pre-released

Localizing Application

 

Kitchen application

This section describes how to translate the Kitchen application, i.e. layers, titles, buttons, etc.
For the translation of the catalog content (products parameters, descriptions, etc.), refer to the content localization documentation 🔗.

The kitchen application supports 2 levels for its translations:

  • Application level: translations for your whole legal entity at the application level for a specific locale. This is the most nominal use case, which is highly recommended.
  • Application distribution level: translations for a specific application distribution of your legal entity for a specific locale. It can be used for very specific use cases to overload translations for a given locale at an application distribution level.

Reference keys API

In order to get all the available translation keys in the application, you have to access this url:

kitchenbaseurl/Kitchen/assets/translation-master.json

kitchenbaseurl depends on targeted environment. Caution that on preprod environment you will have an htaccess to protect access to this resource (in order to avoid information leaks on features before released in production).

Application translation structure

File structure

To translate the Kitchen application, you have to provide a valid JSON object with the same structure than the translation-master file:

{
    "translations": {
        // list of all translation keys here
        // supported translation keys can be found in the translation-master file
    }
}

We recommend to define all of the translation keys of the master file in your translation object. However, it is not mandatory and the planner will use its default translations for non-provided keys (see below).

Dynamic parameters

Some translation keys support dynamic variables, injected by the planner. To retrieve the list of such keys, use the translation-master file and list translation contents that contain these characters: {{someVariableName}}.

Example:

{
    "start_date_end_date_title" : "From {{startDate}} to {{endDate}} or while stock last"
}

These variables can be omitted if you want to have a fixed translation instead. If you want to use the dynamic content, you must use the exact same variable name as written in translation-master.

Note that all the supported dynamic variables are listed in the translation-master file. Adding a non-supported {{variable}} in translation content will have no effect but to display {{variable}} as is.

The content injected by the planner in place of these variables can be of the following types:

  • numbers: independent of the language. If you use an imperial unit system, refer to the section below about escaping special characters
  • dates: we use the function toLocaleDateString 🔗 to display dates, so that dates are always displayed in the current language format
  • strings: the only string we inject are from the range (translated by the range maintainer) or entered by the user directly

Escaping special characters

When the planner injects a variable content, special characters like ", ?, <, > or ' are "escaped", i.e. replaced by a charcode like &quot;. This is done for security reasons, to avoid XSS injection attacks.

If you are using an imperial unit system however, you will encounter an issue for displaying the " symbol for distances. In such cases, you can use one of the following syntax to disable the character escaping: {{{variable}}} or {{&variable}}.

Example

{
    "cut_cut_distance_rule_error_message": "Minimum distance between two cuts is {{{x}}}." // {{&x}} is strictly equivalent
}

❗ It is highly recommended to limit as much as possible disabling the character escaping. Use it only where necessary, for distances that are exclusively computed by the planner..

Imperial unit system computation

To handle properly Imperial unit system, we decided to have 4 decimals precision when we converts mm to inches. With that, the user will have necessarily some fractions (i.e. 1/16) to respect this precision. This precision is sufficient to properly design a kitchen project and it covers the majority of the use cases.

Upload and check translations

The API to call depends on the translation level you chose.

  • For the Application level:

API: PUT applications/2/translations/my-locale
Ex: PUT applications/2/translations/en-GB

  • for the Application distribution level:

API: PUT applicationdistributions/appDistID/translations/my-locale
Ex: PUT applicationdistributions/appDistID/translations/en-GB

After you have pushed your translations, you can verify they are correctly updated with the following APIs:

  • for the Application level:

API: GET applications/2/translations/my-locale
Ex: GET applications/2/translations/en-GB

  • for the Application distribution level:

API: GET applicationdistributions/appDistID/translations/my-locale
Ex: GET applicationdistributions/appDistID/translations/en-GB

Kitchen app translation workflow

Below is detailed how the Kitchen planner uses the translation content during a typical execution.

[At app launch] Retrieve the locale and the fallback

First it retrieves two keys from the app-distribution parameters:

  • locales : the list of accepted locales in this app-distribution (must be a list of JSON objects) and each element can have a fallback key.

  • locale: the identifier of the locale to use. It must be contained in the list of locales above.
    If locale is not provided, "en-GB" is used instead as default.

If ln={locale} is provided in the iframe URL, this locale will replace the locale from the app-distribution parameters. It must also be contained in the list of locales from the app-distribution parameters.

This step determines the locale to use for the user session, as well as a potential locale fallback.

[At app launch] Download the translation files

Then, the planner downloads 3 files per locale: the API file, the application file and the app-distribution file (see translation levels).

Then, it merges these 3 files into 1 "translation pack". The merge order is as follow (decreasing priority): app-distribution, application, API. It means that if a key is both in application and app-distribution levels, the app-distribution will have the priority.

A translation pack is created for the following locales:

  • The current locale from the previous step
  • The fallback locale if it exists. If not, "en"

[At app runtime] Translation of a key inside the planner

When hitting a translation key, the planner tries several locations until it is found. The order is very important and is as follow:

  1. The translation pack of the current locale
  2. The translation pack of the fallback locale
  3. Default translation pack (see below)

Default translation pack

3DVIA provides default translations of the planner that are used in case a key is missing from the client translation packs.

The default translation pack used depends on the locale as shown in the table below.

LocaleDefault translation pack
ar-EGDefault Arabic translations
de-DEDefault German translations
es-ESDefault Spanish translations
fr-FRDefault French translations
pt-PTDefault Portuguese translations
Any otherThe contents of translation-master.json (US English)

The default translation pack contains all of the planner supported keys.

Navigation Tree

Catalog navigation specific case

In the application distribution parameters, you can map translation keys to the different levels of your catalog navigation.

See example below:

"catalogEntries": {
    "detailedDesign": [
        {
            "picto": "furniture",
            "categories": [
                {
                    "categories": [
                        {
                            "freeTags": [],
                            "closedTags": [22],
                            "translationKey": "baseCabinets"
                        },
                        {
                            "freeTags": [],
                            "closedTags": [144],
                            "translationKey": "highCabinets"
                        },
                        {
                            "freeTags": [],
                            "closedTags": [216],
                            "translationKey": "wallCabinets"
                        },
                        {
                            "freeTags": [],
                            "closedTags": [271],
                            "translationKey": "cornerCabinets"
                        },
                        {
                            "freeTags": [],
                            "closedTags": [554, 560],
                            "translationKey": "fillerStripAngle"
                        }
                    ],
                    "translationKey": "cabinets"
                }
            ],
            "translationKey": "cabinets"
        }, //..
    ], //..
}

In the application translation file, it will end up in a structure like this:

"navigation_catalog": {
    "detailed_design_state": {
        baseCabinets : ..,
        highCabinets : ...,
    }
}
← PreviousNext →