Sunday, June 9, 2013

PHP (and WordPress): Command-line 'gettext' Workflow from Scratch

Let's assume you are creating brand new code (for now say a WordPress plugin in PHP) intended for multi-language (internationalized) usage.

Writing the Code

Make sure to use the _() gettext function (WordPress: __(), _e(), and _x() functions) wherever translatable string literals are used, properly specifying the text domain as needed.
When using WordPress, make sure to call load_plugin_textdomain() from the 'init' action callback.
(Note that WordPress does not use the PHP gettext built-in functions, it has its own .mo file reader code in wp-includes/pomo directory.)

Files Involved

  • .po (Portable Object) files: ascii files containing translations (strings from the source code paired with translated strings
  • .mo (Machine Object) files: binary files containing the same information, can be read faster by programs
  • .pot (PO Template) file: contains untranslated strings only; usually completely overwritten after any code change (think of it as a temporary file used for empty .po generation)

The Initial Template

When the initial code is completed, a template ".pot" file needs to be created:

find . -iname \*.php | xargs xgettext --from-code=utf-8 -k__ -k_e -k_n:1,2 -k_x:1,2c -k_ex:1,2c -k_nx:1,2,3c -kesc_attr__: -kesc_attr_e -kesc_attr_x:1,2c -kesc_html__ -kesc_html_e -kesc_html_x:1,2c -k_n_noop -k_nx_noop:1,2c  -ctranslators: -o lang/messages.pot

Starting a new translation

An empty .po file needs to be initialized before we can start translating. Assuming we are translating into German:

cd lang
msginit -l de -o de_DE.po

For some reason, msginit creates a "de.po" file by default.
"locale -a" command to list all the locales installed on your system.
msginit sets encoding to ASCII, needs to be updated.

Translation Memories, Compendia

TODO: read pinfo about compendia & try tmx files.
- create translation memory: po2tmx -l xx -i pofiles -o xx.tmx
- apply it pot2po --tm=xx.tmx -i wordpress.pot -o wordpress_xx.po

Translating the Strings

Work can finally begin! Being a command-line and terminal enthusiast, I use VIm to edit the .po file; it has a great plugin helping in common tasks: po.vim.

Wrapping Up: Creating .mo files simple:

msgfmt de_DE.po -o

When using WordPress, make sure to prepend the "domain" to the .mo file name, e.g.

When the Code Changes

  • Re-create .pot file - see above
  • issue msgmerge -U messages.pot

Further Read
HTML-ized form of "info gettext":
PHP gettext docs:

No comments:

Post a Comment