Translation and Internationalization

Storyboard makes it simple to translate and internationalize the text content of your application. Dynamic text content is treated the same as any other dynamic content that is rendered to the display. Within the text render extension, the translatable content should be associated with a variable. Any changes that occur to that variable, will trigger a screen re-draw to occur if that variable is being used in the current display.

translation_sample.png

Changes in string content of variables is automatically reflected in the user interface to those locations. This makes the translation activity significantly less labour intensive, as it is only required to identify text strings that are statically declared (ie not bound to a variable) and convert them to be associated with a variable. This variable to text string association forms the base of Storyboard's internationalization support. In order to change the UI to reflect a new language one has only to update the text variables with the appropriate UTF-8 encoded text strings.

There are many different ways to organize the association of language to text strings and then the association of those text strings to user interface variables. Storyboard does not impose any particular method, but generally speaking there are two main techniques that can be considered to accomplish these associations.

One method is to simply keep track of all of the text variables being referenced and for each variable have the translated string stored. This means that if I had a control, for example named mybutton on a layer named mylayer, with a text render extension whose text property was associated with a variable (ie myvariable) that our language database would store the the fully qualified name, mylayer.mybutton.myvariable, along with the value of the string, perhaps "Hello". This technique is simple and works well for small applications where there is not a lot of duplication of text content. The sample Translation demonstrates this technique being used in conjunction with multiple independent comma separated value (CSV) files containing the language database information. Early versions of Storyboard provided a minimal level of automation to help manage these mappings.

A second technique provides a more scalable approach to translated applications and is recommended for sophisticated translation and internationalization applications. Instead of having each UI instance of text declare a local variable all translated text refers to a single translation namespace with unique text strings identified by unique ids. This centralized approach allows unique text strings to be declared once and more easily allows for contextualized translations to be differentiated from one another. The sample TranslationUsingId demonstrates this technique and is supported within Storyboard Designer with automation tools that more easily integrate into workflows supported by text translation professionals.

The TranslationUsingId and Translation samples can be imported into your Storyboard Designer workspace via File > Import > Storyboard Sample.

In some circumstances, most notably with non-latin character sets, it may also be a requirement to dynamically change the fonts being used to map to an alternative font that provides the appropriate glyph support for the characters being rendered. Additionally it may be that a change in translated text requires additional properties to be adjusted, such as font point size or control dimensions, to accommodate the new translation. These can be adjusted as a straightforward change in value of a Storyboard variable. This is exactly the same technique that is used for translated text, the difference of course being that rather than changing text string values, the changes are to the font name or point size or numeric property of a control.

Text Translation View

Storyboard Designer contains a view specifically designed to assist with the process of converting and managing translated text using the common translation namespace technique mentioned above. To open the Text Translation view select Window>Show View> Text Translation.

open_translation_view.png

The Text Translation view shows the text and translation content for projects that have identified themselves as having a translation database. For information on getting started establishing a translation database, refer to the section Translating a Storyboard Application.

For example, looking at the Text Translation view when then TranslationUsingId project is selected will show three areas of content.

translation_text_fields.png

The Text References tab of the Text Translation view shows all of the text references in text render extensions that have been detected in the project. This includes text references that are static (not bound to variables), already associated with variables or associated with variables in the translation namespace. The filters at the bottom of the tab can help reduce the content displayed. This tab is the primary area where you would manage the associations of text in the application with translated values. Right clicking on any of the text entry fields will show a menu of choices:

Translate...

This will perform a lookup of the text string in the translation database. If a value is found then it will be used, otherwise a prompt to create a new text translation entry will occur. This option is only available for non-translated content.

Synchronize Selection

This is used to synchronize the value of the current selection with other language values using the same key. This can only be performed on translated content.

Switch Translation ID

This is used to switch an existing translation to another translation and is used when there are multiple translations with different contexts of use, or to change the translation id to something different entirely. This can only be performed on translated content.

Remove Translation

This will remove a translation id mapping and revert the value to a static string or local variable. This can only be performed on translated content.

translation_attributes_fields.png

The Attributes tab of the Text Translation view shows all of the non-text variables that are being tracked and adjusted in association with language changes. Unlike text references, these variables must be manually added but can include both user defined variables, such as font names or point sizes, and model internal variables, such as a control's position or size. This tab is the primary area where you would manage the associations of variables, but it is possible to add variables to the translation view from the Variables view or Application Model by right clicking on an existing variable and selecting Add Translation Variable. Within the Attributes tab, right clicking on any of the text entry fields will show a menu of choices:

