Translations

Translation System Overview

This project has a semi-automated translation system to manage the translation of strings used in the plugin. The system is designed to keep the translation files up to date with only minimal manual operations.

WordPress Translation Files

WordPress uses several types of files to manage translations and internationalization for plugins and themes:

• .pot (Portable Object Template) file: This is the master template file containing all translatable strings extracted from the codebase. It serves as the source for translators to create translations in other languages.
• .po (Portable Object) files: These are human-readable translation files for each language. Translators use the .pot file to create or update .po files, which contain the original strings and their translations.
• .mo (Machine Object) files: These are binary files generated from .po files. WordPress loads .mo files at runtime to display translated strings to users.
• .json files: For JavaScript-based translations, WordPress uses .json files. These are generated from the .po files and are used by the JavaScript internationalization system to provide translations in the browser.

Plugins and themes should include headers providing the text domain and the language directory.

For plugins hosted on WordPress.org, the text domain registers using the JIT loader. For plugins not hosted on WordPress.org, the text domain is registered using the load_plugin_textdomain() function. This should be called on or after init.

How the Translation Workflow Operates

1. Updating the .pot file:

   • The .pot file is updated whenever new translatable strings are added or existing ones are changed in the codebase. This is typically done using WP-CLI commands and requires a working WordPress installation.
   • The command used is:

     wp i18n make-pot . ./languages/accessibility-checker.pot

2. Creating/Updating .po and .mo files:

   • Translators use the updated .pot file to create or update .po files for each language. The .mo files are then generated from the .po files. WordPress uses the .mo files to display translations on the site.

3. Generating .json files for JavaScript translations:

   • JavaScript translations require .json files, which are generated from the .po files. These files allow WordPress to provide translations for strings used in JavaScript code.
   • The command used to generate the .json files is:

    wp i18n make-json ./languages ./languages --no-purge --pretty-print

Important Notes for JavaScript Translations:

• When making the pot file you must run the command against a fully built version of the plugin. The strings are extracted from the built scripts statically so the built scripts must exist and must contain the translation functions to be found.
• When building your plugin you need to include the @wordpress/i18n script as an import - but set it as an external in your build scripts.
  • An example of this for webpack is:

  externals: {
    // Exclude WordPress core scripts and styles from the build.
    '@wordpress/i18n': [ 'wp', 'i18n' ],
  },

• Most minification tools will not preserve the translation functions in the JavaScript code, so you must ensure that the translation functions are not removed during the build process. And example of that for terser and wepack is:

  optimization: {
    	minimizer: [
    		new TerserPlugin( {
    			terserOptions: {
    				mangle: {
    					reserved: [ '__', '_n', '_x', '_nx' ], // Prevent webpack from using these translation function names and mangling them in the source.
    				},
    				keep_fnames: /(__|_n|_x|_nx)$/,
    			},
    		} )
    	],
    },

• You must load the text domain for every js script that you enqueue. This is done using the wp_set_script_translations() function, which associates the script with the appropriate translation files.
• The --no-purge flag in the make-json command ensures that the translations are not plucked out of the .pot or .po files, allowing PTC.WPML to generate the .po files with JS translations included for that language.

Project Automation

• The project uses a semi-automated workflow to keep translation files up to date. The make-pot.yml workflow updates the .pot and .json files and opens a pull request if changes are detected. This can be triggered manually against any branch. Most commonly it will be run against the develop.
• When a .pot update is merged to develop, an external service (PTC.WPML) generates updated .po and .mo files and opens a PR with the new translations.
• Translation branches automatically update the .json files by having the make-pot.yml workflow run on it and open PRs as needed.
  • Merge in any updated json to the translation branch
  • Merge in the translation branch to develop.