babel-gettext-plugin

3.0.0 verified Sat Apr 25 auth: no javascript maintenance

A Babel plugin (v3.0.0) that extracts gettext translation strings (msgid, msgctxt, etc.) from JavaScript files, supporting JSX, ES6, and other syntax via Babel. Built on node-gettext. It replaces older extractors like xgettext which lack modern syntax support. Maintenance is sparse; last release 2019.

Common errors

error Error: Cannot find module 'babel' ↓

cause Incorrect Babel package: babel 6 vs @babel/core 7 naming.

fix

Use '@babel/core' instead of 'babel': npm install @babel/core and const babel = require('@babel/core');

error TypeError: Cannot read property 'traverse' of undefined ↓

cause Plugin used with Babel 6 but installed v3.0.0 (requires Babel 7).

fix

Install v2.x: npm install babel-gettext-plugin@2.x --save-dev

error Warning: No strings extracted. ↓

cause Plugin cannot find gettext call syntax (default function name '_'). No custom functionNames set.

fix

Define functionNames matching your gettext wrapper names, e.g., 'mygettext': ['msgid']

Warnings

breaking Plugin requires Babel 7; incompatible with Babel 6 or older. Use v2.x for Babel 6. ↓

fix Install babel-gettext-plugin@2.x for Babel 6 projects.

deprecated Last release in 2019; no updates for newer Babel versions (8.x) or modern ECMAScript features. ↓

fix Consider alternatives like 'babel-plugin-gettext-extractor' or manual extraction with xgettext.

gotcha Plugin does not support parsing dynamic strings or template literals; only string literals extracted. ↓

fix Ensure all your translatable strings are string literals, e.g., _('Hello') not _(textVar).

gotcha Output encoding: Generated .po/.pot files may have incorrect charset if headers not provided; default is UTF-8. ↓

fix Always specify headers with 'content-type' charset to avoid encoding issues.

Install

npm install babel-gettext-plugin

yarn add babel-gettext-plugin

pnpm add babel-gettext-plugin

Imports

babel

wrong

import babel from 'babel'; // ESM import not supported; Babel 7's API is CJS

correct

const babel = require('babel'); babel.transform(code, { plugins: ['babel-gettext-plugin'] })

Plugin is used via Babel's transform API; not imported directly. Must be required in CommonJS context.

plugin config

wrong

plugins: ['babel-gettext-plugin', { headers: {} }] // wrong: array nesting

correct

plugins: [['babel-gettext-plugin', { headers: {}, functionNames: {} }]]

Options must be passed as the second element of an array, not as separate arguments.

CLI usage

wrong

babel --plugin babel-gettext-plugin code.js // wrong: '--plugin' should be '--plugins'

correct

babel --plugins babel-gettext-plugin input.js -o output.js

Use --plugins, not --plugin. Options can be appended with colon, e.g. --plugins babel-gettext-plugin:{"fileName":"test.po"}

Quickstart

Demonstrates plugin setup with Babel 7, custom function names for extraction, and .pot file output.

const babel = require('@babel/core');
const code = `
const _ = require('gettext');
const msg = _('Hello world');
console.log(_('Goodbye', 'context'));
`;

babel.transform(code, {
  plugins: [
    ['babel-gettext-plugin', {
      headers: {
        'content-type': 'text/plain; charset=UTF-8',
        'plural-forms': 'nplurals=2; plural=(n!=1);'
      },
      functionNames: {
        mygettext: ['msgid'],
        myngettext: ['msgid', 'msgid_plural', 'count']
      },
      fileName: './locales/messages.pot',
      defaultTranslate: false
    }]
  ]
}).then(result => {
  console.log('Extraction complete, check .pot file.');
}).catch(err => console.error(err));