Version 2.5 added support for JSON translation files used in WordPress >= 5.
Most WordPress language packs consist of pairs of PO and MO files. The PO file is what you edit within a file editor like Loco Translate. The MO file is a binary format compiled from the PO file. This is what WordPress actually reads in order to load translations into PHP.
Compiling JSON translation files
You will find the JSON files have curious names and there may be many of them. This is because a JSON file is compiled for every separate script. For example, take a PO file (
fr_FR.po) containing the following message:
#: scripts/example.js:21 msgid "Hello World" msgstr "Bonjour tout le Monde"
Saving this file in Loco Translate would generate a JSON file called
my-plugin-fr_FR-72e8c5e24e35642471d54763afbb6a54.json where the long string is computed as
Its contents will contain only the strings associated with the given script. This file should be treated the same way you treat MO files: It must be deployed to your website in order for WordPress to read it, but it is not for editing directly. It can always be recompiled from the PO file if it gets lost.
There are two new options in the Loco Translate plugin settings to accompany this function.
wp i18n make-pot and ship a valid and up to date POT file with their code.
However, be aware that WordPress supports only basic mapping of
.min.js files when computing the JSON file names. More complex build systems may cause you issues. See the notes below.
Notes and caveats
Source references in the PO file must be valid relative paths and exist in the deployed code. If both the
.min.jsfiles are missing then no JSON will be generated for the script. This is to avoid filling up folders with JSON files that will never be loaded. See String extraction for more detail on this.
Loading script translations from Loco Translate's custom directory works identically to MO files in that they are merged. This merging is done in PHP which means the JSON is decoded and encoded. This solution is not ideal, but currently the most reliable method we've come up with.
Do not use
wp i18n make-jsonto save JSON files into Loco Translate's custom directory. It's essential for correct merging that JSON files exclude empty keys like MO files do. Our compiler does this; WP-CLI does not.
If you do use
wp i18n make-json, always specify
--no-purgebecause this command purges by default. JSON files are not directly editable in Loco Translate, so if you strip script translations from a PO file then you'll no longer be able to edit them. Furthermore, if you were to lose the JSON file, there would be no way to recover the translations except from a backup.
WordPress gives priority to authors' own JSON files if they are named according the script handle, e.g.
myDomain-fr_FR-myScript.jsonand will not look any further if it finds one. Loco Translate cannot generate JSON files with this naming convention. Authors can choose any unique handle they like and there is no way to derive this from a POT file.
Be aware that language packs installed by WordPress will have script translations purged from the PO and MO files. Strings used only in
.jsfiles will be present only in the JSON files. As of Loco Translate 2.5.3 you can choose to merge JSON strings when you copy a PO file, however the JSON format is such that important PO metadata may be lost.
Loco Translate derives JSON file names from the file references held in PO files when they are saved. This name must match the one that WordPress derives from the related script when it is loaded by your theme or plugin. There are many reasons this can fail.