{"id":11423,"library":"node-gettext","title":"Node.js Gettext Localization Library","description":"node-gettext is a comprehensive JavaScript implementation of a significant subset of the GNU gettext localization framework, designed for both server-side Node.js and client-side browser environments, making it an isomorphic solution. Currently at version 3.0.1, the library focuses exclusively on string and phrase translation, omitting categories like LC_NUMERIC or LC_MONETARY found in the full GNU gettext specification, as it assumes the LC_MESSAGES category at all times. It supports core gettext features such as domains, contexts, and plural forms, and ships with pluralization rules for 136 languages. A key differentiator is that developers are responsible for loading translation files (e.g., .mo, .po, .json via gettext-parser) and providing them to the instance, rather than the library automatically reading from the file system. The library provides useful error messages when debug is enabled and emits events for internal issues, such as missing translations.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/alexanderwallin/node-gettext","tags":["javascript","i18n","l10n","internationalization","localization","translation","gettext"],"install":[{"cmd":"npm install node-gettext","lang":"bash","label":"npm"},{"cmd":"yarn add node-gettext","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-gettext","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for parsing .mo and .po files into the JavaScript object format node-gettext expects for translation data.","package":"gettext-parser","optional":false}],"imports":[{"note":"The Gettext class is the default export of the 'node-gettext' module, intended for ES Module (ESM) environments.","wrong":"import { Gettext } from 'node-gettext'","symbol":"Gettext","correct":"import Gettext from 'node-gettext'"},{"note":"For CommonJS projects or older Node.js environments, the module's default export (the Gettext class) is accessed directly.","wrong":"const { Gettext } = require('node-gettext')","symbol":"Gettext (CJS)","correct":"const Gettext = require('node-gettext')"},{"note":"When working with .po files, import the named 'po' export from the companion 'gettext-parser' library. Similarly, use 'mo' for .mo files.","wrong":"import gettextParser from 'gettext-parser'","symbol":"gettext-parser (PO parser)","correct":"import { po } from 'gettext-parser'"}],"quickstart":{"code":"import Gettext from 'node-gettext';\n\n// Example Swedish translation data in the format expected by node-gettext.\n// This would typically be loaded from a .json, .mo, or .po file processed by gettext-parser.\nconst swedishTranslations = {\n  charset: 'UTF-8',\n  headers: {\n    'plural-forms': 'nplurals=2; plural=(n != 1);',\n    'content-type': 'text/plain; charset=UTF-8'\n  },\n  translations: {\n    messages: {\n      'The world is a funny place': {\n        msgid: 'The world is a funny place',\n        msgstr: ['Världen är en underlig plats']\n      },\n      'Hello, %s!': {\n        msgid: 'Hello, %s!',\n        msgstr: ['Hallå, %s!']\n      },\n      'One apple': {\n        msgid: 'One apple',\n        msgid_plural: '%d apples',\n        msgstr: ['Ett äpple', '%d äpplen']\n      }\n    }\n  }\n};\n\nconst gt = new Gettext();\n\n// Add the loaded translations for the 'messages' domain and 'sv-SE' locale.\ngt.addTranslations('sv-SE', 'messages', swedishTranslations);\n\n// Set the current locale for the Gettext instance.\ngt.setLocale('sv-SE');\n\nconsole.log('--- Simple Translation ---');\nconsole.log(gt.gettext('The world is a funny place'));\n// Expected output: \"Världen är en underlig plats\"\n\nconsole.log('\\n--- Translation with Interpolation ---');\nconsole.log(gt.gettext('Hello, %s!', 'Alex'));\n// Expected output: \"Hallå, Alex!\"\n\nconsole.log('\\n--- Plural Form Translation (Singular) ---');\nconsole.log(gt.ngettext('One apple', '%d apples', 1));\n// Expected output: \"Ett äpple\"\n\nconsole.log('\\n--- Plural Form Translation (Plural) ---');\nconsole.log(gt.ngettext('One apple', '%d apples', 5));\n// Expected output: \"5 äpplen\"\n\n// Example of error event handling for missing translations\ngt.on('error', (error) => {\n  console.error('\\nGettext Error Event:', error);\n});\n\nconsole.log('\\n--- Triggering an Error Event (missing translation) ---');\ngt.gettext('This message does not exist');\n// Expected output: \"Gettext Error Event: This message does not exist\"\n","lang":"typescript","description":"Demonstrates basic setup, adding translations from an in-memory object, setting the active locale, and translating singular, plural, and interpolated strings. It also includes an example of handling error events for missing translations."},"warnings":[{"fix":"Review the official 'Migrating from v1 to v2' guide in the documentation to understand the necessary code modifications.","message":"Version 2.x of node-gettext introduced significant breaking changes from 1.x, requiring API adjustments for users migrating. This includes changes to constructor arguments and method signatures.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use dedicated, robust JavaScript libraries for number, currency, date, and other locale-specific formatting needs.","message":"Unlike the full GNU gettext, `node-gettext` is exclusively designed for string message translation (equivalent to the `LC_MESSAGES` category). It does not provide functionality for internationalizing numbers, currencies, or dates.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In Node.js, use `fs` along with `gettext-parser` to load and parse `.mo` or `.po` files. In browser environments, fetch `.json` translation files via HTTP and then add them to the `Gettext` instance.","message":"Developers must manually load translation files (e.g., .mo, .po, .json) from the file system or other sources and provide them as JavaScript objects to the `Gettext` instance via `addTranslations()`. The library does not automatically read files based on locale paths like GNU gettext.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always register an `on('error', handler)` listener on your `Gettext` instance to ensure all internal errors, including missing translations, are logged, displayed, or otherwise managed.","message":"Missing translations or other internal issues are emitted as 'error' events rather than being thrown as exceptions. If these events are not explicitly handled, they might be silently ignored, leading to untranslated strings in production without clear warnings.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement to `import Gettext from 'node-gettext'`.","cause":"Attempting to use `import { Gettext } from 'node-gettext'` when `Gettext` is the default export, especially common in bundled ESM projects.","error":"TypeError: (0 , node_gettext__WEBPACK_IMPORTED_MODULE_0__.default) is not a constructor"},{"fix":"Either configure your project for ES Modules by adding `\"type\": \"module\"` to your `package.json`, or use the CommonJS `require` syntax: `const Gettext = require('node-gettext')`.","cause":"Using ES Module `import` syntax (`import Gettext from 'node-gettext'`) in a CommonJS (`.js`) file without the project being configured for ESM (e.g., missing `\"type\": \"module\"` in `package.json`).","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Verify that `gt.addTranslations(locale, domain, translations)` has been called with the correct `locale` and `domain`, that `gt.setLocale(locale)` is correctly set, and that the translation key exactly matches a `msgid` entry in your loaded translation data. Also, ensure you handle 'error' events for debugging.","cause":"The requested translation key does not exist in the loaded translations for the current locale/domain, or the translations were not loaded correctly, or the locale/domain was not set.","error":"Translation for 'Your message here' not found (often manifests as the original msgid being returned)"}],"ecosystem":"npm"}