README

Automate the internationalization workflow of your WordPress plugin or theme by wiring WP-CLI translation tools into familiar Composer commands.

Requirements

PHP 7.4+ and Composer 2.6+ (Composer plugin API 2.6 is required)
WP-CLI 2.12+ available on your $PATH
A WordPress plugin or theme with Text Domain and Domain Path headers defined

Installation

composer require --dev lloc/composer-i18n-scripts

Composer automatically registers the plugin; no manual bootstrap code is needed. Running composer install on the project will keep the plugin active for all contributors.

Configuration

The plugin inspects your project root to infer settings:

Themes: reads style.css
Plugins: reads the main plugin file (matching the directory name or index.php)

Provide headers like the following so WP-CLI receives the right text domain and language directory:

/*
Plugin Name: Sample Plugin
Text Domain: sample-plugin
Domain Path: /languages
*/

If no metadata is found, defaults are Text Domain: messages and Domain Path: /languages.

Usage

Run the commands from the WordPress project root so that wp can load your environment.

Command	Purpose
`composer i18n:make-pot`	Scan the source directory and generate `languages/<domain>.pot`.
`composer i18n:create-po <locale>`	Copy the `.pot` file to a locale-specific `.po` file (e.g. `de_DE`).
`composer i18n:update-po`	Merge the current `.pot` changes into every `.po` in `languages/`.
`composer i18n:make-mo`	Compile all `.po` files into `.mo` binaries.
`composer i18n:make-php`	Export `.po` translations into PHP array files for performance-sensitive setups.
`composer i18n:make-json`	Build JavaScript translation catalogs (`*.json`) without purging existing assets.

Example workflow:

composer i18n:make-pot
composer i18n:update-po
composer i18n:make-json
composer i18n:make-mo

Development

composer install – install dependencies and register the plugin
composer qa – PHPCS (WordPress Coding Standards) + PHPStan level 10
composer tests – run PHPUnit suite under tests/Commands
composer tests:coverage – generate HTML coverage in tests/coverage/
composer cs:fix – automatically fix style violations

Refer to AGENTS.md for contributor conventions, coding standards, and pull request expectations.

Troubleshooting

“Text domain is not set”: ensure your plugin/theme headers declare Text Domain and Domain Path.
WP-CLI not found: verify wp is installed globally or provide an absolute path (e.g. symlink wp into /usr/local/bin).
Translations not picking up new strings: rerun composer i18n:make-pot before updating .po files so the template is up to date.

lloc / composer-i18n-scripts

Maintainers

Details