Translation Tool Tutorial

Translations are typically implemented towards the end of a project. In this scenario, you have been developing the app and filling in default text in a single language to be translated at a future time. Now that time has arrived and the translator is standing by to fill in alternative values for whatever languages will be supported. The following tutorial will walk you through the recommended workflow for exporting a translation database file for the translator to fill in and re-importing it into the project to view the translations in the app.

1 - Create a Translation Database

Open your app and open the text translation view. This can be accomplished by clicking Window > Show View > Text Translation.

You will see there is a dropdown to select a language, as well as an “Extract Text” button. These will be explained shortly, but for now they are unavailable because there is currently no translation database in the project. To add a translation database, click the “Create Translation Database” button.

In the popup, there are options to create a new translation database or import an existing one. We will create a new one for this tutorial.

Click Next

The attributes file will be explained in further detail later on. It is used for variables that will affect the appearance of the app depending on the current language. For example, the width of a button when a translation is longer in a specific language.

For now, just name the attributes file and click Finish.

Enter the name of your initial language and click OK.

2 - Getting to Know the Interface

The first tab of the translation view will show a list of all of the controls with text render extensions that can be translated, as well as the current text being shown and an indication of whether the text is currently clipped or not.

The filter box on the bottom allows you to search by control name. The “Static” and “Variable” checkboxes at the bottom can be used to filter by text that is currently linked to a variable or not, and the “Translated” checkbox can be used to filter out text that is already linked to a translation id.

The second tab of the translation view shows attribute variables, which, as explained previously, can be used to set certain visual aspects of the app depending on the language. For example, if a text area in the previous tab was showing that the text is clipped in the current language, you may want to create an attribute variable for the width of the text area to increase it so the text will fit. We will show the attribute variables in action later on.

The final tab of the translation view will show all existing translation ids, the text for that ID in the current language, and an optional description to indicate the variable’s use within the app. Currently we have no translation IDs in our database, so let’s translate some text.

3 - Extracting Text To Be Translated

In order to begin adding text to your database for translation, return to the Text References tab of the translation view and click “Extract Text” next to the language dropdown.

This view allows you to see all text fields in the project and tie translation variables to them individually. Click on one of the text fields in the “Model Text References” box. If an ID with a similar value to the one in the selected text reference exists, the ID will appear in the “Suggested Translation Variables” box and you can select it if you would like to use it. If no ID exists, click Create New ID. Select the new ID from the “Suggested Translation Variables” box to link this text reference to the ID. Do this for each text field you would like to translate and then click OK.

If your text is dynamic (maybe you have “Good Morning” text that changes to “Good Afternoon” or “Good Evening”), you can add multiple translation IDs for a field and switch between them at runtime depending on context. Use the checkbox in the “Suggested Translation Variable” box to select the default id to show.

4 - Adding Another Language

Now that you have linked your text fields to translation IDs, you will have a database of initial values for your primary language ready to go. Before you send this database to the translator, you will have to add your secondary languages so that they can enter the proper values.

Click the Language dropdown at the top of the translation view, where you see the name of your initial language. Click the option to “Create New Language”. Enter the name of your second language.

If you would like to copy the initial values from your primary language, check the “copy values from” checkbox. If you would like to leave the values as empty strings until the translator can fill them, leave this unchecked.

Click OK to create your new language. Do this for all languages you would like to add to the database.

5 - Fill the Translation Database

This is the point where you give the CSV file to whomever will be filling in the translations for the secondary languages. The file can be found in the translations folder in the project directory. The translator can open it into Excel or another editor and fill in the values in the proper columns.

When they are finished, return the file to the translations directory and re-open the project in Storyboard.

6 - Viewing the Changes

Now that you have imported the updated translation database, you can easily preview each language in Designer by using the language dropdown in the translations view:

7 - Changing the Language at Runtime

Storyboard currently does not include a built-in action to change the language at runtime, however this can be achieved using the VariableLoader script (accompanied by the csv script) in the TranslationUsingID sample.

To use it, initialize the VariableLoader at application init (change the translation and attributes path to match whatever you named the files):

VarLoader = require("VariableLoader")

--- @param gre#context mapargs
function CBInit(mapargs) 
  -- English is the application's base design language so we don't have
  -- to perform any loading initially. If we start with a different language
  -- then we should use loadOnInit to set those initial values.
  local attrs = {}
  attrs.language = "english"
  --attrs.loadOnInit = true
  attrs.textDB = gre.APP_ROOT .. "/translations/translations.csv"
  attrs.attributeDB = gre.APP_ROOT .. "/translations/attributes.csv"

  Translation = VarLoader.CreateLoader(attrs)
end

And then you can simply call setLanguage and pass in the desired language when you would like to switch (make sure the language name you are passing in is identical to the name you gave it when you created it. This includes upper/lowercase):

--- @param gre#context mapargs
function CBLoadLanguage(mapargs)
  Translation:setLanguage(mapargs.language)
end

8 - Using Attributes to Adjust Your App Based on Language

There may be situations where your app will have to look a little different depending on the current language. For instance, some strings may be longer in different languages, and the formatting of the text field will have to be adjusted for it to fit. Storyboard’s translation tool provides attributes for this exact purpose. In this example, we will imagine that the English language uses a different font than the French language.

First, tie the font for all text fields to a variable. In our case, all the fonts could be tied to the same variable because they will share the same font in each language.

Now click on the attributes tab in the translations view. Right click in the empty variable list and click “Add Variable to Translation”. Select your variable and click finish.

Take the attributes csv file into an editor and fill in your desired values for each language. Re-import the csv into Storyboard and switch between languages in the translations view. You should see the fonts change as you move between languages. Try this out for any other variables you may want to change depending on language.