Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

PO Merger for WP-CLI

When you are a translator contributor for a language that is similar to another one (example: French from France vs French Canada), merging the missing translation from the first language to the second one is a fast way to get translation done. Then, you simply have to edit the difference between the two locales.

This project was made to merge two WordPress PO files using a WP-CLI command.


The project requires the latest version of WP-CLI. Start by updating WP-CLI in the terminal:

wp cli update

Then run the following command to install the project:

wp package install satellitewp/po-merger


PO Merger lets you merge PO files two different ways:

  • With the URL of a project found on the WordPress repository
  • With the translation URL of a project in the WordPress repository (including meta and apps)
  • With the core version of WordPress

To merge two PO files from a WordPress project URL, use the following command:

wp po merge <base-locale> <copy-locale> <url>

To merge two PO files from a WordPress core version, use the following command:

wp po merge <base-locale> <copy-locale> <version>


Parameter Description
<base-locale> Main locale used for the merge.
<copy-locale> Locale used to get translations that are not present in the base locale.
<source> Source can be a WordPress plugin or theme main page URL, a WordPress project translation URL (plugin, theme, meta or apps) or a WordPress core version.


Merging FR locale into FR-CA for a plugin or theme

wp po merge fr-ca fr

Using the translation URL

wp po merge fr-ca fr

wp po merge fr-ca fr

wp po merge en-ca en-gb

Merging FR locale into FR-CA for WordPress 5.0

wp po merge fr-ca fr 5.0

Optional parameters

Parameter Description
--fuzzy=<file> Specifies a text file containing words or expressions (one per line) that will trigger a translation revision. If a translation from the copy locale contains these strings, the translation will be marked as fuzzy.
--dictionary=<file.po> Specifies a PO file containing master translations to use that were previously validated. These translations will be used before using the ones in the copy locale. It will also alter existing translations already approved in the base locale.
--mark-copy-as-fuzzy Marks the translations obtained from the copy locale as fuzzy.
--mcaf Alias of the --mark-copy-as-fuzzy parameter.
--status=<filter1>,<filter2>,... Specifies the filter(s) for the base locale download URL. List of valid filters: current, untranslated, fuzzy, waiting, rejected, old. Some of the filters may be mutually exclusive.
--diff-only Generates a result PO file containing only the differential strings (untranslated).
--username Get the translations from the specific contributor ( username).
--test Allows to conduct local tests. See Testing Locally section for details.

Testing the commands locally [ Tests are broken because of major refactoring ]

A WordPress PO file may contain tens of thousands of lines and it can be difficult to verify the result of the merging process. Thus, the package allows to create small PO files locally and use them for merging.

The --test parameter allows to read PO files defined in the tests/<base-locale> and tests/<copy-locale> folders, instead of downloading from the WordPress server. The PO files should have the valid WordPress PO format and their names should contain exactly the same locale as their current folders, preceding by the -.


tests/fr-ca/test-fuzzy-fr-ca.po and tests/fr/test-fuzzy-fr.po


wp po merge <base locale> <copy-locale><type>/<name of the file>/ --test --<optional parameter>


wp po merge fr-ca fr --test


Parameter Description
<base-locale> The folder tests/<base-locale>
<copy-locale> The folder tests/<copy-locale>
<type> plugins or themes
<name of the file> The name of the file without the locale and PO extension
<optional parameter> Optional parameter

In this example, the content of the files tests/fr-ca/test-fuzzy-fr-ca.po and tests/fr/test-fuzzy-fr.po will be processed. If the base locale doesn't have a given translation, it will be searched in the copy locale and if found, copied to the base locale. If in the base locale a given translation exists already, it won't be replaced by the translation from the copy locale.

The output will be saved in the directory where the command was executed, with the name wp-<type>-<slug>-<base-locale>-merged.po



Optional parameters

The optional parameters supported in the test mode are --mark-copy-as-fuzzy/mcaf and --fuzzy=<file>.

The package comes with the test PO files where you can add your own strings to test.


This project was created and is maintained by SatelliteWP. The project was started during an internship by Pavel Zaharciuc.


Ideas are welcome.


Merge PO files from two similar languages to facilitate translation







No releases published


No packages published

Contributors 4