automattic/babel-plugin-replace-textdomain

A Babel plugin to replace the textdomain in gettext-style function calls.

v1.2.1 2026-08-06 11:32 UTC

GPL-2.0-or-later

Published on Packagist.org on 2026-08-06 11:32 UTC

README

A Babel plugin to replace the textdomain in gettext-style function calls.

This may be useful when using node modules for code-sharing among multiple applications (e.g. WordPress plugins), so each application's bundle uses a consistent textdomain throughout.

Installation

Generally you'll install this via your package manager, e.g.

npm install --save-dev @automattic/babel-plugin-replace-textdomain

Usage

In your Babel config, you might include the plugin something like this:

{
	"plugins": [
		[ "@automattic/babel-plugin-replace-textdomain", { "textdomain": "new-domain" } ]
	]
}

Plugin options are:

• textdomain: Specify the replacement text domain. The value may be a string, which will replace all domains; an object, to map specific domains (leaving any others untouched); or a function, which will be passed the existing domain (empty string if the domain is missing entirely) and is expected to return the new domain (or null).

• functions: Specify the functions that take domain arguments. This is an object mapping function names to the (zero-based) index of the domain argument.

  The default function list handles the __, _x, _n, and _nx functions provided by @wordpress/i18n. This list may be accessed as require( '@automattic/babel-plugin-replace-textdomain' ).defaultFunctions.

• i18nModule: Specify the module name used for resolving import aliases. When a function is imported from this module and called under an alias, the plugin will still recognize it. Defaults to @wordpress/i18n.

• requireI18nSource: Skip calls whose callee provably resolves to something other than i18nModule. Defaults to false.

  By default any call matching the function list is rewritten, including member calls like cache.__( key ). That is fine for hand-written source, but when the plugin runs over a whole bundle — where a dependency's own helpers sit in the same file as the real gettext calls — it rewrites calls that have nothing to do with i18n. With this option a callee is left alone once it can be traced to another module, while a callee whose origin can't be determined is still rewritten (so an unrecognized bundler shape doesn't silently leave a bundle untranslated).

To report instances of the specified i18n functions called without a domain or with an improper value for the domain, set the DEBUG environment variable to include @automattic/babel-plugin-replace-textdomain.

Security

Need to report a security vulnerability? Go to https://automattic.com/security/ or directly to our security bug bounty site https://hackerone.com/automattic.

License

babel-plugin-replace-textdomain is licensed under GNU General Public License v2 (or later)