Skip to main content

Localize Data Source Values

When translations are enabled on your board, Tonkean localizes the text that makers define in the solution, specifically interfaces, preferences, and other user-facing areas like field labels and button text. Some interface widgets can also localize values that come from a data source—for example, catalog item names, category descriptions, and similar values in the Search widget.

To automatically localize data source values, the data source must provide the relevant translations as one additional field (in a specific format) for each field-and-locale combination. When a translated field exists for the viewer's locale and translations are enabled, Tonkean displays the translated value automatically. If no translation exists for that locale, Tonkean defaults to the original value.

This capability is distinct from translating the maker-created experience. For more information on that process, see Translations.

Field Naming Format

To provide a translation, add a field to the data source using the following format:

tnkTranslation{@SEPARATOR@}<original field name>{@SEPARATOR@}<locale>

  • <original field name> - The name of the existing field you want to localize. This field must exist in the data source.

  • <locale> - A standard locale code that matches the locales configured for your board (for example, fr-FR, de-DE, or es-ES)

Add a separate field for each locale you want to support. Enter {@SEPARATOR@} exactly as shown; this is the separator token Tonkean uses to identify translation fields.

Data Source Localization Example

To localize a PRODUCT_CATEGORY_L3_DESC field into French and German, the data source would include the original field plus one translation field per locale:

PRODUCT_CATEGORY_L3_DESC

tnkTranslation{@SEPARATOR@}PRODUCT_CATEGORY_L3_DESC{@SEPARATOR@}fr-FR

tnkTranslation{@SEPARATOR@}PRODUCT_CATEGORY_L3_DESC{@SEPARATOR@}de-DE

Watches

Montres

Uhren

Sunglasses

Lunettes de soleil

Sonnenbrille

With this data in place, a viewer whose locale is fr-FR sees Montres wherever a supported widget displays this field, while a viewer with no matching locale sees the original value, Watches.

Data Source Localization Requirements

For a translated value to display, all of the following must be true:

  • The original field exists in the data source.

  • A separate translation field exists for each locale you want to support, named using the format above.

  • The locale code matches a standard locale code and the locales configured for your board.

  • Translations are enabled on the board. See Translations.

  • The viewer's locale is set on their profile. See Notification Settings.

Data Source Localization Supported Areas

Localization of data source values is supported in the following areas:

  • Search widget result fields - Card title, card description, image URL, card tag text, secondary property, and dynamic properties. For configuration information, see Search Input widget.

  • Search widget search - When the localized field is included as a searchable (additional) search field, users can search by the localized value.

  • Matched entity and external data source dropdown values - Including searching by localized values.

  • Interface expressions that reference external data source fields - When those fields are evaluated through Tonkean expression evaluation.

Populate Translation Values in Your Data Source

Getting the translation fields into the data source is the responsibility of the customer or the implementation team, working with the source of the data. Tonkean displays the translations if they are present; it does not create them for you (except where a data source connector builds them for you).

Common approaches include the following:

  • Provide the translations at the source. If the source system already stores translations, format them as translation fields so Tonkean can collect them.

  • Upload a formatted dataset. Prepare a file (for example, a CSV) that includes the original values and their translation fields in the required format, then load it into a data source such as an Internal DB.

  • Transform the data during collection. Apply a transformation on the connected data source that outputs the translation fields in the required format. For example, the Coupa data source can be configured to build these fields automatically when translations exist in Coupa.

In this section: