Localization

aka The option #3 from joomla/jissues#124

Translation 101

After you changed the code in your PHP or Twig files you should run

If you want to translate yourself you do a

After changing the po files you have to clean the cache to “see” the translations on the site. This can be done by simply deleting the /cache/g11n directory or, if you are logged in with an admin account, using the “clean cache” command from the “System” menu.

How it works (The option #3)

I might have stated before that I’m a very lazy person. So I like to spend my time creating scripts that do the “ugly work” for me. - Like the creation and maintainance of language files :P

The proposed solution to the above mentioned problem implemnents a (still) experimental language handler, that has not been tested out there in the wild.

The basic idea is:

The language file format to use in JTracker will be po (gettext), the result is stored to a “native PHP array” which is written to a text file. Other options can be explored.

3a) Required changes

Changes to hard coded strings in Twig templates and PHP code:

// template.twig
<label>
    My String

    // change to:
    

    // **OR** just use a pipe and a shortcut:
    My String
</label>

In PHP you would use the global function with an easy to remember name; g11n3t (*)

echo g11n3t('My String');

… and go home !

(*) btw: g11n3t means globalizationtext. If you don’t like it, you may create your own alias ;)

The next step would be the creation of the language files.

3b) Language template creation

For gettext files, you first create a template that contains all the keys and empty values. These templates are used to create and update the localized language files. The file extension for template files is .pot.

# Extension.pot

msgid "My String"
msgstr ""

These files can be created and maintained manually, however… I’m a lazy person (did I say that before ? )

The gettext utility xgettext can read a wide range of code languages and supports a custom function name. It supports over 20 languages officially, others just “work” (like JavaScript can be parsed as Python…) but the only unsupported language I know is Twig :( Fortunately this is a known issues, so the solution is to compile the templates and then run xgettext over the generated PHP code.

There is a new script that just collects all relevant files and passes them, along with some options, to xgettext:

tracker.php make langtemplates

Will automatically generate the language templates for the core JTracker application, the JTracker template as well as all the Apps.

Those language templates, once created, are now ready to hand over to the translators or send them to an online translation service (e.g. transifex).

Job finished :)

3c) Localize It !

To actually “see” the site in different languages, you have to create a file that contains the localized strings for every language. The extension for language files is .po.

For example a german language file might look like this:

# de-DE.Extension.po

msgid "My String"
msgstr "Meine Zeichenkette"

A chinese language file might look like this (google says..):

# zh-CN.Extension.po

msgid "My String"
msgstr "我的字符串"

and so on…

Translators may notice here, that you always see the original in clear text above the translation. – If you plan to handle the translations manually…

While you can also create those files manually, the gettext tools msginit and msgmerge can create and update language files from a given template - So why not use them (remember: me lazy…)

tracker.php make langfiles

will create language files for the core, the template and all extensions (Apps) in all defined languages.

What else ?

System requirements

To manually create and manage your language file(s) you will need:

To have your language files created and managed automatically you will need:

The gettext utilities should be available or installable on all *nix based systems, as well as some sons/daugthers and parents (like BSDs and apple stuff). If you are stuck on windows, your best bet may be cygwin (as always). There is also MinGW, a sourceforge project, as well as this site. I have not tried any of the above currently beside my own linux box, but I believe that if would be no problem for a windows developer with decent skills to modify the script ;)

Known issues

Usage in the virtual environment

The virtual environment already has the gettext package added, so creating and updating language files can be done from here, in case a developer can/will not install gettext on his/her operating system.

It goes like this:

vagrant ssh
cd /vagrant/cli
./tracker.php make langtemplates
./tracker.php make langfiles

It would be nice if a “non-Linux” user could test this :wink:

Refs