This last week I worked on my team's internationalization (aka i18n) solution. We call it react-i18n (if we ever open source it, we'll need to rename it, because that's already taken). It's pretty neat and really small. I'm not going to talk about why we don't use any of the myriad of other tools that do this (maybe I'll save that for another blog post). What I want to talk about is something I did to make that module more usable.

One feature of the module is that it will automatically load your server-rendered content for you. At PayPal we have another module called react-content-loader. This is an express middleware that relies on conventions used in Kraken and inserts the content for the user based on their language preferences. For example, let's say that you have a file:

// locales/US/en/pages/home.properties
header.title=PayPal Rocks
header.subtitle=No really, it does

Then this middleware would insert this in the bottom of your page (for US users with en as their preferred language):

<script type="application/json" id="react-messages">
  {
    "pages/home": {
      "header": {
        "title": "PayPal Rocks",
        subtitle: "No really, it does"
      }
    }
  }
</script>

Then react-i18n will automatically load that on the client side. All you have to do is use it:

import getContentForFile from 'react-i18n'
const i18n = getContentForFile('pages/home')

function App() {
  return (
    <div>
      <h1>{i18n('header.title')}</h1>
      <div>{i18n('header.subtitle')}</div>
    </div>
  )
}

So that's how it works (again, I'm sure some of you are thinking of other libs that could do this better, but please spare me the "well actually." I'm aware of them, I promise). Now that you understand basically how this works, I want to talk about a few things that I changed about it to make it more usable.

No side-effects on import

So you'll notice that when we use react-i18n on the client in the example above, we don't have to do anything to initialize or bootstrap it with content. It automatically gets those from the DOM. It does this inside the main export from react-i18n. This way when you import react-i18n, loading the content happens for you. This is a handy feature. But it comes with the trade-off that the main module in react-i18nhas side-effects in the root-level of the module. For example:

// react-i18n/index.js
// ... stuff
// side-effect!
const content = JSON.parse(document.getElementById('react-messages'))
// ... more stuff
export {getContentForFile as default, init}

This presents a few challenges for users of the module. It means that they have to be aware of what happens when they import your module. They have to make sure that they don't import your module before the global environment is ready for it. And that problem manifests itself not only in the application environment, but also in the test environment! And unless you take care to give good warnings when the environment isn't ready (if you even know), people will get cryptic error messages when doing seemingly unrelated tasks (like importing some module that happens to import your module somewhere in the dependency graph).

Another issue is that there could be a reason to configure the initialization process. What if my node doesn't have the id react-messages, but instead uses i18n-content? Or what if I don't server-render the messages at all and they're coming from an ajax request? Turns out that react-i18n actually exposed another module react-i18n/bootstrap to customize this behavior which is great, but that doesn't resolve the problem of stuff happening if someone were to import react-i18n first.

So what I did was a wrapped all side-effects in a function I exported called init(which was similar to the bootstrap thing it already exported):

// react-i18n/index.js
// ... stuff
function init(options) {
  // ... other stuff
  // side-effect! But it's ok now because that's clear
  const messages = JSON.parse(document.getElementById('react-messages'))
  // ... other other stuff
}
// ... more stuff
export {getContentForFile as default, init}

So this means that anyone using the module now must call the init function, but they're doing that on their own terms and whenever they want it to happen which I think is the key difference. It doesn't matter whether someone imports this module before initialization takes place. It also gives us an opportunity to give a more informative error message if they fail to initialize before they start using the module.

The key is that your module shouldn't do side-effects when it's imported. Instead, export functions which perform the side-effects. This gives the users control over when and what happens. Even better is to not have any side-effects at all if you can help it (which is actually also possible to accomplish with my reworking of react-i18n), but that's a subject for another newsletter.

Make it generic

Before, this library was actually just a part of our app. So we could easily rely on the fact that the JSON object was a nested object where the first key was the name of the localization file and the rest was just a nested version of the contents of that file (as you can tell in the example above). And the implementation and examples in the docs were all geared toward this use case. However, we're in the process of "inner sourcing" this module (and perhaps open sourcing it eventually), so folks are going to use it who use different tools and have different use cases.

So, if it's not too much work and doesn't add too much complexity, then try to make the solution more generic. So now, the implementation doesn't care about the fact that the root level of the localization object is a file name and the rest is the contents of that file. All it cares about is the fact that it's a nested JavaScript object. This means that whereas before, you had to do this:

import getContentForFile from 'react-i18n'
const i18n = getContentForFile('pages/home')

// etc...
i18n('header.title')
// etc...

You can now do this:

import getContent from 'react-i18n'

// etc...
getContent('pages/home.header.title')
getContent('pages/home')('header.title')
getContent('pages/home.header')('title')
// etc...

So each invocation of getContent will return the content or if the content is another nested object it'll return another content getter function. I call this "sota-curried" because it's not really currying, but it kinda looks like it a little bit.

Now PayPal's react-i18n is more generically useful because the implementation and documentation don't assume you're using react-content-loader. And as it turned out, doing things this way actually made the implementation simpler! Wahoo!

I should mention also that you can't predict the future, and that's what you sort of have to try to do when building a generic library. While you're doing this, you need to balance usability with the YAGNI principle. I only put this effort in because we were extracting this from our project so others could use it and we needed to support these use cases. Beware of pre-mature optimizations (that's not limited to performance situations, but also features/complexity as well).

There were several other things I could talk about, but I'm going to wrap this email up with this. I hope that you find ways to remove side-effects from the root-level of most of your modules and find ways to make your solution more generic without sacraficing usability or implementation complexity.

Good luck! And stay awesome 😎