i18next JSON

i18next is a library and format commonly used for handling translations in JavaScript-based projects. Translations are usually stored as part of JavaScript code or in .json files. Tolgee supports importing the .json representation of translation mapping.

The i18next format uses suffixes for plurals (e.g. my_key_zero, my_key_one, my_key_many) and has specific placeholders for keys (e.g. value is {{placeholder_key}}). You can import and export your localization data in the i18next format directly using Tolgee.

However, when possible, we recommend using the ICU format with the ICU plugin for i18next. The ICU format offers much better support for advanced message formatting and plurals.

Read more about i18next in i18next official documentation.

Example of i18next JSON

en.json

{
  "save": {
    "button": "Save"
  },
  "dogs_count_zero": "No dogs",
  "dogs_count_one": "One dog",
  "dogs_count_other": "{{count}} dogs",
  "array": [
    "First item",
    "Second item"
  ]
}

When importing this JSON, Tolgee will convert nested keys into flat key structure and all plurals and placeholders to ICU message format (can be disabled).

When exporting to i18next JSON, Tolgee will convert ICU message format back to i18next format. Depending on your preference, you can choose to either use the flat JSON structure or nested JSON structure. However, for projects needing more advanced message formatting, we strongly recommend using the ICU format with the i18next ICU plugin. The Tolgee platform doesn't support exporting these advanced features in the i18next format.

The message format and placeholder conversion

When importing data to Tolgee from the i18next JSON files, you can either enable or disable the conversion to the Tolgee Universal ICU placeholders. The conversion is enabled by default. You can also disable the conversion globally in the project settings. We recommend keeping the conversion enabled, as it brings many benefits. Read more about the benefits of Tolgee Universal ICU placeholders.

When the conversion is disabled, the original placeholders (e.g., {{name}}, {{count, number}}). are preserved. The message format is automatically detected when importing data in i18next JSON format. When exporting, you can choose from message & placeholder formats listed above.

Placeholder conversion specification

Only placeholders specified in the table below are supported. Tolgee doesn't support additional flags and modifiers and won't convert such placeholders. Unsupported placeholders will neither be lost nor modified. When a file with unsupported placeholders is imported and exported, all keys' values will remain the same.

ICU type	Example	Converted to ICU	Note
none	{{name}}	{name}
number	{{count, number}}	{count, number}	No options are supported

Importing / Exporting in general

To read more about importing and exporting with Tolgee, continue to import section or export section.