Understanding JSON translation dictionary

Translations are stored as JSON dictionaries and live in the directory /i18nix/translations. Each JSON dictionary holds the translation dictionary in the locale of the file name. For example, fr.json will store all French translations. Translations are stored as keys mapped to the translation value. The keys are the strings wrapped in ix.

Let's say you want to translate Hello world!:

ix("Hello world!");

The key is Hello world!. In the spanish language dictionary es.json, the translation would look like:

{
  "Hello World!": {
    "author": "matt@gmail.com",
    "comment": "This is on the home page",
    "locations": ["/components/home.tsx"],
    "value": "¡Hola Mundo!"
  }
}

The values mapped to each translation key have a purpose:

• Author - Our script syncs with your GitHub. The author tracks who on your team made these changes.
• Comment - Comments provide context to how that text is being used. This helps the auto translation or continuos human translation service create context-driven translations.
• Locations - Track where these translations are being used. This is used to optimization. Only download translations needed to power the component users are on.
• Value - The translated text. The value should be the translated key.

Managing pluralization

When you want to do pluralization, make sure you are using the {count} tag. Whatever is passed into {count} determines which value is used.

{
  "There are {count} days left.": {
    "author": "matt@gmail.com",
    "comment": "Counter in the home page.",
    "locations": ["/components/home.tsx"],
    "single_value": "There is {count} day left.",
    "plural_value": "There are {count} days left."
  }
}

In the example above, if {count} == 1, then the value returned will be the value in the field single_value. For plural {count}, the value returned will be the plural_value field. This pluralization branching logic is all handled by the useTranslation hook.

Modifying translations

You are free to manually modify the translation dictionary. Just make sure that the keys in each dictionary match with the key of your string in ix within your codebase. Otherwise, the mapping is disconnected, and your translation will be lost. It is highly recommended to use the Translate script to help you modify translations.

How are things translated

When you add a new string in ix and run the Translate script, it will create new entries in the JSON translation dictionaries. However, the string won't be translated until you've updated each dictionaries' translations. You can do the translations yourself by manually updating the dictionaries, or use a translation service.

We recommend using the i18nix Translation as a Service. This works right out of the box for i18nix translation dictionaries. The service can provide AI generated translations or human translators.