Creating multilingual OL Connect templates

Creating multilingual OL Connect templates

Creating multilingual OL Connect templates

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.
Create an translation entry for an element

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.

Leave a comment for translators on translation entries

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.

Wrap a text selection in a span element to isolate the text 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.
The .POT file exported from your template shown in POEdit

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.

Translation resources

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.

Edited .po file showing dirty state

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.
Invoice shown in the base language (english)
Invoice text labels translated to French
Invoice text labels translated to Dutch

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.
Pluralization options for a translation entry

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:

Plurar controls in POEdit

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.

Tagged in: multilingual, Template



Leave a Reply

Your email address will not be published. Required fields are marked *



Similar posts you might also like


How to – Pass variables to a template

How to - Pass variables to a template

In this post we’ll show you how to use runtime parameters to effortlessly pass variables to a template. Runtime parameters provide an elegant way to pass information from Workflow into the document creation process without having to modify the data records or data model. Keep reading to learn more!

(more…)

Troubleshoot your User Scripts with the Script Debugger

The debugging user scripts

When developing complex OL Connect templates, User Scripts typically grow in number and complexity. You may encounter situations where they not always do what you expect them to do. See how the Script Debugger allows you to debug the scripts by tracing script execution and figure out the state of local and global variables.

(more…)

Conditional design elements

Conditional design elements

When creating personalized documents one often needs to make decisions based on data. A common example is showing/hiding one or more paragraphs depending on a field’s value. To achieve this OL Connect Designer 2021.1 comes with a wizard to simplify setting up these conditional elements. It allows conditions to check against multiple data fields and it provides predefined operations based on the field type (e.g. check if a boolean field is true or is false).

(more…)