Introduction


This changes i18n format from i18next json to ICU using formatjs/intl-messageformat

Advice

When using this module, only the ICU message format is respected, this means the i18next format interpolation will not work.
So for example instead of Hy {{name}}! it is Hy {name}!

Getting started

Source can be loaded via npm or downloaded from this repo.

``


npm package

$ npm install i18next-icu

peer dependencies

$ npm install intl-messageformat
`

Wiring up:

`js
import i18next from "i18next";
import ICU from "i18next-icu";

i18next.use(ICU).init(i18nextOptions);
`

- As with all modules you can either pass the constructor function (class) to the i18next.use or a concrete instance.
- If you don't use a module loader it will be added to window.i18nextICU

Backend Options

`js
{
// per default icu functions are parsed once and cached for subsequent calls
memoize: true,

// memoize if not having a lookup and just using the key fallback as value
memoizeFallback: false,

// which events should clear the cache, can be set to false or string of events separated by " "
bindI18n: '',

// which events on resourceSource should clear the cache, can be set to false or string of events separated by " "
bindI18nStore: '',

// Will be run when parser throws an error. Can return any string, which can be used as a fallback, in case of broken translation.
// If omitted, the default swallows the error and returns the unsubstituted string (res)
parseErrorHandler: (err, key, res, options) => {},

// Transform the language code prior to ICU locale parsing, useful for supporting psuedo-locales like en-ZZ
// If omitted, the default leaves the language code as is
parseLngForICU: (lng) => lng,

// Automatically escape HTML special characters in variable values to prevent ICU parsing issues
// When true, characters like <, >, &, ", ' in variables are escaped to their HTML entities
// This prevents strings like "user:<" from being truncated or causing parsing errors
// Default: false (to maintain backward compatibility)
escapeVariables: false,
}
`

Options can be passed in by setting options.i18nFormat in i18next.init:

`js
import i18next from "i18next";
import ICU from "i18next-icu";

i18next.use(ICU).init({
i18nFormat: options
});
`

$3

`js
import i18next from "i18next";
import ICU from "i18next-icu";

i18next.use(ICU).init({
lng: "en",
resources: {
en: {
translation: {
key:
"You have {numPhotos, plural, " +
"=0 {no photos.}" +
"=1 {one photo.}" +
"other {# photos.}}"
}
}
}
});

i18next.t("key", { numPhotos: 1000 }); // -> You have 1,000 photos.
`

hints

Using i18next-icu - non of the i18next specific stuff will be available. You will have to rely on what intl-messageformat provides by calling the t function with needed options.

All extra features build around i18next plurals, interpolation, context do not get applied to messageformat based keys.

Migration guide

$3

- updated intl-messageformat` dependency. Adding locales-data is no longer needed.

---

Gold Sponsors