Translating this plugin

Overview

This article will cover the information, tools and instructions to create and submit a translation for the Advanced Custom Fields plugin.

Information

There are a number of ways you can create translations but the end result is always the same. You will end up with two files, a .po file and an .mo file. The .po file is a human-readable translation file. You can open it in any text editor and edit it. The .mo file is a much smaller but completely unreadable compressed version.

WordPress will use the .mo file (for the current language) to swap out strings (text) throughout the Advanced Custom Fields plugin making it readable.

For more information, please read Everything You Need to Know About Translating WordPress Plugins by Daniel Pataki.

Tools

poedit

To create and edit translations, we suggest using the fantastic and free poedit app. This app allows you to easily create new translations for any language, edit existing translations, synchronize strings and also generate the .mo file.

github

To gain access to upcoming versions and push updated translations, we use github.

Translations are to be made for the ACF PRO plugin, which is held in a private repository. To become a translator and get access to this repo, please contact our support team with your details including github username and language. If you don’t own a paid Github account you don’t have to worry that your fork will become public. The status of the acf-pro source repository will be entailed to its forks. Everything will remain private and hidden.

Once you have been added to the ACF PRO repository, just hit the fork button in the upper right corner of the repository page. From your acf-pro github repo you can pull a local copy to your computer, edit the translation files, commit the changes and push them back to github. Next you click the green compare button (in your acf-pro repo) to initiate a pull request.

git

To pull, commit and push changes to github, we suggest using the Git Tower app. Git actions can also be performed in the command line. A good summary regarding getting up to speed in Tower as well as in the Cli could be found here (https://www.git-tower.com/learn/git/ebook/command-line/introduction) and here (https://www.git-tower.com/learn/git/videos)

Instructions

Create a new translation

  • Contact our support team and request to become an official translator
  • Gain access to the acf-pro repository on github
  • Pull the latest version of the remote repo to your local repo.
  • Open  Poedit
  • Choose “New from Po/POT file”
  • Select the pot file within /lang/acf.pot
  • Select the new language you wanna translate. Choose the country if you want the language in general e.g. French or if you wanna be more exact you select French (France) or French (Madascar) to take local dialects into consideration.
  • Go to the .po file preferences

Translation settings

  • Project name and version should be best set to the current name and version. e.g. Advanced Custom Fields 5.2.8
  • Language. That setting reflects the initially chosen language for the .po file.
  • The plural form radio button should be set to the default rules for the chosen language. Basically it is the key mapping the two plural forms from the english strings in the php source to the number of forms necessary in the chosen language.
  • Encoding of the source code should be set to UTF-8
  • Translation team and the email address where the translation team could be reached should be set to the initial and main maintainer of the specific language.
  • Source path should be set to .. which is the relative location of the root directory to the lang directory
  • Path should be set to .
  • Excluded paths is set to ignore all javascript files by *.js
  • Keywords from the source code – The following is a mix of all available PHP as well as WordPress specific functions necessary to define localizable strings in WordPress templates. The list shouldn’t be altered and looks like the following:

Keywords

__
_e
_n:1,2
_x:1,2c
_ex:1,2c
_nx:4c,1,2
esc_attr__
esc_attr_e
esc_attr_x:1,2c
esc_html__
esc_html_e
esc_html_x:1,2c
_n
_noop:1,2
_nx_noop:3c,1,2
__ngettext_noop:1,2

if everything is set correctly in the .po file preferences; as a precaution go to the menu “catalogue->update from source” to take care in case the pot file isn’t reflecting the latest state of the source that you get the latest strings.

Now you can start translating the available strings. You can run into three different kinds of translations:

Regular strings

If you select a string you get two fields underneath. Source text and translation. The former you can’t edit while the latter you can enter your translation into.

Plural forms

depending on the number of plural forms your language requires you get the necessary number of tabs where you have to fill in the varying strings. Japanese would only show a single tab, english two for singular and plural while polish shows three. At the moment ACF Pro has three strings you have to mind plural forms, which number 68, 70 and 561.

Comments

The comments behave exactly like the regular strings. The only difference you get an explenatory context; mostly used for brief copy writing. The only string at the moment is number 485.

When you are done choose Save as and prepend acf- so the French Madascar .po version would be called acf-fr_MG.po

Workflow

  • As soon as a point in the plugins development cycle is reached where the translateable strings aren’t changed anymore an email is sent out to all registered translators.
  • If you are the translator listed with his name and email in the .po file you pull the latest revision of the remote changes upstream.
  • In Poedit you hit “update from pot file” to take care the pot file and your languages .po file are on par.
  • You make the translational updates, commit the changes and then place a pull request like explained before.
  • In case you aren’t the translator listed in the .po file header, but you have the time and motivation to take care of the translation updates in this release then you contact the listed translator and ask if he or she is already in order of translating. So it could be prevented that no extra work is done.
  • In case you find any translations inappropriate after commit you could open a issue on github with the tags translation and fr_FR for the french translation.

Credits

Co-written by Ralf Koller