i18n Support – WordPress Plugin Boilerplate

The plugin is prepared to support internationalization (i18n) and translations for your WordPress plugin.

Note

The i18n Composer scripts assume that WP-CLI is available in the current environment. You can either use wp-env or install WP-CLI separately. See the official WP-CLI installation guide.

Translate your plugin

1. Run bundling using npm run build for js script extraction.
2. Run composer run i18n:extract to generate the .pot file in the languages/ directory and update existing .po files.
3. Translate the strings in the .po files existing or create a new file for each language you want to support.
4. (Optional) Run composer run i18n:compile to compile the .po files into .mo, .json and .php files. This step makes translations available to WordPress. The deploy action does this automatically using wp-env.

This process allows you translating blocks and generate the fast php format for maximum performance.

Using AI

The plugin does provide a command to instruct your coding agent to do the work for you.

/upsert-translations [lang1 lang2 ...]

Use the wp-plugin-bp skill for translation work, or run the commands manually when working without an agent.

Actually translating strings

The .po files have to be created and the strings have to actually be translated. You can use tools like Poedit or Loco Translate to manage translations. Another thing that works well is using is to ask your coding agent to “upsert the translations”.

Things to keep in mind

• The textdomain has to be exactly the one defined in demo-plugin.php. Otherwise, extraction will not find the strings.
• The provided scripts only work if wp-cli is available and a fully working WordPress installation is present.
• i18n Strings in Enums are not supported due to upstream library limitation in gettext
• To extract twig strings you need to install https://github.com/timber/wp-i18n-twig
• The make-pot command requires to read bundled js files. Thats why we exclude the resources/ folder in composer i18n:extract. Processing the source folder would result a in json translation file per js source file and therefore be incompatible with the wp_set_script_translations during enqueueing of bundles.