Using Document Translation

Dynamo Template can use two types of translation resources: document translation and Salesforce translation.

Document translation is an internal resource managed through template builder. It provides translation matrix that is independent of any external translations. Salesforce translation is a resource that is managed in Salesforce translation workbench and then imported to the template.


Using Document translation

Translation tab

Translation tab can be found from Data Source tab at right side of the document template editor. If translation is not enabled, click "Enable Translation".

Translation tab shows "Add Translation" button and all available translations under translation resource name which is typically "labels".

Adding translations

New document translations can be added by selecting an element (without assigned dynamic content) or selecting/painting an inline area. After that pressing "Add Translation" button will open "Add Translation" dialog. Dialog will show defaults for translation key, text and language. By clicking "OK" new translation will be added for defined language in translation matrix. New translation key will appear in the "Translation" data source and the element that was selected is linked to the translation key through "Content" attribute.

Document translations can be defied also in translation part. Clicking the "translation part tile" in "Dashboard" view or edit button in "Translation" tab will open translation editor. Translations are presented using matrix with single translation key column and several language columns. Every language has own column where first row value is used as the language key. It's recommended to use ISO 639-1 language codes like en (English), de (German), fi (Finnish).  Other translation matrix rows present translation texts. Translation key in the first column is used to map translation text to the document.

If language key or translation key is not found, the placeholder text will stay in the document output.

Creating translations from document

When translation matrix is not yet defined, the document can be created using one of the wanted languages. After document is ready, text can be divided to translations  with unique keys. Every translated element needs own translation key and text. If full text spans over several paragraphs, every paragraph needs own translation key and text. Translated paragraph can’t contain inline (static or dynamic) elements. If translated area needs to have dynamic content, then the area must be divided into two different parts. 

Easiest way to add translations is by clicking "Add Translation" in "Translation" tab. 

Defining language

When translation mapping is in place, the element content will be replaced with a language text. Language is selected using e.g. a field value from Salesforce, if value will match with the language key, that language will be used. 

Translation matrix variable and correct language is selected and initialized with <setTranslation> command. This command must exist before <composeContent> command to be effective. Language attribute value must match with one of the translation matrix column keys. 

When translation is enabled from the translation tab, <setTranslation> command will be added to main flow and the language attribute is set to use  "documentLanguage" variable.  Document language is set by default to "en". This variable can be locate from the variables tab.  Any Salesforce field could be used to control the selected language as long as the field values match language keys. Template designer could also add more complex mappings between Salesforce values and language keys by using choose-when-otherwise logic.

Please note that the content visible in the template’s mapped elements is just placeholder text that will be replaced when document is generated.

Translating picklist values

After enabling the Dynamo document translation feature, in order to use Dynamo document translation on picklist values, please follow the 2 steps below:

  • Add the translations for each of the API values of the picklist field into the translation matrix
  • In the template document part where you map the picklist field, wrap the field inside labels[] tag (screenshot below) so that when the template evaluates all the dynamic fields, the field's value will be used as a key in the translation matrix

By default, when you map a picklist field into the template, the API value is displayed in the generated document. This picklist translation instruction is for this default case.