i18n-js

library4.5.3jsnpmunverified

i18n-js is a lightweight JavaScript/TypeScript library for internationalization (i18n) and localization (l10n). Version 4.5.3 is stable with regular updates. It provides interpolation, pluralization, and date/number formatting. Unlike react-i18next or i18next, i18n-js is framework-agnostic and simple, focusing on minimal overhead and ease of use. It supports CommonJS and ESM, has TypeScript definitions built-in, and works in both Node.js and browser environments. Key differentiators are its small size (~5 KB gzipped), no dependencies beyond the locale data, and a familiar Rails-style I18n API.

productivity

npm install i18n-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · I18N-JS

i18n-js

productivityjavascriptv4.5.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

I18n

✓ import I18n from 'i18n-js'

✗ const I18n = require('i18n-js').default

Default export. In TypeScript, you can also use import I18n from 'i18n-js'. The CommonJS require gives back the same object directly.

I18n

✓ const I18n = require('i18n-js')

✗ const I18n = require('i18n-js').default

CommonJS require returns the default export directly, no .default needed.

I18n

✓ import * as I18n from 'i18n-js'

Namespace import also works, but default import is preferred.

transliterations

✓ import { transliterations } from 'i18n-js'

✗ const transliterations = require('i18n-js').transliterations

Named export for transliterations object.

Shows basic setup of translations, locale switching, interpolation, and pluralization using the I18n.t() method.

import I18n from 'i18n-js'; // Set up locale translations I18n.translations = { en: { greeting: 'Hello %{name}!', inbox: { one: '1 message', other: '%{count} messages' } }, pt: { greeting: 'Olá %{name}!', inbox: { one: '1 mensagem', other: '%{count} mensagens' } } }; // Set default locale I18n.locale = 'en'; // Translate console.log(I18n.t('greeting', { name: 'John' })); // => "Hello John!" console.log(I18n.t('inbox', { count: 1 })); // => "1 message" console.log(I18n.t('inbox', { count: 5 })); // => "5 messages" // Change locale I18n.locale = 'pt'; console.log(I18n.t('greeting', { name: 'João' })); // => "Olá João!"

Debug

Known issues

breakingIn v4, the library dropped default export being a function (like I18n.t() previously). Now you must use the I18n object.

fix

Replace direct I18n.t() calls with I18n.t() after importing the default export. Update imports from 'i18n-js' to import I18n from 'i18n-js'.

affects: <=3.x => 4.0

breakingV4 changed the pluralization API: the 'one' and 'other' keys are now required; previously you could omit them and use string fallback.

fix

Ensure all pluralization keys include at least 'one' and 'other' per locale.

affects: <=3.x => 4.0

breakingV4 removed the I18n.prototype.defaultLocale; use I18n.defaultLocale instead.

fix

Replace I18n.defaultLocale with I18n.defaultLocale property (no prototype).

affects: <=3.x => 4.0

deprecatedI18n.locales (array of available locales) is deprecated in v4. Use I18n.availableLocales instead.

fix

Replace I18n.locales with I18n.availableLocales.

affects: >=4.0

gotchaThe library does not include locale data by default; you must provide translations. Unlike i18next, it has no fallback detection logic.

fix

Always set I18n.translations for each locale you intend to use. Use I18n.fallbacks or implement custom fallback logic.

affects: *

gotchaNested keys using dots (e.g., 'inbox.one') require object structure in translations. Using dot-delimited strings in I18n.t() is supported but can be ambiguous if keys contain dots.

fix

Avoid keys with dots inside them, or use I18n.t('inbox.one') with proper nested objects.

affects: *

gotchaInterpolation variable names must match exactly (case-sensitive). Using %{Name} vs %{name} will not work.

fix

Use consistent variable names in translation strings and the options object.

affects: *

Errors

Common errors & fixes

Uncaught Error: I18n is not a function

Default import used incorrectly with require() in CommonJS (missing .default)

fix

Use const I18n = require('i18n-js'); not require('i18n-js').default

undefined method `t' for I18n:Module

Using older v3 API where I18n.t was directly on the module

fix

Upgrade to v4, import I18n from 'i18n-js' and use I18n.t() as method.

Module not found: Can't resolve 'i18n-js'

Package not installed or missing dependency

fix

Run npm install i18n-js

TypeError: Cannot read properties of undefined (reading 'translations')

Trying to access translations before setting them

fix

Ensure I18n.translations is set before calling I18n.t()

I18n.t is not a function

Using I18n.t as a standalone function after import as I18n object or using old default

fix

Import correctly: import I18n from 'i18n-js'

Upgrade

Version history

4.5.3latest on npm

Audit

Dependencies

intl-messageformatoptionalUsed for ICU message formatting, optional but recommended for advanced pluralization and formatting

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fnando/i18n ↗

packagei18n-js ↗

homepagehttps://github.com/fnando/i18n#readme ↗