Soluling home   Document home

i18next Localization and Internationalization

i18next Localization and Internationalization

i18next (homepage) is a popular JavaScript internationalization library. It is used directly and through framework integrations such as react-i18next for React and i18next-vue for Vue. i18next stores the strings in JSON resource files. Soluling Desktop and Soluling Cloud support i18next resource files.

The end of the document contains links to get the full source code of the samples. After reading this document, we recommend reading a tutorial about how to use Soluling.

Resource file format

An i18next resource file is a JSON file whose values are strings. You can group the strings into nested objects. The following is a part of Sample.json of the sample.

{
  "key": "value",
  "keyDeep": {
    "inner": "value"
  },
  "keyNesting": "reuse $t(keyDeep.inner)",
  "keyInterpolate": "replace this {{value}}",
  "keyContext_male": "the male variant",
  "keyContext_female": "the female variant"
}

Soluling reads the file as follows:

Item Description
Strings Each string value becomes a row. The path of the keys is the context of the row, for example, keyDeep.inner.
Interpolation Placeholders such as {{value}}, {{- value}}, and {{value, format}} must be kept in the translation.
Nesting References to other strings, such as $t(keyDeep.inner), must be kept in the translation.
Context Context variants, such as keyContext_male and keyContext_female, are separate keys, so each of them is a separate row.
Arrays The strings of an array, such as the items of arrayJoin in Array.json, are separate rows.

When building, Soluling writes a localized resource file for each language. The localized file has the same keys and structure as the original file, but the values are translated.

Plurals

i18next stores each plural form as a separate key with a suffix. Starting from i18next 21 (JSON format v4), the suffixes are the plural categories of the language, for example:

{
  "item_one": "{{count}} item",
  "item_other": "{{count}} items"
}

Older versions used _plural (JSON format v3, see Plural.json) or numbers such as _0 and _1 (JSON format v2, see Many.json).

Note! Soluling reads each plural key as an ordinary string. This means that the localized file contains the same plural keys as the original file. If the target language needs more plural forms than the original language, for example, _few and _many in Polish, add those keys to the original file too, or add them to the localized file after building. Otherwise, i18next uses the _other form for them. For full plural support, consider using an ICU message format library, such as React Intl.

Resource file names

i18next applications usually load the resources of each language from a separate directory, for example, locales/en/translation.json and locales/fi/translation.json. By default, Soluling creates the localized files in language-specific subdirectories with the same name as the original file, for example, fi\Sample.json. If your original file is locales\en\translation.json, set the output directory on the Output sheet so that the localized files are written to locales\fi\translation.json and so on.

Desktop process Desktop process

  1. Start Soluling. Drag the original resource file (e.g., Sample.json) on Soluling or click the New from File or Files button and select the file.
  2. If Soluling asks what kind of file it is, select i18next resource file and click OK.
  3. Project Wizard appears. Select the original language and the target languages, for example, Finnish, and complete the wizard.
  4. Translate the project.
  5. Choose Home | Build All to build the localized resource files, for example, fi\Sample.json.

When you change the original resource file, open the Soluling project and choose Home | Scan. Soluling keeps the existing translations, and you only translate the strings that were added or changed.

Cloud process Cloud process

With Soluling Cloud, you localize the resource file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans.

Create a project

  1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
  2. Click Add a new project, then Select files and pick the original resource file (e.g., locales/en/translation.json), or drag and drop the file onto the page. Click Create.
  3. On the next page, check the project's Name. It defaults to the file's name.
  4. Set the Original language to the language of the file, for example, English.
  5. Under Target languages, check the languages you want to translate to, for example, Finnish and German.
  6. Under Source type, select i18next resource file (.json). The file is also a valid generic JSON file, so make sure you pick the i18next parser.
  7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

Translate the project

Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Get the localized files

  1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
  2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
  3. The Files section lists the resource file with a download button for each target language. Save each localized file where your application loads it, for example, locales/fi/translation.json.

Update the project

When you change the strings, upload the new original file, translate what is new or changed, and download the localized files again. On the dashboard, click the project's Update file button (the upload arrow), select the new file or drop it onto the page, and click Update. Existing translations are kept, so you only translate the strings that were added or changed.

The dashboard is one of four ways to use Soluling Cloud. You can also use the SoluCLI command-line tool, Soluling Desktop, or SoluMake, which can run the update and build steps in your build pipeline. See the Cloud tutorial for all of them.

Samples

GitHub and <data-dir>\Samples\i18next contain the following i18next sample files:

File Description Notes
Sample.json A resource file that contains plain and nested strings, nesting ($t()), interpolation, context, and plural keys. The localized Finnish file is in the fi subdirectory. Try this first!
Interpolation.json A resource file that contains placeholders.  
Array.json A resource file that contains arrays of strings and objects.  
Plural.json Plural keys in the i18next JSON v3 format (_plural). No Soluling project
Many.json Plural keys in the i18next JSON v2 format (_0 to _5). No Soluling project

The React samples also contain an i18next application.

Configuring i18next localization

You create a resource file localization project by adding an i18next resource file (e.g., D:\Sample\locales\en\translation.json) into your Soluling project. You can configure how to localize your i18next resource file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.