Skip to main content

i18n

Recommendation
Updated
Moved
USE
2022-04-27

What is it​

i18n is an abbreviation of internationalization and is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.

When to use it​

Use i18n when building user interfaces that will be used by non-Einride users. It's usually much easier to add support for i18n right away compared to adding support for i18n in an existing application.

How to use it​

Here are a few conventions to try to follow.

The translation keys use a mix of camelCase and snake_case on the form thisIsTheTranslationKey_modifier where the modifier could be a pluralisation modifier, a context modifier or a meaning modifier (error, button or similar).

For keys shared among multiple pages, use the common nesting group. For translations belonging to a specific component use the component group and for page specific translations use the page group. If there's good reasons to keep a group of keys on the top level do so. A good example for that would be global errors.

{
  "pages": {
    "page1": {
      //...
    }
  },
  "components": {
    "AComponentName": {
      //...
  },
  "common": {
    //...
  },
  "errors": {
    //...
  }
}

Nested translation keys​

I18n supports nesting of translation keys. This can quickly get complicated and add a lot of complexity for the translator. It might also cause unintended side effects. Changing a nested key might have grammar or layout effects that isn't easy to detect. As an example of how quickly the translations become complex is this:

{
  "claimShipments": "$t(common.claim) {{count}} $t(common.shipment, {\"count\": {{count}}})"
}

This evaluates to claim 1 shipment or claim 2 shipments. But that's not directly obvious from the translation and it's easy to make mistakes. Note the escaped " and the fact that we need to pass count down to the second key. And this is just a very "simple" example.

The preferred way of writing this would instead be:

{
  "claimShipment_one": "Claim {{count}} shipment",
  "claimShipment_other": "Claim {{count}} shipments"
}

How to learn it​

See react-i18next for a specific library that will help implementing i18n.