Add Variable To Translation

This will open a variable selection dialog allowing you to manually select variables that have already been defined within the model to be associated with a translation language change.

Update Translated Variable

This is used to synchronize the value maintained in the attribute database for the current language with the current value used in the UI. This is a handy option to use when you want to interactively work through a set of language translations and make UI adjustments interactively and save the current value as shown in Designer.

Synchronize Selection

Similar to the the functionality in the Text References tab, this allows the synchronization of values for a field across multiple languages.

Remove Translation

This will remove the association of a variable as being changed when a language changes. This change is propagated to the translation attribute database.

translation_id_fields.png

The Translation IDs tab of the Text Translation view shows all of the translation identifiers (ids) for the current translation set and the value of those ids for the currently selected language. Translation ids that are currently referenced and in use are shown in bold. At this time Storyboard does not offer support for the editing of these database values from within Designer but suggests that the values be edited in their source database, for example the comma separated value (CSV) file in the translations directory.

Translating a Storyboard Application

Many user interfaces do not start out with translation as a primary concern. Translation and internationalization of a UI is frequently an activity that occurs after the main user experience issues have been addressed and a workflow established in a primary language.

When the Text Translation view is opened and no translation database has been associated with the project, then what you will see will be an empty view prompting for a translation database to be created:

translation_no_database.png

To get started translating your application, create a binding to a translation database where the text strings for the application in the default language can be stored along with any additional attributes that need to be considered as part of the internationalization effort for this application. Create this binding by selecting Create Translation Database which will open a New Translationwizard:

translation_pick_database.png

Currently Storyboard Designer only has the ability to interface with comma separated value (CSV) multi-column language files. In these files, commonly used by translators in programs such as Excel, a single column contains a unique identifier, then subsequent columns contain the different language values for that identifier. For example:

ID,English,French,Spanish
1,Hello,Bonjour,Hola
                    

If a translation database such as this is already available, then you can select it in this dialog, otherwise a new one will be created for you. These files contain the text string information used for different text values in different languages. It is frequently necessary to also change non-text attributes that are Storyboard specific so these attributes are maintained in a separate database file using the same organization but instead of unique identifiers the fully qualified path to the Storyboard variable that should be changed is used instead:

ID,English,French,Spanish
Layer.Control.grd_width,192,310,192
                    

These files are stored in the translations directory of the project with the name(s) that you have provided.

Once a translation database is established, then the first thing to do is to run an analysis of the current user interface and to establish translation mappings for the text content that is present in the default language of the application. This can be done on a field by field basis using the entries in the Text References tab or a full analysis can be performed using the Extra Text option. The Extract Text button in the Text Translation view scans the all text field references and presents a dialog that allows the user to select and approve the automatically identified translations and to create new text translations for fields that do not already have a translation entry. This tool significantly helps bootstrap the translation process.

After this bootstrapping, the translation database file (default translations/translations.csv) can be provided to text translators or linguists to populate with new language entries. For more details on the best practices for editing these files to create UTF-8 encoded text strings, refer to the next section Creating and Editing Translation Content CSV Files. If the translation database file is replaced in the project and the project re-opened, then the new language values will automatically become available for use.

Creating and Editing Translation Content CSV Files

We have explored two tools for editing and creating translation content, Microsoft Office and Open Office Calc. Both tools are able to save UTF-8 encoded (csv) files.

Microsoft Excel (Office 365 Version)

Microsoft Excel is a popular spreadsheet software solution that is widely adopted in many industries.

  1. Using Excel, open a spreadsheet file via File > Open... (note: this can be a spreadsheet created using Excel or Calc)

  2. Save the file as a (csv) file via File > Save As > Browse

  3. Choose 'CSV (Comma delimited) (*.csv)' in 'Save as type:'

  4. At the bottom of the dialog, select tools > Web Options....

    excel_save_as.png
  5. Select the 'Encoding' tab and choose to save this document as: Unicode (UTF-8).

    excel_web_options.png

Open Office Calc

It is free and can be downloaded from www.openoffice.org.

  1. Using Calc, open a spreadsheet file via File > Open... (note: this can be a spreadsheet created using Calc or Excel).

  2. Save the file as a (csv) file via File > Save as... > Text CSV(.csv)

    calc_save_as_csv.png
  3. When saving a (csv) file, Open Office Calc will ask which character encoding you wish to use for the file, be sure to choose Unicode(UTF-8).

    calc_char_encoding_utf8.png
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.