{"id":17708,"library":"i18n-express","title":"Express.js i18n Middleware","description":"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.","status":"abandoned","version":"1.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/koalazak/i18n-express","tags":["javascript","i18n","express","middleware","json","internationalisation","node","session","language"],"install":[{"cmd":"npm install i18n-express","lang":"bash","label":"npm"},{"cmd":"yarn add i18n-express","lang":"bash","label":"yarn"},{"cmd":"pnpm add i18n-express","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core web framework dependency.","package":"express","optional":false},{"reason":"Required for reading and setting language preference cookies.","package":"cookie-parser","optional":false},{"reason":"Often used in conjunction for session-based language persistence, as demonstrated in example usage.","package":"express-session","optional":true}],"imports":[{"note":"While originally CommonJS, modern Node.js allows default import syntax. The module exports a single middleware function as its default.","wrong":"import { i18n } from 'i18n-express';","symbol":"i18n","correct":"import i18n from 'i18n-express';"},{"note":"This is the original and most common import pattern for this CommonJS package.","symbol":"i18n (CommonJS)","correct":"const i18n = require('i18n-express');"},{"note":"The imported `i18n` is a function that *returns* the middleware, requiring an options object even if empty.","wrong":"app.use(i18n);","symbol":"Middleware Usage","correct":"app.use(i18n({\n  translationsPath: path.join(__dirname, 'i18n'),\n  siteLangs: ['en', 'es']\n}));"}],"quickstart":{"code":"const express = require('express');\nconst path = require('path');\nconst cookieParser = require('cookie-parser');\nconst session = require('express-session'); // Required for session-based language persistence\nconst i18n = require('i18n-express');\n\nconst app = express();\n\n// Create a dummy translations directory and files\nconst translationsPath = path.join(__dirname, 'i18n-translations');\nconst fs = require('fs');\nif (!fs.existsSync(translationsPath)) fs.mkdirSync(translationsPath);\nfs.writeFileSync(path.join(translationsPath, 'en.json'), JSON.stringify({ \"WELCOME_MSG\": \"Hi! Welcome!\" }));\nfs.writeFileSync(path.join(translationsPath, 'es.json'), JSON.stringify({ \"WELCOME_MSG\": \"¡Hola! ¡Bienvenido!\" }));\n\napp.set('views', path.join(__dirname, 'views'));\napp.set('view engine', 'ejs');\n\napp.use(cookieParser());\napp.use(session({\n  secret: process.env.SESSION_SECRET ?? 'supersecretkey',\n  resave: false,\n  saveUninitialized: true,\n  cookie: { maxAge: 60000 }\n}));\n\napp.use(i18n({\n  translationsPath: translationsPath, // Path to your JSON translation files\n  siteLangs: [\"en\", \"es\"],\n  textsVarName: 'translation', // Variable name in views\n  cookieLangName: 'ulang' // Cookie name for language persistence\n}));\n\napp.get('/', (req, res) => {\n  res.render('index', { \n    lang: res.locals.lang, \n    translation: res.locals.translation \n  });\n});\n\n// Dummy EJS view file (views/index.ejs)\n// Create 'views' directory and 'index.ejs' with this content:\n/*\n<div>\n  <h1><%= translation.WELCOME_MSG %></h1>\n  <p>Current Language: <%= lang %></p>\n  <p>\n    <a href=\"/?clang=en\">English</a> |\n    <a href=\"/?clang=es\">Español</a>\n  </p>\n</div>\n*/\n\nconst PORT = 3000;\napp.listen(PORT, () => {\n  console.log(`Server running on http://localhost:${PORT}`);\n  console.log(`Try http://localhost:${PORT}/?clang=es to switch language`);\n});\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Consider migrating to actively maintained i18n solutions for Express, such as 'i18n' or 'express-i18n'.","message":"The 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.","severity":"breaking","affected_versions":">=1.1.3"},{"fix":"Ensure `app.use(cookieParser());` and `app.use(session(...));` are called prior to `app.use(i18n(...));`.","message":"Requires `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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';`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Familiarize yourself with the language detection hierarchy and ensure your application's language switching mechanisms align with it. Test all detection methods thoroughly.","message":"Language 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Always call `i18n` with an options object: `app.use(i18n({ /* options */ }));`","cause":"Attempting to use `i18n` directly as middleware instead of calling it with options to return the middleware function.","error":"TypeError: i18n is not a function"},{"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.","cause":"The `textsVarName` (e.g., 'translation') object is undefined in the view, usually because the translation files are not found or `translationsPath` is incorrect.","error":"Cannot read properties of undefined (reading 'WELCOME_MSG')"},{"fix":"Add `const session = require('express-session');` and configure `app.use(session(...));` before using i18n-express.","cause":"The example code in the README uses `session` middleware without explicitly requiring `express-session`.","error":"ReferenceError: session is not defined"},{"fix":"Verify that `app.use(cookieParser());` (and `app.use(session(...));` if used) are placed *before* `app.use(i18n(...));` in your Express application configuration.","cause":"Missing `cookie-parser` middleware or incorrect order of middleware execution, preventing i18n-express from accessing cookies or session.","error":"Language is not changing despite setting query param or cookie."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}