App Translator

This application manages the translation of DigitalSuite applications. Authorized users can use it to create translations in different languages using logical dictionaries whose keys are generated automatically.

Table of Contents

• App Translator
  • Glossary of common terms
  • Overview
  • How does it work?
  • Choosing an environment and displaying a dictionary
  • Create a Dictionary
  • Managing the existing dictionaries
  • Edition tools
    • Find and Replace
    • Batch Translation Tool
  • Additional features
    • Expanded View

Glossary of common terms

• Environment: Represents a specific application revision. It is composed of three elements: Project, Version and Web Interface or Process. For each environment you will be able to create one or more dictionaries.
• Dictionary: Represents the translation for each element of an application in an environment in a specific language.
• Designer Dictionary: The dictionary created automatically based on a web interface or process design. This is the default translation. This is the reference for creating new dictionaries in different languages.
• Entry: An element to be translated. It is displayed in a table for each existing dictionary when an environment is selected.
• Reference Dictionary: This is a read only column on the entries table and is used as a guide to ease the translation activities.
• Dictionary to Edit: This is an editable column. It allows the user to modify or add a translation for an entry.
• Empty template: This is a dictionary with no translations for the entries. It can be used as a template when creating a new dictionary.

Overview

When developing an application on the DigitalSuite platform, you can ask yourself : How can I enable my application to be used in different regions by different users who may not speak the same language? In other words: How can I internationalize my application?.

The App Translator application allows you to translate your DigitalSuite applications in many different languages, so that end users can see web interfaces in the language of their choice. This application allows you to manage the existing translations for the different environments of your account, by using dictionaries, which can be displayed, created, edited, deleted or imported for any particular application.

In order to internationalize an application, it is very important to include it in a project version; otherwise it won't belong to an environment.

Once you have created an application and included it in a project version, you can start to create dictionaries for it.

How does it work?

As you may know, the DigitalSuite platform allows you to create web interfaces to launch processes or to be used as a manual task. These web interfaces are composed of configurable widgets. Each time you add widgets to a web form, the DigitalSuite WebModeler will ask you to set its configuration such as an ID, a label, validation messages and so on...Depending on the widget type, specific configuration values may be required.

The app translator application allows those values to be translated in different dictionaries, so that the labels, validation messages and such can be displayed to the end users in different languages. We call this action the internationalization of an application.

In order to internationalize an application, the following requirements are necessary:

1. Include the application to internationalize into a project's version.
2. Provide the ID for each widget of the application to be translated.
3. Have an authorized profile to use the app translator application.

You may also need to internationalize the wording that is not contained in a widget configuration such as a label in a dynamic field and more globally any wording contained in a javascript script. To do this, you will have to use the following freemarker method to create a new key in the designer dictionary:

${i18n('text_id', 'value')}

text_id : the key id
value : the translation that will appear in the designer dictionary.

You may also need to use this Freemarker method for translating emails sent by processes.

When developing an application which uses JavaScript to set labels dynamically or any internationalizable text, it is important to consider the possibility that the translated text has quoted words, which will affect the behavior of the translation. To avoid this problem, the function "P_quoted", is provided for any DigitalSuite application, to allows the JavaScript interpreter to distinguish a quote within the string from the quotes that serve as string delimiters. Here is an example on how to use it:

${ P_quoted( i18n('tx_toolbox', 'User settings') ) };

In the previous example, the French translation for this phrase will be "réglages de l'utilisateur", which will produce an error if you do not use the "P_quoted" function, due to the apostrophe in the phrase. So, it is important to use this statement as a good practice each time you need to internationalize dynamic text using JavaScript.

Choosing an environment and displaying a dictionary

When you open the application, the first thing to do is to choose an environment. To do this, three list will be presented: Project, Version and Web Interface or Process. Only the project list will be available at the beginning. The button bar, that is used to manage the dictionaries, will be disabled until a valid environment is selected.

When you select a project, the Version list will be updated with all the existing project's versions. You can then select a version and the list of web interfaces or processes of the version will appear in the last list.

After choosing a valid value in the 3 lists (Project, Version or Web Interface or Process), the application will display a table with the following 3 columns.

1. Reference Dictionary: This column is read only and by default it will display the "Designer Dictionary", the dictionary created automatically from an application design. For Web Interfaces, each entry displayed in this table matches either a widget's configuration field or a key created using the app translator freemarker method. When the application has other dictionaries configured, they will appear in the dropdown list of the column header. You can select one of them in order to visualize it as reference.
2. Dictionary to Edit: This column is editable and is used to fill in the translation for each element. When the application already has dictionaries configured, they will appear in the dropdown list of the column header. You can select one of them in order to visualize the entries translation and you will be able to edit them. On the other hand, when the application has no dictionary, you will have to create one before being able to use this column.
3. Entry Id: The Entry Id column is a read only column and displays the ID of the entry. It can be used as a second element of reference to make the translation process easier.
4. Entry Source: The Entry Source is read only and shows the source of the entry (e.g. Widget, Menu, Basket, Custom, Application Information).

