Localisation in ZenMagick

Localisation, that is, the ability to translate page content is implemented via some custom zm_l10n... functions. Bascially, all text that might need be translated is wrapped in one of those functions.

Default language for all text in the default theme and anywhere else in ZenMagick is english. This is perhaps discrimatory, but the alternative would have been german, so I think we can agree I made the right choice

Since a lot of sites are in english this means they do not have to do anything to use the default theme. Since the text is actually in the files, rather than in a separate file, it is also easy to change.

As an example, zen-cart would do someting like this:

echo ENTRY_EMAIL;

while in ZenMagick the same would look similar to this:

zm_l10n("Email Address")

Arguably, the second is easier to read, even though at the cost of a function call. In order to translate a string in ZenMagick, a file l10n.php needs to be created that contains mappings from english as the base language to the translated string.

The file would be located in the themes language folder inside a language subfolder. For example, the italian mapping file would be languages/italian/l10n.php.

Even though the file is usually to translate into other languages than english, the same mechanism can be used to change the english text without touching the template files. Some exmaples can be found in the default theme itself. The mappings are set up to make crumbtrails and sorting options look nicer.

So, looking at the ZenMagick code one might ask: ZenMagick claims that all HTML/content is customisable, but what about the l10n strings used in the ZenMagick core code?A legitim question, whose answer is in the above. Since all l10n string can be mapped to different strings, so can be the ones that are used in the ZenMagick core code.

Formatting

One thing that is worth mentioning in this context is that there has been taken some care to avoid string concatenation. Doing that would severly limit the way strings could be replaced and values inserted in different places.

To avoid this, zm_l10n functions accept a variable number of parameters and effectiely work like sprintf(..). This gives translaters the option to control where in the text each parameter should be places.

Please check out the PHP documentation for more details - they do a much better job explaining that than I could ever do.

Chunks

While the localisation functions are quite handy, they can be cumbersome with large pieces of text. Examplescould be the text for popups, disclaimer, etc. Those pieces of text usually do not require inserting dynamic values which makes them just very big strings.

Since they would have to be in full in every place they are used it would also make it harder to change them. To avoid this, large pieces of text - chunks - can be stored in separate files in the language directory. A separate function zm_l10n_chunk_get exists to display text stored in those files. It takes a single parameter which is the name of the file without the ‘.txt’ extension.

Finding strings to localize them

In order to help people find strings and make it easy to create mapping files, there is a admin tool to create mapping tables that include all theme strings (unless the code that extracts them has bugs!). The ZenMagick Language Tool lets you create lists of all localised string per file and if you download the list it will be in a format ready to cut’paste into an l10n.php file.

The only strings missing are the ones used by ZenMagic code itself. There aren’t many and most of the would be in the net.radebatz.zenmagick.html.default package anyway. The code in that package is designed with the option to copy it into custom themes in order to modify it. If you prefer to keep using them there are two ways to find strings used in core.

1. Browser the source code
   This is probably good enough if you have a rough ideas as to where the string is used. It is also worth trying a
   search for ‘zm_l10n‘ in the core folder.
2. Modify zm_l10n to log unmapped strings
   This requires to make changes to core code, so it should be only temporary. The function in question is _zm_l10n_lookup and is, not surprisingly, located in core/l10n.php. Uncomment the following line and all unmapped strings will be logged in the configured error log:
   //!isset($l10n[$text]) && zm_log(”can’t resolve l10n: ‘”.$text.”‘”, 3);

Internationalisation

In contrast to zen-cart, internationalisation is handled separately from localisation. The code is a similar set of zm_i18n... functions.

Configuration is done in a corresponding i18n.php file in the same folder as l10n.php. The configuration includes setting up thedesired date and time formats and a couple other things that have traditionally been defines.