Translating eZ Publish websites: a simple tool for template/script translations

eZ Publish is well-known as a Content Management System with built-in multi-language features. To present different translations of pages, eZ Publish uses 3 major components: content translation, content class translation, and template / script translation. In this post, we will explain these 3 components and introduce a script to help translate strings in templates.

Let's consider an example -- a product page -- to better illustrate the 3 components. A typical product page might have the main menu, a "login" link, product description text, a product image, and a product status like "Out of Stock" or "Available".

1) Content translation component

A product is represented by one content object in eZ Publish. eZ Publish provides editors with an interface to translate each content object into multiple languages. Editors would provide language-specific product description text, product name, and sometimes a different product image.

2) Content class translation

Each product content object is an instance of a product content class. eZ Publish content classes can also be translated. It is not only important for administration screens but in the case of a product status, also important for the front-end pages displayed to site visitors. The product status would usually be defined in the content class as a "Selection" field. The values "Out of Stock" and "Available" would thus be stored at the content class level and can be translated into multiple languages.

3) Template/script translation

Labels and text used in eZ Publish templates and custom (PHP) modules can be marked as translatable. Then, translations can be created for those strings in the form of XML documents on the file system. When configured correctly, eZ Publish will read the XML translation document relevant to the language that is currently being viewed, and replace the translatable strings with the equivalent translation. Examples of translatable strings at the template level include the "Login" and "Logout" links, and the label text on an HTML button.
While the content translation and content class translation components are relatively intuitive and well-documented, template/script translation warrants a closer look. In order to mark strings as translatable you have to use the "i18n" operator in templates and the "ezi18n" function in PHP scripts.

Then, you create the XML translation documents with a tool called "ezlupdate". (For more details, see this article at ez.no.) However, the process of creating and maintaining (whenever there are new strings) the XML translation documents is tricky, especially on some operating systems where you would need to compile "ezlupdate" or a similar tool. The process can be painful enough that we decided to create an alternative tool in the form of a PHP command line script. This script can scan an extension directory and create the relevant XML translation documents (with alphabetically sorted elements) from the translatable strings in your templates and module files.

You still need to open the XML document and add the translations for all listed text and labels in that document. You can use your preferred editor to do so. The previously mentioned article suggests the editor "linguist", which enables you to edit the XML documents quite comfortably.

Whenever new strings are added, the command line script will generate new XML translation documents. However, because the elements are sorted alphabetically, you can run a diff comparing the old and new documents to easily see which strings are new or obsolete.

The command line script to create the XML translation documents is available here. We welcome your feedback!