gettext.js

2.1.1 verified Fri May 01 auth: no javascript maintenance

Browser-side GNU gettext implementation for internationalization (i18n). Current stable version is 2.1.1. Provides a `gettext`-like interface in the browser, compiles MO files to JavaScript, includes a webpack loader for MO files, and supports plural forms with `ngettext`. Key differentiators: lightweight, browser-focused, integrates with webpack, and offers both runtime API and pre-compilation. Compared to i18next or Polyglot, gettext.js is closer to the GNU gettext workflow and simpler for projects already using MO files. Release cadence: occasional maintenance updates, as last release was several years ago.

Common errors

error TypeError: gettext is not a function ↓

cause Using default import instead of named import after v2.0.0.

fix

Change import gettext from 'gettextjs' to import { gettext as _ } from 'gettextjs'.

error Module not found: Can't resolve 'gettextjs' in '...' ↓

cause Package not installed or path mistake.

fix

Run npm install gettextjs and ensure the import path is correct.

error Error: set_catalog must be called with an object ↓

cause Called set_catalog without arguments or with wrong type.

fix

Call set_catalog({ 'en': { 'key': 'value' } }) with a valid catalog object.

error Calls to gettext return original string even though catalog is set ↓

cause Catalog might not have the correct locale or the string key is missing.

fix

Ensure the catalog includes the exact string key and that the locale matches. Use set_catalog({ locale: { msgid: msgstr } }).

Warnings

gotcha set_catalog must be called before any gettext/ngettext calls, otherwise they return the untranslated string. ↓

fix Always call set_catalog with a valid catalog object (locale -> { message: translation }) at initialization.

deprecated The `compiler` module and the CLI tool `gettextjs compile` are deprecated in favor of webpack loader or manual parsing. ↓

fix Use the webpack loader or include a precompiled catalog via set_catalog.

gotcha In browser, `.mo` files cannot be read directly; you must use a loader (webpack) or convert to JSON/catalog object via the runtime. ↓

fix Use the provided webpack loader for `.mo` files, or compile the `.mo` to a JS file using the CLI (`gettextjs compile input.mo output.js`) and then import that file.

breaking Version 2.0.0 changed imports from default to named exports. `import gettext from 'gettextjs'` no longer works. ↓

fix Use named imports: `import { gettext as _, ngettext, set_catalog } from 'gettextjs'`.

Install

npm install gettextjs

yarn add gettextjs

pnpm add gettextjs

Imports

gettext (as _)

wrong

import gettext from 'gettextjs'

correct

import { gettext as _ } from 'gettextjs'

gettext is a named export, not default.

set_catalog
wrong
```
const { set_catalog } = require('gettextjs')
```
correct
```
import { set_catalog } from 'gettextjs'
```
Works with CJS, but preferred import is ESM as shown. set_catalog is required before using gettext/ngettext.

ngettext

wrong

import { ngettext as _n } from 'gettextjs'

correct

import { ngettext } from 'gettextjs'

It's fine to alias, but the symbol name is ngettext.

Quickstart

Shows basic setup: import named exports, set_catalog with translations, and use gettext/ngettext.

import { gettext as _, ngettext, set_catalog } from 'gettextjs';
import fs from 'fs';

// Load a .mo file as bytes (e.g., from fs) and parse it
const moBuffer = fs.readFileSync('messages.mo');
const catalog = { locales: ['en'], messages: {} }; // simplified; real usage uses mo-parse
// For simplicity, set a dummy catalog
set_catalog({
  'en': {
    'hello world': 'hello world',
    'bug': ['bug', 'bugs']
  }
});

console.log(_('hello world')); // 'hello world'
console.log(ngettext('bug', 'bugs', 4)); // 'bugs' (since count > 1)