Registry / web-framework / i18n-express

i18n-express

JSON →
library1.1.3jsnpmunverified

i18n-express is a lightweight internationalization middleware designed for Express.js applications, currently at version 1.1.3. It facilitates basic language switching and content localization by reading language-specific JSON files from a designated directory. The middleware determines the user's preferred language based on a hierarchy: a configured cookie, a URL query parameter, browser `Accept-Language` headers, or a default language. Once determined, it exposes a `textsVarName` (default: `texts`) variable to your view engine (e.g., EJS, Handlebars) containing the translated strings for the active language, along with a `lang` variable indicating the current language. Its primary differentiator is its extreme simplicity and file-based approach, avoiding complex CLDR data or advanced pluralization rules, making it suitable for very straightforward localization needs. The package has not seen updates in approximately seven years, suggesting it is no longer actively maintained and new releases are highly unlikely.

npm install i18n-express
INSTALL
IMPORT
SIG · I18N-EXPRESS
I
i18n-express
web-frameworkjavascriptv1.1.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

i18n
import i18n from 'i18n-express';
import { i18n } from 'i18n-express';
While originally CommonJS, modern Node.js allows default import syntax. The module exports a single middleware function as its default.
i18n (CommonJS)
const i18n = require('i18n-express');
This is the original and most common import pattern for this CommonJS package.
Middleware Usage
app.use(i18n({ translationsPath: path.join(__dirname, 'i18n'), siteLangs: ['en', 'es'] }));
app.use(i18n);
The imported `i18n` is a function that *returns* the middleware, requiring an options object even if empty.

This quickstart initializes an Express app with i18n-express, demonstrating how to set up translation files, configure the middleware, and access translated texts and the current language in an EJS view.

const express = require('express'); const path = require('path'); const cookieParser = require('cookie-parser'); const session = require('express-session'); // Required for session-based language persistence const i18n = require('i18n-express'); const app = express(); // Create a dummy translations directory and files const translationsPath = path.join(__dirname, 'i18n-translations'); const fs = require('fs'); if (!fs.existsSync(translationsPath)) fs.mkdirSync(translationsPath); fs.writeFileSync(path.join(translationsPath, 'en.json'), JSON.stringify({ "WELCOME_MSG": "Hi! Welcome!" })); fs.writeFileSync(path.join(translationsPath, 'es.json'), JSON.stringify({ "WELCOME_MSG": "¡Hola! ¡Bienvenido!" })); app.set('views', path.join(__dirname, 'views')); app.set('view engine', 'ejs'); app.use(cookieParser()); app.use(session({ secret: process.env.SESSION_SECRET ?? 'supersecretkey', resave: false, saveUninitialized: true, cookie: { maxAge: 60000 } })); app.use(i18n({ translationsPath: translationsPath, // Path to your JSON translation files siteLangs: ["en", "es"], textsVarName: 'translation', // Variable name in views cookieLangName: 'ulang' // Cookie name for language persistence })); app.get('/', (req, res) => { res.render('index', { lang: res.locals.lang, translation: res.locals.translation }); }); // Dummy EJS view file (views/index.ejs) // Create 'views' directory and 'index.ejs' with this content: /* <div> <h1><%= translation.WELCOME_MSG %></h1> <p>Current Language: <%= lang %></p> <p> <a href="/?clang=en">English</a> | <a href="/?clang=es">Español</a> </p> </div> */ const PORT = 3000; app.listen(PORT, () => { console.log(`Server running on http://localhost:${PORT}`); console.log(`Try http://localhost:${PORT}/?clang=es to switch language`); });
Debug
Known issues
breakingThe package is effectively abandoned, with no updates in approximately seven years. This means there will be no fixes for bugs, security vulnerabilities, or compatibility issues with newer Node.js or Express versions.
fix
Consider migrating to actively maintained i18n solutions for Express, such as 'i18n' or 'express-i18n'.
affects: >=1.1.3
gotchaRequires `cookie-parser` and `express-session` middleware to be configured and used *before* i18n-express in the Express middleware chain for cookie and session-based language persistence features to work correctly.
fix
Ensure `app.use(cookieParser());` and `app.use(session(...));` are called prior to `app.use(i18n(...));`.
affects: >=1.0.0
gotchaThe package is a CommonJS module. While Node.js can often import CJS modules into ESM projects, direct `import { i18n } from 'i18n-express'` or complex ESM setups might lead to issues.
fix
Use `const i18n = require('i18n-express');` in CommonJS projects. In ESM, use dynamic `import()` or ensure your build system correctly handles CJS interoperability with `import i18n from 'i18n-express';`.
affects: >=1.0.0
gotchaLanguage detection follows a specific priority: `cookieLangName` (if set) > `paramLangName` (from URL query) > browser `Accept-Language` header > `defaultLang`. Misunderstanding this order can lead to unexpected language display.
fix
Familiarize yourself with the language detection hierarchy and ensure your application's language switching mechanisms align with it. Test all detection methods thoroughly.
affects: >=1.0.0
gotchaThis library offers very basic internationalization. It lacks features such as pluralization rules, complex locale-aware formatting (dates, currencies), or integration with CLDR data, which are common in more robust i18n libraries.
fix
For applications requiring advanced i18n features, consider libraries like `i18n` (npm package) or `formatjs` (react-intl), which offer more comprehensive solutions. This library is best suited for simple key-value translations.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: i18n is not a function
Attempting to use `i18n` directly as middleware instead of calling it with options to return the middleware function.
fix
Always call `i18n` with an options object: `app.use(i18n({ /* options */ }));`
Cannot read properties of undefined (reading 'WELCOME_MSG')
The `textsVarName` (e.g., 'translation') object is undefined in the view, usually because the translation files are not found or `translationsPath` is incorrect.
fix
Ensure `translationsPath` points to the correct directory containing valid `.json` language files (e.g., `en.json`, `es.json`) and that the `textsVarName` in your view matches the configuration.
ReferenceError: session is not defined
The example code in the README uses `session` middleware without explicitly requiring `express-session`.
fix
Add `const session = require('express-session');` and configure `app.use(session(...));` before using i18n-express.
Language is not changing despite setting query param or cookie.
Missing `cookie-parser` middleware or incorrect order of middleware execution, preventing i18n-express from accessing cookies or session.
fix
Verify that `app.use(cookieParser());` (and `app.use(session(...));` if used) are placed *before* `app.use(i18n(...));` in your Express application configuration.
Upgrade
Version history
1.1.3latest on npm
Audit
Dependencies
expressrequiredCore web framework dependency.
cookie-parserrequiredRequired for reading and setting language preference cookies.
express-sessionoptionalOften used in conjunction for session-based language persistence, as demonstrated in example usage.
Agent activity
6 hits · last 30 days
node
6
Resources