Tips for translation data sources (i18n)

If you want your configurator to be available in multiple languages, we recommend to store translations in a data source.

The text content that must be translated is often interwoven with regular product data. If you are free to choose the structure of your data sources, you can take our below recommendations as a starting point.
In general, you should keep these points in mind when designing a data source:

1. Ease of data maintenance. How much effort is it to add new languages to the data source?
2. Ease of configurator maintenance. What must be done to the configurator to add new texts or languages?
3. Performance. Sending too much data at once can degrade the user experience.

The below recommendations try to strike a balance between these general points.
We use Microsoft Excel in our examples, but the underlying concepts can be transferred to similar file types.

Static Text / UI Controls

This is a recommendation for the translation of static text content, as found e.g. in the user controls of your configuraor (labels, button text, tooltips etc.)

• Unless you have a huge amount of texts, we recommend to keep all translations in one file / worksheet.
  This makes it simpler to e.g. hand that file over to professional translators, who then have all translations available as reference and for additional context.
• Create a column for each text that must be translated and a row for each language
  • This is the simplest way to access each text in the configurator.
  • All texts of a language will be contained in a single record, which can be connected to UI controls with Signals and Slots
  • Maintaining the data in the worksheet will be a bit cumbersome for longer texts, but the ease of access in the configurator offsets that downside. You can try to split the data among several worksheets to improve ease of maintenance.
• The first column, the key column, should identify the language.
• Create a single data source from this file (we'll call ours StaticTextDataSource in this example)
• Now you can load just the texts of the desired language in a table component:

  from StaticTextDataSource
  select all
  filter .Language = CurrentLanguage
  

• The table will contain just one record, which you can obtain with the GetFirst() method.
• Finally, connect the columns of the record with Signals and Slots to your UI controls.

Product Data

This is a recommendation for the translation of a variable number of items, which is usually the case for product data. (e.g. categories, products, parts, …) The Static Text recommendation does not work here, as the number of columns would be variable, and you can't use Signals and Slots on columns that may or may not exist.

We assume you have a worksheet that contains arbitrary product data, where each row is a "product" and each a column an attribute of that product. Some columns contain text that must be translated.
An Excel file will work best here, because we'll create multiple data sources and want to be able to update them all at once.

Here is what we suggest:

• For each text column that must be translated, create one column per language.
  • example: if you have a Name column, create a NameEN, NameDE, NameFR etc.
• Upload your Excel document as file asset. Create the following data sources based on that file asset.
• Create a data source for the first language, e.g. ProductEN
  • open the import configuration of the data source and remove all columns that belong to different languages
  • rename all translation columns (of your data source) to have a neutral name, e.g. rename NameEN to Name
• Copy the data source for the next language, e.g. ProductDE
  • change each translation column to point to a German column instead, e.g. Name should target the NameDE column
  • repeat this step for each language. In the end you should have one data source per language.
• In your configurator, create a value component ProductData that points to the data source of the current language:

  // if you have many languages, you may want to use a record component instead
  if CurrentLanguage = "de" then ProductDE else ProductEN end
  

• Now you can create table components that target the ProductData component and thus get your product data in the current language:

  from ProductData
  select all
  filter … // you can use any filter you want
  

• When the product data changes, you can update all data sources at once by re-uploading your Excel document in the file asset.
  • you can also add additional worksheets for other product data to the same Excel document. That way you only have to upload one file to update all your data sources at once.
• Adding a new language requires:
  • adding new columns in the worksheet (e.g. NameXY, DescriptionXY)
  • creating a new ProductXY data source for that language
  • selecting the new data source in the ProductData value component when the language is "XY"

This pattern makes it easy to import updated data and to process it in the configurator, as all translated texts are stored alongside the general product data. However, maintaining the data in the Excel file can become a challenge if you have to support many languages.