Create a Dictionary

To create a new dictionary, click on the "+" button in the button bar. This button is available when an environment is selected and will display a popup window :

In this window, you will have :

1. Dictionary language: A dropdown list with all the available languages that can be used to create a dictionary. Choose one from the list to proceed. If one language has been already chosen for another existing dictionary, it won't appear in the list as an option.
2. Dictionary name: You can provide custom names for your dictionaries.
3. Template: Here two possibilities are provided:
   • Empty: The dictionary will be created with no translations, so for each entry, the value will be empty.
   • Copy From: The window will expand to display 4 new fields to choose the source environment from which the dictionary should be copied. The new dictionary will be created by matching entries id from the source dictionary. When no translation is available in the source dictionary, the new dictionary will use the the translation from the designer dictionary. Copying a dictionary is very useful when you are dealing with different revisions of an application using different versions.

Once all the fields are filled in, the Create button is activated allowing the creation of the dictionary. You can create the dictionary and start editing it.

Managing the existing dictionaries

Once an application has dictionaries, many possible features are provided to maintain them by editing, deleting and creating new dictionaries.

1. Editing Dictionaries: To edit a dictionary, just type in an entry field for a new translation. The border of the entry that you modify will be highlighted and the "Save" button of the button bar will be activated. Changes are not be saved automatically : you will have to save them explicitly.

2. Saving a Dictionary: To save your modifications, just click on the Save button in the button bar. You will be asked to confirm this action because once the dictionary is modified, the changes cannot be undone.

3. Deleting a Dictionary: To delete a dictionary, you have to select the environement of the dictionary you want to delete and choose the dictionary in the column dictionary to edit. The Delete button will be activated. When you click on it, you will be asked to confirm the deletion. A dictionary deletion cannot be undone

4. Reload Environment: This button allows you to reload the dictionaries lists for a selected environment. By doing this, all the changes performed over a dictionary will be reset until the last saved point. To use it, click on the reload button provided in the button bar. If any changes were detected over the deployed dictionary, a confirmation window will appear to confirm the action. If the user proceeds, the dictionaries lists will be reloaded and all the unsaved changes will be lost. This action cannot be undone

Edition tools

In order to make the translation process easier, additional tools are provided:

Find and Replace

This tool allows you to search a given value in the Dictionary to Edit column. You can also search and replace the given value with another. To do this, click on in the button bar. A new floating window will appear:

From the moment that you provide a value into the find field, the buttons will be enabled and you will be able to :

1. Find and replace: This will let you execute a search in the Dictionary to Edit column until it finds an occurrence that will be highlighted. If you click again on the Find and Replace button, it will perform a replace action, overwriting the current value with the one provided in the replace field. If no value was provided for the replace field, the current value of the entry, will be replaced by an empty value.

2. Previous and Next: This button allows you to execute a search ascending or descending the column. It works only as a search functionality and does not take the replace field into account. However, if you click on the replace button, the currently selected entry will be replaced with the value provided in the replace field.

3. Cancel: This button is used to close the dialog window.

The find function looks for each entry containing the provided text, not just entry containing its exact content.

A checkbox field can be used to replace all the occurrences found without confirmation. It will perform the search through the whole column, and replace the occurrences found for each entry of the dictionary.

Batch Translation Tool

This tool is used to perform batch translations of recurrent wording. It is very useful when you create a dictionary from an empty template. It will help you fill in the translations in the edit dictionary. The idea is mainly to find a given text in the reference dictionary and, whenever an occurrence is found, to set the corresponding translation in the dictionary to edit.

To use it, click on in the button bar. A new floating window will appear:

The first field (From:) should be filled in with the text to be looked for in the Reference Dictionary column. Contrary to the Find and Replace tool, the batch translation tool will look for the exact value provided. The second field (To: ) should be filled in with the value that you wish to set for the corresponding entry in the dictionary to edit column. An empty value is allowed in this field.

Once you have filled in both fields, the button Translate All will get activated. Clicking on it will perform the batch replacement described above.

Additional features

Expanded View

This tool is present in every entry of the Dictionary to Edit and is used to edit long translations. When you hover over a field in the dictionary to edit column, a little parchment icon will appear at the right of the entry field. When clicking on it a new window opens with a large text box where you can easily edit the value for the entry.

When you are done editing the translation, you can click on either the continue icon to set value to the entry or on the cancel icon to dismiss the modifications.