A multilingual OL Connect template can handle content and static text elements in more than one language. Traditionally this is achieved by creating a template or section for each language variant. This approach complicates content updates and template maintenance. Alternatively one can create JSON snippets holding the translated strings and create scripts to apply these strings to the sections and snippets. This requires you to implement the scripting logic.

In both scenarios there isn’t an optimal workflow to get the strings translated by a translator. The Translation feature introduced in OL Connect 2019.1 simplified this and provided options to export translation strings in a standardized file format known by translators and their software. OL Connect Designer lets you import translated string files using drag & drop and applies the translations based on the current locale. The locale can be explicitly set for the template or dynamically defined by the value of a data field. The Translation feature also handles pluralization of strings without you having to write a single line of code. This article explains the translation round-trip and provides some additional tips and techniques.

Translation files

Connect uses the .po (Portable Object or PO file) and .pot (Portable Object Template or POT file) extensions for the translation files. These use the Gettext format, which is widely used in the open-source world. Popular systems, like WordPress and Drupal, use this text-based format to translate plug-ins and themes. PO files hold translated strings for individual languages. So when your template needs to be outputted in French and German in addition to English, you will need two PO files (fr.po and de.po). In this case, English is the base language which was used to design the template.

After designing the template you can use the Translation feature to generate the POT file. This file contains all strings in the base language (in the case above this is English) and is the starting point for your translators/agency.

So in short: POT files are translation files which contain no translations while PO files hold strings for a specific locale.

The Connect translation workflow

The translation workflow in a nutshell:

• Tag page elements for translation (for example paragraphs, headings, table cells, buttons, labels etc.). This adds the respective strings to the Translations view.
• Export the strings to a .pot file. This file is send to translators.
• Translators translate strings, the result is a .po file.
• Add the .po file to the Translations folder located in the Resources panel.
• Set the locale for the template either to a specific locale or set it dynamically based on a data field.

Tagging elements for translation

In Content, translations are handled per HTML element. In order to mark a string translatable you will need to tag the element holding the string. This indicates that the content of the element should translated. This creates a new entry in the Translations view and adds the data-translate attribute to the element. The latter can be verified when viewing the HTML in the Source view. The entry in the Translation view states the text content of the tagged element. This will be the key that is used by the internal translation algorithm.

To tag an element for translation:

1. Choose: Window > Show View > Translations
2. Place the cursor in the respective element or select the element via the Outline view. The last entry in the breadcrumb shows the selected element.
3. Click the Tag Element icon in the toolbar of the Translations view. The text content of the element is copied to a new translation entry.

Note! Changing the text in the document after the element was tagged will break the relationship. This can be resolved by editing the entry in the Translations view or use the Sync button.

Placeholders

The string may include placeholders for data fields (e.g. Dear @name@). Typically translators are familiar with strings containing variables. One could leave a comment explaining that the placeholder is used as a variable and that this text should not be translated (this would break your personalization script).

To add a comment, simply double click the entry in the Translations view and enter instructions in the Comments field. This information will be added to the POT file and visible for translators in their translation tools.

Nested HTML

When an element includes nested HTML structures be careful to leave these in. The string presented to the translator will shows this code too. This is typically not a problem for simple bold and italic elements but more complex elements like hyperlinks could cause problems. The translator may accidentally modify the respective code and break the hyperlink.

The easiest way to avoid this situation is to split the text around the structure into separate chunks, no matter how short. This is achieved by selecting the respective text in the template and select Wrap in Span… in the contextual menu. Subsequently tag the new <span> element for translation.

Export strings (.pot)

Once all translatable elements are tagged, you are ready to create the POT file. Click the Export button on the toolbar of the Translations view. A dialog appears allowing you to specify the name and target location for the POT file.

The POT file contains a list of all strings (including comments) and will be used by the translator/agency to create language specific PO files.

Create translations using Poedit

There are many solutions available for translators. Poedit is a shareware and cross-platform editor to aid in the process of language localisation. Let’s take a look how to create a PO file based on a POT file generated by OL Connect Designer.

To start a new translation in Poedit:

