www.qucamba.com
Level: Beginners
Language: English
Things you will learn in this tutorial:
The Translation Manager is available for all Business Central profiles up from BC version 15.0 and resides in its own ribbon menu "TRANSLATE". It can be used to investigate, edit, merge and export translations.
To use the Translation Manager, you need to enable the TranslationFile feature in your app’s configuration.
Since loading and decoding translations takes some time, the Translation Manager is inactive by default. It can be activated by selecting the "TRANSLATE" ribbon menu and clicking "Open".
After opening the Translation Manager the master app’s translations (i.e. the app the current profile is connected to) is loaded first to allow the user to work on translations while Qucamba Reports continues loading translations of all other dependencies in background. During background translation loading, a progress indicator is displayed besides the app selection drop down list as well as in the application’s status bar.
As soon as the loading indicator disappears, other apps can be selected from the drop down list of apps.
Though all apps of the current dependency graph can be viewed in the Translation Manager only translations of the master app can also be edited. The reason for why all translations are loaded into memory is that these translations are used for additional functionality, like
Qucamba Reports usually tries to resolve translation ids to clear symbol names. If for some reason the symbol name is not available, the translation hash value as it is defined in the Xliff files is displayed instead.
During the process of loading translations, Qucamba Reports processes al Xliff files located in each app’s "Translations" folder. On dependencies, this folder is retrieved from the app’s package file.
Depending on your installation, translations of your base app might reside in a separate app instead of the base app itself. Thus, you should include the translation app as a dependency on your app as well.
After loading translations, you have on the left pane
When selecting an object, all attached translations are displayed in the right pane. Each Xliff file is displayed as a separate group that can be expanded and collapsed..
Additionally, each available language code is added to the top filter bar allowing the user to turn display of translation files to view or edit on and off.
When editing translations in the Translation Manager, changes are not committed to Xliff files unless you click the "Save Changes" action.
The following section explains, how to work with the Translation Manager
After activating the TranslationFile feature in your app’s configuration file (app.json), you need to rebuild your app at least once to make the compiler generate the *.g.xlf file in the Translation folder of your app. As soon as the generated Xiff file is updated, load or reload the Translation Manager and choose "New Translation File" from the File menu.
In the Create Translation File window, type the ISO code of a language or select the language from the list and click OK. In this example, we are going to create a new translation file for the language German as it is spoken in Germany.
Tip: Just click on the language selection box and start typing the ISO language code e.g. "de-". From here on, you may select from the supported countries that have German as a language
Qucamba Reports creates an appropriate language file and adds it to your app’s Translation folder. Usually, you start creating a language file for "en-US". Then, continue creating additional language files, one for each language you would like to support e.g., "de-DE".
Of course, you are alternatively still able to create translation files as you did before by hand. In case you prefer creating Xliff files manually, click the "Reload" action located in the File menu of the Qucamba Reports Translation Manager to reflect changes you made to the underlying Xliff files.
When working on your app, you might add additional string literals that will be included in the *.g.xlf file by the compiler automatically. However, the AL Language compiler does not update the language files accordingly.
Qucamba Reports allows you to synchronize the generated Xliff file with each translation file by selecting "Synchronize with Generated Xliff" from the Tools menu.
By performing a synchronization of all language-specific translation files with the generated Xliff
To avoid loss of existing translations of unintentionally orphaned translation units, we recommend creating backups of your translation file before performing any of the Translation Manager actions as well as using source control for Xliff files as well.
When the app that you are currently working on by means of the Qucamba Reports profile is selected in the Translation Manager window, translations can also be edited.
To edit a translation, place the cursor in the Target column and enter the translation.
If the currently focused cell is not yet in edit mode, you can either press <F2> to enter its edit mode or use the mouse to left click on the cell. Use the <Enter> key to accept the entered translation and to proceed with the next translation, i.e. the next line. Again, use the <F2> key, to enter the cell’s edit mode.
Tip: If you want to overwrite the entire content of the focused cell you do not even need to press <F2>. Instead, simply start typing the new content.
After reaching the end of the current object, you may want to poceed with translating the next object of the current or even the next object type. You can navigate through all objects regardless of the object type by pressing the keys <Ctrl> + <Up> to go to the previous object or <Ctrl> + <Down> to go the next object. You can use the mouse as well and click the appropriate action in the "View" ribbon group.
Note, that your changes are not committed to the underlying Xliff files unless you click the Save All Changes action.
When loading an app’s translations, the Translation Manager tries to resolve all numeric translation path values to symbol names allowing you to understand what you are translating. However, you might recognize that some objects and/or symbol names appear orphaned i.e., the Translation Manager displays a numeric value instead of the object’s or symbol’s name. This usually happens after renaming a symbol that had already been translated.
The Translation Manager helps you in getting orphaned entries re-assigned. For example. to re-assign translation units to a renamed field, simply type in the correct field name in the Type column.
To reassign these translation to an object, simply enter the object’s name (without the object type) into the appropriate column. Based on the name you entered, Translation Manager calculates the numeric translation value for the object and updates all translation units of the selected object in all translation files accordingly.
This results in updated translation units as illustrated below.
After clicking the Save All Changes button, changes are written back to the underlying Xliff files.
Note: To re-assign translation units of an entire object, use the "Move Translations" function described below instead.
In some cases, you might want to re-assign all translations of an object to another object or you might want to copy all existing translations of an object to a new object. Typically, this happens after copying a base object, e.g. a report from the base app that you would like to substitute.
To accomplish this, click on "Copy/Move" located in the "Tools" ribbon group.
This opens the "Copy Translations" window as illustrated below.
As you can see in the illustration above, the Target App is already preselected with the current master app, i.e. the current app by means of the currently active profile.
Next, you can select the new target object type. This means, that you can even move or copy translations between deferring object types.
Finally, you select the target object from the list or simply enter the target object’s name.
Usually, you should leave the "Embed in app’s xliff files" checkbox checked to write the changes to the underlying Xliff files. If you uncheck this option, separate Xliff files containing the target object’s name will be created. However, since you can only have one Xliff file per target language in your app, these separated files would have to be merged to the main Xliff files.
In case you need to merge translations for some particular objects from separate files into the app’s Xliff files, there’s also a Merge operation available in the Translation Manager.
First, select the translation units you want to merge to the app’s translation files. Then, click "Merge" in the "Tools" ribbon group. If you do not have multiple translation units selected, Qucamba Reports asks you, if it should merge all translation units of the current object or just the selected one.
This opens the "Merge Translations" window that let’s you pick the target translation file. Usually, this is the one Xliff file of the app that provides the same source language as well as the same target language and that is not the generated Xliff file. Thus, most often there’s just a single choice contained in the "Select Target Translation File" selection box.
After clicking OK, Qucamba Reports merges the selected translation units into the selected Xliff file. However, remember that you usually also want to remove the merged files from your app’s workspace.
When a translation unit of the current master app (i.e. the app you’re working on by means of your current Qucamba Reports profile) is selected, the Go-to-Reference function in the "View" ribbon group allows you to investigate the symbol that the translation unit refers to in Visual Studio Code.
By calling the Go-to-Reference function, your app workspace is opened in Visual Studio Code, the file that contains the related AL object is opened and the cursor is placed near the definition of the symbol.
Tip: The shortcut for this action is the same shortcut as it is in Visual Studio Code (and others): <F12>.
When translating an object, you should usually start by clicking the "Suggest Translations" action. Qucamba Reports then looksup all yet untranslated texts by searching for the same source text within all apps contained in the dependency graph.
In case different translations are found, Qucamba Reports opens the "Pick Translation" window and allows the user to either pick the most appropriate translation and/or enter the desired application manually. The following illustration shows how a field called "Balance" is translated automatically.
In case there is no translation of the same source text contained in any of the apps within the dependency graph, Qucamba Reports starts to search for all existing elements with the same translation path but by ignoring each object’s translation id. This means, that e.g. for translating the "ToolTip" property of a page field called "Blocked" all pages are searched for a field called "Blocked" containing a translated property called "ToolTip". Again, Qucamba Reports opens the "Pick Translation" dialog.
In some cases, the list of possible translations might already contain a perfect translation. However, you can pick the most appropriate translation and edit it int the "Translate to" field before accepting the translation by clicking OK.
All remaining texts that are still empty need to be translated manually by clicking into the cell within the "Target" column and typing in the translation.
After all texts of the current object have been translated, use the "Next Object" action in the View menu to navigate to the next object of the app.
While working with the Translation Manager you might also find some keyboard shortcuts helpful. You can find the assigned keyboard shortcut in the tooltip of each action item.
Following table lists the most important shortcuts of the Translation Manager.
Shortcut Keys |
Description |
Control + Shift + N |
Create a new language file |
Control + Up |
Move to previous object |
Control + Down |
Move to next object |
Control + F1 |
Suggest translations |
F5 |
Reload translations of the current app |
Control + Y |
Synchronize language files with the generated Xliff |
Control + Shift + S |
Save changes to underlying Xliff files |
F12 |
Go to reference |
By using the Qucamba Reports Translation Manager, translating an app becomes an easy task. Various tools help developers getting their daily trouble solved.