PO Merger for WP-CLI: The WordPress Translation Simplifier

In this article, the second in a series of two on translation in a WordPress environment, I would like to describe the steps involved in conceptualizing and developing the tool PO Merger and its use. The problem that led to the creation of the tool is explained in the first article of this series and is called “The WordPress Translation: Sharing and Automation“. Although building a software application is composed of several stages, I find that the conceptualization and development stages are the most dynamic and so, will be the most interesting to describe to you.

Context

PO Merger is a tool that merges translations from two PO files from WordPress from two similar languages chosen by the user. The first file is considered the “base” and the second is the “copy”. If a particular line is not translated into the base file, the tool will attempt to find that line in the “copy” file. If this line is found in the copy and translated, then PO Merger will copy it to the base file. At the end of the process, a new file will be created that will contain the combination of the translations that were present in the base file and the copy file.

Technically, any combination of languages is allowed. However, the ultimate goal of the tool is to merge interchangeable language content, such as Français and Français du Canada, or for example the different variations of English (US, UK) Spanish, German, etc.

Conceptualization

Conceptualization is a crucial step, but it is not a “rigid” process (on the contrary, the lack of adaptability is the proof of a bad concept!). Sometimes, a specific aspect of the concept can be changed during development. However, we must follow our guidelines and keep the original objective in mind. Otherwise, the developer may create something of little use to the targeted user, because the application could be too “vague” in its features.

In the case of PO Merger, the concept of the application is intrinsically connected to WordPress. The ultimate goal of the tool and the target user have been well defined and have never changed.

PO Merger must take two WordPress PO files (which can come from a plugin, a theme or the “kernel” of WordPress), check for missing translations in the first file and find them in the second file.

At the end, the application must produce a new file with the merged content. The tool will be used by contributors to WordPress translations. Of course, optional parameters were considered from the beginning. But some aspects have been modified or abandoned during development while other options and features have been added, however the basic concept has always remained the same.

The choice of programming language was simple: we chose PHP. The WordPress core uses PHP and it’s the language best known and accessible by users in the WordPress ecosystem.

A user interface, which would allow the user to choose two existing files and revise the merged content was considered during the conceptualization. However, the idea did not survive the development, as we will see a little further. Once again, this underscores the importance of a solid foundational concept and the importance of not starting the project through the user interface, but of sticking to the desired processes and results.

Development

Development is literally the “proof of concept” because the viability of the idea or its impracticability will appear very quickly during development. In considering this, all “portions” of the project should be as much as possible “independent” from each other. Otherwise, a significant conceptual change could force the developer to rework the entire codebase, if he did not use a modular approach. Two other key aspects are to a) structure the project well and b) ensure the quality of the code. These aspects should be the norm for any project, but even more so when future feature additions are planned from the start.

As I mentioned above, a user interface was part of the initial concept and a “skeleton” interface had begun to be developed. However, the fact that the interface would have the same functions as the specialized tools (and therefore much more developed) like, for example, Poedit, has made the interface a much less attractive to us.

It has therefore been decided to change the concept: the user will use a command line to enter the required parameters and will use existing (and well developed) tools to review the result. WordPress offers a command line interface with WP-CLI. Thus, the tool has been transformed into a “package” that can be added to an installation of WP-CLI. The user must install it and enter the parameters via the command line, using the command defined by the PO Merger package.

Usage

Here is the command and an exemple showing basic parameters:

wp po merge fr-ca fr https://wordpress.org/plugins/wordpress-seo/

We can decompose the command into elements, resulting in this:

• wp – WP-CLI
• po merge – the PO Merge package’s command
• fr-ca – the base locale with missing translations
• fr – the copy locale from which translations will be searched
• URL – the homepage of a WordPress plugin or theme

The translating link can be used instead of the homepage’s URL:

https://translate.wordpress.org/projects/wp-plugins/wordpress-seo/

In the case of the WordPress core, the command would therefore be:

wp po merge fr-ca fr 5.1

Here, the “5.1.” refers to the version of WordPress.

If all command parameters are valid, a new file with the “-merged” suffix containing the merged content will be generated in the folder in which the command was executed.

Here is the original Base PO file (click for full-width):

Here is the originale Copy PO file (click for full-width):

And here is the Resulting PO file (click for full-width):

PO Merger also comes with an array of optional parameters. For example, the “diff-only” parameter downloads the Base File with only the lines that aren’t translated:

wp po merge fr-ca fr https://wordpress.org/plugins/wordpress-seo/ --diff-only

In order to have an overview of all available parameters, I invite you to visit the package’s README which contains the complete documentation as well as the installation procedure.

In conclusion

PO Merger is not a magical tool that will solve all the problems related to the translation of WordPress. However, in some cases, it may be able to avoid hours and hours of manual labor, not to mention avoiding human error. Some design issues were significantly changed during the development phase, but our modular approach allowed us to make these changes without reprogramming the entire application. And now, considering that the package for WP-CLI is available to the public, maybe you’ll be the next one to improve it!

Term definitions

• Package : a module that adds one of multiple functionnalities to an application, a website, etc.