i18n-t

Common errors

• TypeError: I18n is not a constructor

  cause Attempting to call `I18n()` as a function instead of using `new I18n()`.
  fix Instantiate the I18n class using the `new` keyword: `const i18n = new I18n({ defaultLocale: 'en' });`

• Error: require() of ES Module [...] not supported.

  cause Trying to `require()` an ES Module or `import` a CommonJS module in an incompatible environment or without proper transpilation.
  fix This package is CommonJS. Ensure you are using `const I18n = require('i18n-t');` and that your project is configured for CommonJS, or migrate to an i18n library that supports ESM.

• Cannot find module 'i18n-t' or similar module resolution error

  cause The package is not installed or the `node_modules` directory is not correctly resolved, or trying to `import` in a pure ESM context that doesn't understand CJS.
  fix Run `npm install i18n-t` to ensure the package is installed. If in an ESM project, consider using a different i18n library or a CJS-to-ESM wrapper if absolutely necessary, though migration is recommended.

Warnings

• breaking The `i18n-t` package has been abandoned since its last update in June 2016 (version 1.0.1). It receives no further development, bug fixes, or security updates. This poses significant risks for production applications.
  Fix: Migrate to a actively maintained internationalization library like `i18next`, `i18n-js`, or `node-i18n` for better long-term support, features, and security.
• gotcha This library is CommonJS-only and does not provide ES Module (ESM) exports. Attempting to use `import` syntax will result in module resolution errors in modern JavaScript environments.
  Fix: Continue using `const I18n = require('i18n-t');` in CommonJS contexts. For projects requiring ESM, consider using a different, modern i18n library that explicitly supports ESM.
• gotcha The package does not ship with TypeScript type definitions. Integrating it into a TypeScript project will require manually creating declaration files (e.g., `i18n-t.d.ts`) to avoid type errors.
  Fix: Create a `declare module 'i18n-t' { ... }` block with appropriate types for the `I18n` class and its methods, or migrate to a TypeScript-first i18n library.
• gotcha When a translation key is not found for a given locale, `i18n-t` defaults to returning the translation key itself. This behavior might be unexpected compared to other libraries that offer fallback locales or explicit `missingTranslationHandler` functions.
  Fix: Implement custom logic to check for translation existence before calling `i18n.t` or wrap `i18n.t` with a function that provides desired fallback behavior. Ensure all required keys exist in your locale files.

Install

• npm install i18n-t npm
• yarn add i18n-t yarn
• pnpm add i18n-t pnpm

Imports

• I18n
  wrong:

  import I18n from 'i18n-t';

  correct:

  const I18n = require('i18n-t');

  This package is CommonJS-only and does not provide an ESM export. Direct `import` statements will fail.
• i18n.t

  const i18n = new I18n({ defaultLocale: 'en' }); i18n.t('en', 'HELLO', { name: 'World' });

  The primary translation function `t` is a method on an `I18n` instance, requiring the locale and key as explicit arguments.
• i18n.load

  const i18n = new I18n({ defaultLocale: 'en' }); i18n.load('./locales');

  Used to load translation files from a specified directory. Ensure the path is correct for your environment (e.g., Node.js `__dirname`).

Quickstart

This quickstart demonstrates how to initialize `i18n-t`, load locales from a directory and pre-loaded objects, and then translate strings using the `t` method, including interpolation for variables and indexed placeholders.

const I18n = require('i18n-t');
const path = require('path');
const fs = require('fs');

// Create a dummy 'locales' directory and files for demonstration
const localesDir = path.join(__dirname, 'temp_locales');
if (!fs.existsSync(localesDir)) {
  fs.mkdirSync(localesDir);
}
fs.writeFileSync(path.join(localesDir, 'en.js'), 'module.exports = { HELLO: "Hello {{name}}", CATS: "{{0}} cats", DOGS: "No dogs" };');
fs.writeFileSync(path.join(localesDir, 'fr.js'), 'module.exports = { HELLO: "Bonjour {{name}}", CATS: "{{0}} chats" };');

const i18n = new I18n({
    defaultLocale: 'en'
});

// Load locales from the dummy directory
i18n.load(localesDir);

// Or using a pre-loaded object (can be used alongside or instead of load)
i18n.set({
    es: {
        HELLO: 'Hola {{name}}'
    }
});

// Translate sentences
console.log(i18n.t('en', 'HELLO', { name: 'Samy' }));
console.log(i18n.t('en', 'CATS', 10));
console.log(i18n.t('fr', 'HELLO', { name: 'Marie' }));
console.log(i18n.t('fr', 'CATS', 5));
console.log(i18n.t('es', 'HELLO', { name: 'Pedro' }));
console.log(i18n.t('en', 'DOGS'));
console.log(i18n.t('fr', 'DOGS')); // Will return key if not found in 'fr'

// Clean up dummy directory (optional, for a runnable example)
fs.unlinkSync(path.join(localesDir, 'en.js'));
fs.unlinkSync(path.join(localesDir, 'fr.js'));
fs.rmdirSync(localesDir);