Dev:Internationalization

From Habari Project

(Redirected from Dev:Translation)
Jump to: navigation, search

It is easy to implement translations in your plugins and themes. Habari provides several functions that will help you to include strings you want to be translated. There are also scripts and tools to make preparing translations easier.

Please note that this guide is mainly for Linux users. For windows, there are good graphical tools like PoEdit. Please refer to their manuals to see how to perform the process described here.

Contents

How it works

You will perform the following easy steps:

  • Change your code to use translated strings
  • Get the strings out of your code into a template
  • Use that template to make catalogs for each language
  • Use the catalogs to create translations
  • Compile the translated catalog so Habari can use it
  • Provide the template and the catalogs to others so they can help with more languages
  • Refresh template and catalogs if strings are added or changed

Prepare your code

Translations are managed via text domains. So the first thing you should do is adding the following line to your theme's or plugin's action_init() method:

$this->load_text_domain( __CLASS__ );

That will load the text domain named exactly as your plugin's class, including the case. You will need that name soon.

To make strings translatable, Habari provides some functions. The easiest is:

_t( 'translatable string', 'text domain' );

This will simply look into the text domain if there is a translated value for that string and if so, use it. The strings in your code should always be English so everyone has a chance to understand it if there is no translation for his language yet.

You don't want values you insert into your strings translated, for example post titles. _t() takes care of it. Just supply an array with the values you want to be replaced.

_t('Post with title %s created', array('awesome post title'), __CLASS__ )

When you want to output your string anyway, instead of

echo _t('your string', __CLASS__ );

you can write

_e('your string', __CLASS__ );

which does exactly the same. _e() also supports string replacement with arrays as shown above.

Extract strings

The strings from your code have to be stored in a .pot file (the template). From that .pot file, you can create a .po file (the catalogue) for each language. .po files will then be parsed to .mo files, but we get to that point later.

With a Linux console and gettext, you can extract the strings easily. Just call

xgettext -o locale/yourfile.pot --no-wrap --add-comments=@locale --language=PHP --from-code=utf-8 --keyword=_n:1,2 --keyword=_ne:1,2 --keyword=_t --keyword=_e $(find . -name "*.php")

for PHP code (replace yourfile with the exact class name, regarding the case) and

xgettext -o locale/habari.pot --no-wrap --add-comments=@locale --language=Perl --join-existing --from-code=utf-8 --keyword=_n:1,2 --keyword=_ne:1,2 --keyword=_t --keyword=_e $(find . -name "*.js")

for JavaScript. See also https://github.com/habari/scripts/blob/master/rxgettext.sh

That will get you a pot file in a locale subdirectory. If you don't have access to a Linux console, there are also GUI tools that provide similar functionality, like PoEdit.

Create and compile translatable catalogs

From that .pot file, you can now create a .po file (the catalog) for each language. The following command will do that:

msginit --locale=de --input=MyClass.pot

if your language code is "de" and your class is named exactly "MyClass" - mind the case!

If you are done translating, you can make a binary version of your catalog that Habari can use. If you have downloaded custom translations for Habari itself, you will know this step.

msgfmt -o MyClass.mo de.po

The above command will name the catalog (po) file after your language code by default so I didn't change that in the example. The binary (mo) file has to be exactly the class name again.

Move that file into a subfolder locale/de/LC_MESSAGES/ in your plugin's folder and you are done!

Translation hints

You must specify the plural forms like this (the tool of your choice will ask for them):

nplurals=2; plural=n==1?0:1;

If you edit the .pot file manually with a text editor, use this line:

"Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"

Name the .po file exactly as your class name, regarding the case, and save it to a subdirectory locale/xx/LC_MESSAGES where xx is your locale code.


Personal tools