l10n-tools-compiler-gettext

7.0.10 verified Fri May 01 auth: no javascript

A compiler plugin for the l10n-tools ecosystem that handles PO/MO file formats for internationalization workflows. Current stable version is 7.0.10, requiring Node >=22.19.0 and npm >=10.9.0. It is part of the l10n-tools monorepo and depends on l10n-tools-core ^8.0.0, which dropped PHP gettext support in v8.0.0 (a breaking change). This package is TypeScript-native, ESM-only, and designed for CLI-based translation compilation. Unlike standalone gettext parsers, it integrates tightly with l10n-tools's pipeline and is intended for use with l10n-tools-cli or programmatically via the core API. Release cadence follows the monorepo's weekly/biweekly schedule.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /.../node_modules/l10n-tools-compiler-gettext/index.js from /.../app.js not supported. ↓

cause Package is ESM-only and cannot be required via CommonJS.

fix

Use import syntax or dynamic import(). Alternatively, set { type: 'module' } in package.json.

error TypeError: compileGettext is not a function ↓

cause Default import used instead of named import.

fix

Change to: import { compileGettext } from 'l10n-tools-compiler-gettext'

error Error: Cannot find module 'l10n-tools-core' ↓

cause Missing peer dependency l10n-tools-core.

fix

Install l10n-tools-core: npm install l10n-tools-core@^8.0.0

error SyntaxError: Unexpected token 'export' ↓

cause Trying to run ESM code in a CommonJS context without type:module or .mjs extension.

fix

Rename file to .mjs or add 'type': 'module' to package.json.

Warnings

breaking l10n-tools-core bumped from ^7.x to ^8.0.0 requiring peer dependency update ↓

fix Update l10n-tools-core to ^8.0.0 and ensure your code does not rely on the removed PHP gettext support.

breaking Deprecation of PHP gettext support may affect users processing PHP-generated .po files ↓

fix Use a compat shim or preprocess files to remove PHP-specific metadata.

gotcha Package is ESM-only; require() will throw ERR_REQUIRE_ESM ↓

fix Use import syntax or dynamic import(). Ensure parent package is also ESM or uses a bundler that supports ESM.

gotcha compileGettext expects raw PO string, not parsed object ↓

fix Ensure you pass a string. Use parsePo() first if you need to inspect or modify the parsed structure.

deprecated The compileGettext function signature changed in v7.5.0: options parameter flattened ↓

fix Update to latest version and pass options as flat object instead of nested structure.

Install

npm install l10n-tools-compiler-gettext

yarn add l10n-tools-compiler-gettext

pnpm add l10n-tools-compiler-gettext

Imports

GettextCompiler

wrong

const GettextCompiler = require('l10n-tools-compiler-gettext')

correct

import { GettextCompiler } from 'l10n-tools-compiler-gettext'

Package is ESM-only and does not export a CommonJS version. TypeScript types are bundled.

compileGettext

wrong

import compileGettext from 'l10n-tools-compiler-gettext'

correct

import { compileGettext } from 'l10n-tools-compiler-gettext'

compileGettext is a named export, not a default export.

parsePo
```
import { parsePo } from 'l10n-tools-compiler-gettext'
```
Available since v7.0.0. For parsing .po files without compilation.

Quickstart

Show reading a .po file, compiling it with compileGettext, and writing the .mo output. Minimal setup with TypeScript.

import { compileGettext } from 'l10n-tools-compiler-gettext';
import { readFileSync, writeFileSync } from 'node:fs';

const poContent = readFileSync('messages.po', 'utf-8');
const compiled = compileGettext(poContent, {
  sourceLocale: 'en',
  targetLocale: 'fr',
  domain: 'messages',
});
writeFileSync('messages.mo', compiled);
console.log('Compiled .mo file written.');