npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

i18next-icu

v2.7.0

Published

i18nFormat plugin to use ICU format with i18next

Readme

Introduction

npm version

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:

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

{
  // per default icu functions are parsed once and cached for subsequent calls
  // (a message changed by addResource, reloadResources or HMR is parsed again)
  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,

  // Require an `other` case in every plural, select and selectordinal argument (passed to the intl-messageformat parser)
  // Set to false to accept messages that only list explicit cases, e.g. {count, plural, one {# item}}
  // Default: true (a message without `other` fails to parse and goes to parseErrorHandler)
  // With false, a value no case matches (count: 5 for the example above) fails when formatting and also goes to parseErrorHandler
  requiresOtherClause: true,
}

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

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

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

more complete sample

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.

What keeps working and what does not is listed in Using ICU or MF2 in the i18next docs.

debug warnings

With i18next debug: true, i18next-icu logs a warning through the i18next logger, once per key, when:

  • a message can not be parsed or formatted (the default parseErrorHandler silently returns the unformatted message), with a hint if it contains i18next interpolation like {{name}}
  • t is called with count and plural suffix keys (key_one, key_other, key_ordinal_one, ...) exist for that key
  • t is called with context and a context key (key_male) exists
  • a message contains $t( nesting
  • a key resolves to an object or array (returnObjects, joinArrays)
  • interpolation.escapeValue is on, which the plugin does not apply (logged once, not logged with escapeVariables: true)

Without debug these checks do not run.

React Native, Hermes and other runtimes without Intl

intl-messageformat formats with the runtime's Intl APIs: Intl.PluralRules picks the one, few, other, ... case of plural and selectordinal, Intl.NumberFormat formats # and {n, number}, Intl.DateTimeFormat formats {d, date} and {t, time}. When an API is missing, formatting throws and the default parseErrorHandler returns the unformatted message (with debug: true the error is logged).

  • Hermes (the default React Native engine) implements Intl.NumberFormat and Intl.DateTimeFormat on Android and iOS, but not Intl.PluralRules or Intl.Locale (see Hermes Intl APIs). Exact matches like =0 and =1 work, every other plural case returns the raw message. Polyfill both in your entry file, before i18next is initialized, with locale data for each language you ship:

    import '@formatjs/intl-locale/polyfill.js';
    import '@formatjs/intl-pluralrules/polyfill-force.js';
    import '@formatjs/intl-pluralrules/locale-data/en.js';
    import '@formatjs/intl-pluralrules/locale-data/de.js';
  • Runtimes without Intl: Hermes on React Native for Windows (microsoft/hermes-windows#222), and on Android older Hermes builds and JavaScriptCore without the Intl variant. Without Intl no message can be created, so even Hello {name} comes back unformatted (#66); with only an Intl.PluralRules polyfill, plurals pick the right case but a message with # comes back unformatted (#47). Polyfill, in this order, @formatjs/intl-getcanonicallocales, @formatjs/intl-locale, @formatjs/intl-pluralrules, @formatjs/intl-numberformat and, for dates, @formatjs/intl-datetimeformat, the last three with locale data for your languages. See FormatJS runtime requirements.

TypeScript

Since i18next v26.5.0, set parseInterpolation: 'icu' in your CustomTypeOptions and the options of t() (and the values of react-i18next's Trans and IcuTrans) are type-checked against the ICU arguments of each message:

// i18next.d.ts
import 'i18next';

declare module 'i18next' {
  interface CustomTypeOptions {
    parseInterpolation: 'icu';
    defaultNS: 'translation';
    resources: {
      translation: {
        key: 'You have {numPhotos, plural, =0 {no photos.} =1 {one photo.} other {# photos.}}';
      };
    };
  }
}
t('key', { numPhotos: 3 }); // ok
t('key', { numPhotos: 'three' }); // type error: numPhotos takes a number
t('key'); // type error: 'pass these arguments as t() options': { numPhotos: number }

{name} takes a string or number, {n, number}, plural and selectordinal a number, {d, date} and {t, time} a Date, select one of its cases or any string (for other), and arguments nested in cases are required too. interpolationFormatTypeMap changes a type by format name, for example date: Date | number. The messages need literal types, as the resources file from i18next-cli's types command has them; with typeof a JSON import every message is a string and the arguments are not checked.

With i18next v26.2.0 to v26.4.x, set parseInterpolation: false instead. i18next's own extractor looks for {{variable}}, and nested-brace plurals like {count, plural, one {{count} row} other {{count} rows}} would make it ask for a variable that does not exist (#85). With false, keys are checked but the options are not.

Both settings are type-only; runtime interpolation is handled by intl-messageformat via the i18next-icu plugin and is not affected.

Migration guide

1.x.x -> 2.0.0

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