Registry / productivity / i18n

i18n

JSON →
library0.15.3jsnpmunverified

A lightweight Node.js translation module that stores language files in JSON format, supporting dynamic on-the-fly string addition. Current stable version is 0.15.3 (last updated July 2024), with a moderate release cadence. Key differentiators include simplicity (no extra parsing), integration with Express via middleware, and support for both singleton and instance patterns. It provides common __('...') syntax for translation lookups, automatic locale detection from Accept-Language headers, and CLI/script usage. Unlike more complex solutions like i18next, this library is minimal with no external dependencies, but it lacks features like pluralization, interpolation, and loading from remote backends.

productivity
npm install i18n
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · I18N
I
i18n
productivityjavascriptv0.15.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'
✗ import i18n from 'i18n'
Since v0.12.0, named export is used for instance; default import was never defined. For singleton, use 'const i18n = require('i18n')' or dynamic import.
i18n (singleton)
✓ const i18n = require('i18n')
✗ const { i18n } = require('i18n')
Singleton import is a default export style via require. Named import does not exist. If using ESM, use const i18n = require('i18n') or dynamic import.
require('i18n')
✓ const i18n = require('i18n')
✗ const { I18n } = require('i18n') // Wrong for singleton, correct for instance
When using singleton, require returns the shared instance. For instance, destructure I18n class.

Creates an HTTP server with i18n instance, initializes per request, and returns translated greeting based on Accept-Language header.

const http = require('http'); const path = require('path'); const { I18n } = require('i18n'); const i18n = new I18n({ locales: ['en', 'de'], directory: path.join(__dirname, 'locales'), defaultLocale: 'en' }); const app = http.createServer((req, res) => { i18n.init(req, res); res.end(res.__('Hello')); }); app.listen(3000, '127.0.0.1', () => { console.log('Server running on http://127.0.0.1:3000'); });
Debug
Known issues
breakingi18n@0.12.0 changed export: I18n is now a class constructor via named export; singleton usage changed.
fix
Use const { I18n } = require('i18n') for instances; for singleton, const i18n = require('i18n') still works as default export.
affects: >=0.12.0
deprecatedIn v0.11.x and earlier, require('i18n') returned a singleton with configure() – that pattern still works but instance is preferred.
fix
Upgrade to >=0.12.0 and use instance or continue with singleton; no breaking change if using require('i18n') as before.
affects: <0.12.0
gotchaGlobal singleton scope can leak state across concurrent HTTP requests; always use i18n.init() per request or instance scoped to request.
fix
Use new I18n() instance per request or call i18n.init(req, res) to scope locale to request.
affects: >=0.0.0
gotchaAutomatic locale detection uses Accept-Language header; if not present, falls back to default locale. Not suitable for cookie-based or query-based locale selection without manual override.
fix
Manually set locale using i18n.setLocale(req, 'de') before rendering.
affects: >=0.0.0
deprecatedSince v0.9.0, the __() helper is exposed on res object after init; using global i18n.__() without init may not reflect request locale.
fix
Ensure i18n.init() is called for request-bound translations; use res.__() or req.__() helpers.
affects: >=0.9.0
Errors
Common errors & fixes
Cannot find module 'i18n'
Package not installed or import path incorrect.
fix
Run 'npm install i18n' and ensure require/import path is correct.
TypeError: i18n is not a constructor
Using require('i18n') and trying to instantiate with new i18n() but that returns a singleton, not constructor.
fix
Use const { I18n } = require('i18n') for constructor; or use singleton pattern without new.
TypeError: Cannot read properties of undefined (reading '__')
i18n.init() not called before accessing res.__.
fix
Add i18n.init(req, res) before using res.__() in middleware.
Error: No locale set yet, configure() or setLocale() is required
Trying to translate before any locale is configured.
fix
Call i18n.configure({...}) or i18n.setLocale(...) before using __().
Error: ENOENT: no such file or directory, open '.../locales/en.json'
Locale file for 'en' not found in configured directory.
fix
Create the missing JSON file (e.g., locales/en.json) with an empty object {} or your translations.
Upgrade
Version history
0.15.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
45 hits · last 30 days
node
42
OpenAI (training)
1
Resources
githubssh://git@github.com/mashpie/i18n-node ↗
packagei18n ↗
homepagehttp://github.com/mashpie/i18n-node ↗
i18n — npm install i18n · libregistry