Translations

Information on translating and localizing LnBlog.

Summary
TranslationsInformation on translating and localizing LnBlog.
Translation MechanismsLnBlog supports two distinct translation mechanisms.
Translation InterfaceLnBlog uses four key functions to translate strings.
Basic gettext Translation StepsTranslating LnBlog with GNU gettext is a little esoteric, but not really all that difficult.
Ad Hoc Translation FormatThe ad hoc translation mechanism used by LnBLog takes the form of a simple PHP array.
Charset issuesAll LnBlog templates are encoded with the UTF-8 character set and are restricted to only characters in the 7-bit ASCII range.
Contributing TranslationsAnyone is welcome to translate LnBlog into any language whatsoever.

Translation Mechanisms

LnBlog supports two distinct translation mechanisms.  The recommended method is to use the PHP module for GNU gettext.  The “fallback” method is an ad hoc function that reads strings from a file in a PHP array.  This is provided because gettext, while widely used in the free software community, is not a standard PHP module and so is not available on all web hosts.  If you wish to provide a translation to be included with LnBlog, then please try to support both options.  Note that, with a little scripting ability, a gettext translation could be automatically converted to the ad hoc format.  Such a tool will probably be included with LnBlog in the future.

Translation Interface

LnBlog uses four key functions to translate strings.  When extracting translatable strings from the source code using xgettext, you will need to account for these.  They are listed below.

_()The simple translation marker.  This function simply returns the translation its single argument.  If no translation is available, returns the argument.
p_()Print translation.  Like _(), but prints the translation instead of returning it.
pf_()Print formatted translation.  Like p_(), but allows printf() scancodes to be embedded into the string.  Like printf(), this takes a variable number of arguments, with the first being the string to translate.
spf_()Like pf_(), but returns the translation instead of printing it.  This is analogous to sprintf in the same way that pf_() is analogous to printf().

To extract the strings translated by these functions, you can use the --keyword argument to xgettext, which comes with GNU gettext.  The exact command for this is given in the next section.

Basic gettext Translation Steps

Translating LnBlog with GNU gettext is a little esoteric, but not really all that difficult.  In this section, we will walk through the steps of creating and installing a translation.  For a more detailed tutorial, I recommend Gora Mohanty’s “A tutorial on Native Language Support using GNU gettext” available at http://oriya.sarovar.org/docs/gettext/.

To do the translation, you will need a copy of the GNU gettext utilities.  On all modern Linux distributions, these are either installed by default or available from standard package repositories.  On Windows, you will need to download them separately.  The GNUWin32 project has a handy installer available at http://gnuwin32.sourceforge.net/packages/gettext.htm.  You will simply need to run the installer and add the “C:\Program Files\GnuWin32\bin” directory to your path.

The first step is extracting the translation strings.  (If a messages.pot file was already included in your copy of LnBlog, you may skip this step.)  If you are using a UNIX or Linux system, then you can do this by opening a command prompt, changing to the LnBlog directory, and running the following command.

xgettext -LPHP --keyword=_:1 --keyword=p_:1 --keyword=pf_:1 --keyword=spf_:1 -o messages.pot `find -name "*.php"`

This will create a template PO file that will be the basis for your translation.

The next step is to your initial translation file.  To do this, run the command below.

msginit -l en_US -o LnBlog.po -i messages.pot

This example uses en_US as the locale for the translation.  You should, naturally, substitute the actual language and/or country code for which you are translating in the -l option.

Now you are ready to start translating.  The actual translation consists of simply editing the LnBlog.po file.  You may do this with a standard text editor, with GNU Emacs PO mode, or with a special PO editor such as KBabel.

Editing the PO file in a text editor is pretty straight-forward.  When you open the file, you will see a number of line pairs, labeled msgid and msgstr respectively.  The msgid is the untranslated English text that appears in the source code.  The msgstr is the translated value that gettext will display.  You simply need to go through the file and translate the msgstr lines into your language.  You should note that some lines include scancodes such as %s and %d.  These indicate that a word or number will be substituted into the line in that position.

Once you have finished translating your LnBlog.po file, it is time to build the binary translation file that will be used by gettext at runtime.  To do that, use the following command.

msgfmt -c -v -o LnBlog.mo LnBlog.po

Installing this file is as simple as copying it into the appropriate directory.  The exact directory depends on the locale, but the basic pattern is

LnBlog/locale/en_US/LC_MESSAGES/

Once this directory is created and your LnBlog.mo file copied into it, you are done.  Just edit your LnBlog/userdata/userconfig.cfg or LnBlog/userdata/userconfig.php file to set the LANGUAGE configuration constant to the correct value (or you can use the $LANG environment variable) and should be able to see your translation working.

Ad Hoc Translation Format

The ad hoc translation mechanism used by LnBLog takes the form of a simple PHP array.  The translation file must create the array and populate it.  Each element of the array will be indexed by the untranslated US English text and will contain the translated text as its data.  If you are familiat with GNU gettext, the array index is analogous to the msgid and element content is analogous to the msgstr.

Here is a simple example of an ad hoc translation file.  Note that the PHP opening and closing tags are required, as is the array creation on the second line.  Also note that there can be no characters ot whitespace outside the PHP tags.

<?php
$strings = array();
$strings["My message."] = "Translated message.";
?>

Charset issues

All LnBlog templates are encoded with the UTF-8 character set and are restricted to only characters in the 7-bit ASCII range.  Any translations should use a character set that is compatible with this, as the internationalization system does not do any character set conversion on the HTML code in the various theme templates.  In other words, if you do a translation, it is best if your text is encoded in UTF-8.

Contributing Translations

Anyone is welcome to translate LnBlog into any language whatsoever.  If you would like to have your translation added to the official distribution, then please contact me at pag.nosp@m.eer@skeptic.nosp@m.ats.com.

Close