1. Choose: File > New from POT/PO file
2. Locate and select the POT file and click Open. The Translate Language dialog appears.
3. Select a target language and click OK. The translation editor appears showing a list of our strings.
4. Select an entry in the Source text list and subsequently enter the translation in the Translation field.
5. Once you have completed all translations choose: File > Save and save the PO file to disk.

Tip! When you missed an element in your Connect template, simply tag the element and update your POT file. Subsequently toggle to Poedit and choose: Catalog > Update from POT file… Changes will be merged into the PO file.

Import translations (.po)

Importing the PO file is as easy as drag and drop the file from the file system to the Translations folder located in the Resources view. Alternatively use copy and paste from the same location. The PO file is stored with the template. The following image shows PO files for Dutch, German and Canadian French.

Double click the PO entry to invoke the text editor showing the text format of the PO file. It is a plain text editor so one could make modifications to the source. In this case you should send a copy to your translator/agency to keep them in sync.

OL Connect Designer monitors the PO file on disk (in the last known import location) for possible changes. When changes are found a small asterisk icon decorator is shown for the respective PO file in the Translations folder located in the Resources view. Right mouse click the entry and choose Update from the contextual menu to import the latest changes.

Applying translations

Before the OL Connect can apply the translations we need to set the Locale. This can either be explicitly set (e.g. all records use the some locale) or it can be linked to a data field. In this case the data field needs to contain the proper locale name. A locale name usually has the form ‘ll_CC’. Here ‘ll’ is an ISO 639 two-letter language code, and ‘CC’ is an ISO 3166 two-letter country code. For example, for German in Germany, ll is de, and CC is DE. Connect supports the underscore or dash as separator character.

To use an explicit locale for your OL Connect template:

1. Choose: Edit > Locale…
2. Change the Use field to Explicit local.
3. Select the required locale name from the Locale drop down.
4. Click OK store the setting.

To set the locale based on data field (requires a field holding the locale name):

1. Choose: Edit > Locale…
2. Change the Use field to Data field.
3. Select the data field holding the locale name from the Data field drop down.
4. Click OK store the setting.

Behind the scenes

Translations run before all User Scripts and are automatically applied when adding content to the document using the html() command.

The translation algorithm checks the current locale and retrieves the strings from the matching PO file. In case no matching file was found the template will use the strings in the template (e.g. not apply translation logic).

Translating plural forms

Plural nouns are words used to indicate that there is more than one. In certain languages there are more than 1 plural forms. For example: Czech and Polish have 3 plural forms where Arabic has 6 plural forms. But let’s take a look at the following example:

This order contains 1 product(s).

The pluralization options allows you to show the singular and plural forms for the noun product. In other words:

This order contains 1 product.

or

This order contains 10 products.

Instead of writing a custom script we can use the pluralization option of the Translation feature. In Design mode the text looks like shown below. A User Script will replace the @num_products@ with the value of a data field.

This order contains @num_products@ product(s).

To instantiate pluralization:

1. Place the text cursor in the text.
2. Click the Tag Element icon on the toolbar of the Translation view. An entry is added to this view.
3. Double click the entry to open the String Options dialog.
4. Select the Pluralization checkbox. The Singular, Plural and Data Field fields become available.
   1. The content of the Source field is copied to the singular and plural fields for your convenience.
5. Enter the proper singular and plural values.
   1. These are the strings send to the translator/agency.
6. Select the data field which holds the value for the pluralization logic. The drop down is limited to fields at the root level of the Data Model.
7. Click OK to store the options set for this string.
8. Generate a POT file using the Export button on the toolbar of the Translations view.

The Poedit user interface shows two or more translation tabs. As mentioned some languages can have more than one plural forms, each will be presented in a separate tab. The following image shows the Singular and Plural tabs for the Dutch language:

Save the PO file and import or update it in your OL Connect template. When toggling to Preview or generating output the correct form will be determined by the value of the data field set for this string entry.

Tip! Pluralization also works without using actual translations. So use a de_DE.po file in your German document just for pluralization. Simply create the POT file and generate the PO file for your language. Import the PO file and make sure you set the proper Locale.

Easter egg! For languages that only have a singular and plural form there is no need to create the POT and PO file. Simply tag the element, enable pluralization and enter the proper singular and plural text. The application will automatically fallback to these definitions when no PO matching is found.