babel-gettext-extractor

4.1.3 verified Sat Apr 25 auth: no javascript

Babel plugin to extract gettext strings from JavaScript/JSX code, supporting ES6+ and JSX syntax. Current stable version is 4.1.3, maintained by Sentry. It is a fork of babel-gettext-plugin with added support for references and earlier Node.js versions. Works with Babel 7. Key differentiators: flexible configuration of function names, custom output file naming via a callback, base directory for relative paths, and optional whitespace stripping from template literals. Alternatives like babel-plugin-react-intl focus on React Intl, while this plugin targets the standard gettext workflow.

Common errors

error Error: Cannot find module 'babel-gettext-extractor' ↓

cause Plugin not installed or misspelled in Babel config.

fix

Run 'npm install --save-dev babel-gettext-extractor' and verify the plugin string is correct.

error ReferenceError: [BABEL] unknown: Unknown option: .plugins[0][1].foo ↓

cause Invalid option name in the plugin configuration object.

fix

Check the option names: valid ones are 'headers', 'functionNames', 'fileName', 'baseDirectory', 'stripTemplateLiteralIndent'.

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

cause fileName function receives an object without the expected property, possibly due to Babel version mismatch.

fix

Ensure you are using Babel 7 and pass the file object correctly; check the example in the README.

error No output .pot file generated ↓

cause Either no translatable strings found, fileName returns false, or output path is incorrect (e.g., relative path resolves to a non-existent directory).

fix

Ensure your source files contain calls to configured functionNames with string literals. Check console logs for skipped files. Confirm fileName path is absolute or relative to the working directory.

Warnings

breaking Plugin name changed from 'babel-gettext-plugin' to 'babel-gettext-extractor' in v4. ↓

fix Replace 'babel-gettext-plugin' with 'babel-gettext-extractor' in your Babel config.

deprecated The 'babel' package is deprecated; use '@babel/core' with Babel 7. ↓

fix Replace require('babel') with require('@babel/core') and update config accordingly.

gotcha fileName option can be a function returning false to skip extraction per file. ↓

fix Return false from the fileName function to prevent output for that file.

gotcha If stripTemplateLiteralIndent is true, gettext implementations must also strip leading indent; otherwise translations may have extra whitespace. ↓

fix Ensure your gettext runtime also strips leading indent when using this option.

gotcha baseDirectory only affects file references in the .pot output; it does not filter which files are processed. ↓

fix Use fileName function or Babel's ignore/include patterns to control which files are processed.

Install

npm install babel-gettext-extractor

yarn add babel-gettext-extractor

pnpm add babel-gettext-extractor

Imports

plugin
wrong
```
import babelGettextExtractor from 'babel-gettext-extractor'
```
correct
```
module.exports = { plugins: ['babel-gettext-extractor'] }
```
This is a Babel plugin, not a standalone module. It's used via Babel's plugins array, not imported directly in application code.

plugin with options

wrong

module.exports = { plugins: ['babel-gettext-extractor', { headers: {} }] }

correct

module.exports = { plugins: [['babel-gettext-extractor', { headers: { 'content-type': 'text/plain; charset=UTF-8' } }]] }

Options are passed as an array entry [plugin, options], not as separate arguments.

require in code

wrong

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

correct

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

The plugin is a string reference; requiring it directly and using the object is incorrect because Babel resolves it by name from node_modules.

Quickstart

Configures babel-gettext-extractor with custom function names and headers, outputs a .pot file.

// .babelrc or babel.config.js
module.exports = {
  plugins: [
    ['babel-gettext-extractor', {
      headers: {
        'content-type': 'text/plain; charset=UTF-8',
        'plural-forms': 'nplurals=2; plural=(n!=1);'
      },
      functionNames: {
        _t: ['msgid'],
        _n: ['msgid', 'msgid_plural'],
        _p: ['msgctxt', 'msgid']
      },
      fileName: './messages.pot',
      baseDirectory: './src',
      stripTemplateLiteralIndent: false
    }]
  ]
};

// Run: babel --plugins babel-gettext-extractor src/ -d lib/