wp-textdomain

1.0.1 verified Fri May 01 auth: no javascript

A linting and fixing tool for WordPress plugin and theme textdomains in PHP files. Version 1.0.1 is latest. It scans PHP files using glob patterns and validates/replaces textdomain arguments in gettext functions like __, _e, _x, etc. Supports multiple domains in an array, automatic fixes (fix option), and custom keyword definitions. Key differentiators: specifically designed for WordPress, unlike general PHP linters; can fix missing or incorrect textdomains; configurable via options like engine (php-parser), variableDomain, and missingDomain.

Common errors

error Cannot read properties of undefined (reading 'domain') ↓

cause Missing or incorrectly formatted options object, or domain not specified.

fix

Ensure options object is provided with a 'domain' property (string or array).

error No files matched for pattern: **/*.php ↓

cause Provided glob pattern does not find any PHP files.

fix

Double-check the pattern and working directory; use an absolute path if needed.

error Error: php-parser: Parse Error on line X ↓

cause PHP file contains syntax that php-parser cannot parse.

fix

Temporarily remove or fix the problematic PHP syntax, or update php-parser settings.

Warnings

gotcha When using multiple domains, fixing uses the first domain as replacement; others are only valid. ↓

fix Always ensure the primary domain is listed first in the domain array when fix:true.

gotcha The package uses php-parser for parsing PHP; complex PHP syntax may cause errors. ↓

fix Test with your codebase and consider reporting issues on GitHub.

deprecated The 'logfile' option with moment.js timestamp may be deprecated; moment is a heavy dependency. ↓

fix Consider using a custom date function or a lightweight alternative.

Install

npm install wp-textdomain

yarn add wp-textdomain

pnpm add wp-textdomain

Imports

wpTextdomain
wrong
```
import wpTextdomain from 'wp-textdomain';
```
correct
```
const wpTextdomain = require('wp-textdomain');
```
Package exports a single function via CommonJS; ESM import is not supported by default
wpTextdomain
```
import wpTextdomain from 'wp-textdomain';
```
In TypeScript, if module resolution allows, you can use ESM but the package is CJS

Quickstart

Shows basic linting and fixing of WordPress textdomains in PHP files using wp-textdomain.

const wpTextdomain = require('wp-textdomain');

// Lint PHP files for textdomain 'my-theme'
wpTextdomain('**/*.php', {
  domain: 'my-theme',
  fix: false
});

// With automatic fix using multiple domains
wpTextdomain('**/*.php', {
  domain: ['my-theme', 'kirki'],
  fix: true
});