i18n-js

To use the library, instantiate the I18n class with a translations object. The object structure follows the Ruby on Rails i18n format, where each root key represents a locale (e.g., en, pt-BR, or zh-Hant-TW).

You can provide a full translation object or a basic one for simple use cases.

import { I18n } from "i18n-js";
import translations from "./translations.json";

const i18n = new I18n(translations);

You can install the i18n-js library using either npm or yarn. It is recommended to install the latest version.

npm install i18n-js@latest
# or
yarn add i18n-js@latest

The library supports loading base translations (like those from rails-i18n) to enable standard formatting for dates, numbers, and sentence connectors.

import { I18n } from "i18n-js";
import ptBR from "i18n-js/json/pt-BR.json";
import en from "i18n-js/json/en.json";

const i18n = new I18n({
  ...ptBR,
  ...en,
});

I18n.js requires a nested object structure to represent the translation tree. If your translation data uses a flat structure with dot-notation keys (e.g., "en.messages.hello": "hello"), you must transform it into a nested object before passing it to the library.

You can achieve this using lodash.set or the flat package.

const { set } = require("lodash");

const from = {
  "en.messages.hello": "hello",
  "pt-BR.messages.hello": "olá",
};

function flatToNestedObject(target) {
  const nested = {};

  Object.keys(target).forEach((path) => set(nested, path, target[path]));

  return nested;
}

console.log(flatToNestedObject(from));
// Output:
// {
//   en: { messages: { hello: 'hello' } },
//   'pt-BR': { messages: { hello: 'olá' } }
// }

If you encounter the error Unable to resolve "make-plural" from "node modules/i18n-js/dist/import/Pluralization.js", it is because the make-plural dependency uses .mjs files which your build pipeline might not be configured to recognize.

In React Native environments, you must update your metro.config.js to include mjs in the sourceExts array.

const { getDefaultConfig } = require("metro-config");

module.exports = (async () => {
  const {
    resolver: { assetExts, sourceExts },
  } = await getDefaultConfig();

  return {
    resolver: {
      sourceExts: [...sourceExts, "mjs"],
    },
  };
})();

Errors like SyntaxError: Unexpected end of JSON input or Uncaught SyntaxError: Unexpected token ; are typically caused by invalid JSON files rather than i18n-js itself.

• Empty Files: Ensure you are not attempting to import an empty .json file.
• Invalid Syntax: Ensure your files contain valid JSON data. For example, writing {}; is invalid JavaScript/JSON and will trigger a syntax error. JSON must be a valid object or array without trailing semicolons.

You can dynamically update or lazy-load translations by calling I18n#store(translations). This merges the provided object into the existing store.

import { I18n } from "i18n-js";
import ptBR from "translations/pt-BR.json";
import en from "translations/en.json";

const i18n = new I18n();

i18n.store(en);
i18n.store(ptBR);

Use I18n#localize (alias I18n#l) to format dates, strings, or epoch integers based on defined formats in your translation object.

• Input types: String (ISO-8601 or custom), Epoch integer, or Date object.
• Custom Placeholders: You can include placeholders like %{day} in your date format definitions and pass them in the options.
• Direct Helpers: Use I18n#toTime for parsing and I18n#strftime for standard strftime-style formatting.

// Using a format defined in translations
i18n.l("date.formats.short", new Date());

// Using strftime
i18n.strftime(new Date(), "%d/%m/%Y");

// Relative time
i18n.timeAgoInWords(fromTimestamp, toTimestamp); // "about 1 hour"

A change event is triggered whenever I18n#store, I18n#update, I18n#locale, or I18n#defaultLocale is called. Use I18n#onChange(callback) to subscribe. The method returns an unsubscribe function to remove the handler. Additionally, I18n#version increments on every change, making it useful as a cache key.

const i18n = new I18n();
const unsubscribe = i18n.onChange(() => {
  console.log("I18n has changed!");
});

// To remove the listener:
unsubscribe();

Use I18n#t (or its alias I18n#translate) to fetch translations.

• Scopes: You can pass a string ("greetings.hello") or an array (["greetings", "hello"]).
• Interpolation: Use %{key} in your translation strings and pass an object containing the values to t().
• Array Interpolation: If a translation entry is an array of strings, values are interpolated into each string in the array.
• Custom Interpolation: You can override I18n#interpolate to support custom logic, such as returning React elements.

// Basic translation
i18n.t("hello");

// Interpolation
const i18n = new I18n({
  en: { greetings: "Hi, %{name}!" },
});
i18n.t("greetings", { name: "John" });

// Array interpolation
const i18n = new I18n({
  en: { messages: ["Hello!", "Welcome, %{name}!" ] },
});
i18n.t("messages", { name: "John" });

Pluralization uses special keywords in your translation files: zero, one, and other. To trigger pluralization, pass a count option to I18n#t.

To support languages with different pluralization rules (like Russian), register a custom handler using I18n#pluralization.register(locale, handler).

const i18n = new I18n({
  en: {
    inbox: {
      zero: "You have no messages",
      one: "You have one message",
      other: "You have %{count} messages",
    },
  },
});

i18n.t("inbox", { count: 0 }); // "You have no messages"