Localizing Application and Content
Applications
In order to translate the application (except product commercial information and parameters, see sections below), you will have to use several APIs.
Reference keys API
In order to get all the translation keys available in the application, you have to access this url:
homebaseurl/Planner/assets/json/translation-master.json
homebaseurl 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).
for exemple, on preprod main environment: https://preprod-home.enterprise-dev.by.me/Planner/assets/json/translation-master.json
Get default translations
If you want to get default translations for home retailer application, you can call the GET method:
API: GET applications/1/translations/my-locale
Ex: GET applications/1/translations/en-GB
Note that if you have already pushed translation for this locale at the application level (see explanation on translation levels in next section), you will get your overloaded translations and not the default one.
Translation levels
There are two different levels for translations.
▪ Application level: you can define 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.
API: PUT applications/1/translations/my-locale
You have to be authenticated with your API key / secret key.
▪ Application distribution level: you can define 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.
API: PUT applicationdistributions/appDistID/translations/my-locale
You have to be authenticated with your API key / secret key. This level will overload the keys provided and use the application level for keys that are not provided.
Home Retailer Application translation workflow
Below is detailed how the Home Retailer Application uses the translation content during a typical execution.
▪ [At app launch] Retrieve the locale and the fallback
In the app-distrib parameters, it will seek for two keys:
locales : the list of accepted locales in this app-distrib (must be a list of JS objects) and each element can have a "fallback" key.
locale: the identifier of the locale to use. This one must be contained in the list of locales above.
If locale is not provided, "en-GB" will be used instead.
If ln={locale} is provided in the iframe URL, this locale will replace the locale from the app-distrib parameters. It must also be contained in the list of locales from the app-distrib parameters.
▪ [At app launch] Download of the translation files
Then, the planner will download 3 files per locale: the API file, the application file and the app-distrib file (cf. translation levels). Then, it will merge these 3 files into 1 "translation pack". The merge order is as follow (decreasing priority): app-distrib, application, API. It means that if a key is both in application and app-distrib levels, the app-distrib will have the priority.
A translation pack is created for the following locales:
– The final 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:
- The translation pack of the current locale
- The translation pack of the fallback locale
- 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.
| Locale | Default translation pack |
|---|---|
| fr-FR | Default French translations |
| pt-PT | Default Portuguese translations |
| Any other | The 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": {
"building":
[{
"picto": "exterior_doors",
"categories": [
{
"freeTags": [],
"closedTags": [
240
],
"translationKey": "front_doors"
},
{
"categories": [
{
"freeTags": [],
"closedTags": [
389
],
"translationKey": "sliding_patio_door"
},
{
"freeTags": [],
"closedTags": [
388
],
"translationKey": "swinging_patio_door"
}
],
"translationKey": "patio_doors"
},
{
"freeTags": [],
"closedTags": [
249
],
"translationKey": "garage_doors"
}
],
"translationKey": "exterior_doors"
}, //..
], //..
}
In the application translation file, it will end up in a structure like this:
"navigation_catalog": {
"building": {
exterior_doors : {
front_doors: ..,
}
Content
This section is about adding translations / localization of product information in home retailer planner. It can be done either by API or with the help of 3dcloudbyme.
Adding translations using API
HomeByMe for Home Retailer Application has divided products into three categories as the following:
▪ 1: Opening Products (Build)
▪ 2: Furnishing Products (Furnish)
▪ 3: Decorating Products (Decorate)
According to different category, different properties of product can be translated.
1: Opening Products
Following properties of the Openings Products can be translated:
▪ 1: Name, short description and commercial description
▪ 2: Parameters (width, depth, height, circumference, etc.)
All translations in Openings which are marked in red below are taken from application master translation file. That is because all of them have only width and height with some basic setting about opening and wall side. Only name of the product is translated in JSON file, same like - Name, short description and commercial description point.
Name, Short Description and Commercial Description
Translations are added in "commercialInfos" array for each language ID in "definition" object of [POST] Products API.
Example below:
"definition": {
"name": "Chair Waterfly",
"productSheetUrl": "",
"commercialDescription": "",
"shortDescription": "",
"languageCode": "en-GB",
"price": {
"value": null,
"from": null,
"pricingMethod": {}
},
"reference": "chairWaterfly",
"manufacturer": null,
"brandID": "1",
"brandName": "Bryo",
"geometryExtension": [],
"id": "9621",
"external_id": "9621",
"typeID": 138,
"startDate": null,
"endDate": null,
"parentID": null,
"prices": null,
"commercialInfos": [
{
"name" : "Chair Waterfly",
"commercialDescription" : "chair comfortable blue",
"productSheetUrl" : "http://xxx",
"shortDescription": "chair comfortable",
"languageID" : 2
},
{
"name" : "Chaise Waterfly",
"commercialDescription" : "chaise confortable bleu",
"productSheetUrl" : "http://xxx",
"shortDescription": "chaise confortable",
"languageID" : 1
}
]
},
Parameters (width, depth, height, circumference, etc.)
2: Furnishing Products
Following properties of the Furnishing Products can be translated:
▪ 1: Name, short description and commercial description
▪ 2: Aggregation parameters (type, material, etc.)
Name, Short Description and Commercial Description
Setting translation for Name, short description and commercial description is same as opening products.
Aggregation Parameters (type, material, etc.)
Localized in parameters definition of each product JSON. Syntax is the same as in all parameter typeID:2.
"parameters": {
"definition": {
"filterWidth": {
"typeID": 2,
"values": [
60,
80,
1000
],
"editable": null,
"translation": {
"name": "filterWidthKey",
"values": {
"1": "60Key",
"2": "80Key",
"3": "100Key"
}
},
"defaultValue": 60
}
}
},
Where (example):
{
"key": " filterWidthKey ",
"languageID": "2",
"label": "Width"
}
{
"key": "60Key",
"languageID": "2",
"label": "60cm"
},
{
"key": "80Key",
"languageID": "2",
"label": "80cm"
},
{
"key": "100Key",
"languageID": "2",
"label": "100cm"
},
3: Decorating Products
Following properties of the Decorating Products can be translated:
▪ 1: Aggregation parameters
Aggregation Parameters
It is localized as every other parameter in parameters definition of the product. It can be used to filter by color palette.
For example, filtering color palette JSON:
"parameters": {
"definition": {
"filterParameterColorPalette": {
"typeID": 4,
"values": [
"blue",
"green",
"red"
],
"editable": null,
"translation": {
"name": "filterParameterColorPaletteKey",
"values": {
"blue": "blueKey",
"green": "greenKey",
"red": "redKey"
}
},
"defaultValue": "blue"
}
}
},
Adding translations using 3DCLOUDBYME
It is possible to put translations straight through 3DCLOUDBYME but it is limited to number of languages which has been implemented into the application.
Without translation keys
Name and short and commercial descriptions translations can be handled here:
Each parameter can be named manually. In this case four different languages are linked to this application. All examples below are just to show the structure of JSON for each data type.
▪ typeID:1 - real (Discrete length)
3Dcloudbyme language option:
"width": {
"typeID": 1,
"values": [600, 800, 1000],
"editable": "RW",
"translation": {
"name": {
"1": "Longueur",
"2": "Width",
"3": "Anchura",
"4": "Breite"
},
"values": {
"2": {
"600": "600cm",
"800": "800cm",
"1000": "1000cm"
}
}
},
"defaultValue": 600
},
▪ typeID:1 - real (Continuous length)
3DCloudbyme language option:
"legHeight": {
"max": null,
"min": 0,
"step": 1,
"typeID": 1,
"editable": null,
"translation": {
"name": {
"1": "Hauteur de la jambe",
"2": "Leg Height",
"3": "Altura de la pierna",
"4": "Beinhöhe"
}
},
"defaultValue": 80
},
▪ typeID:2 - integer
3DCloudbyme language option:
"handleOrientation": {
"typeID": 2,
"values": [0, 1],
"editable": "RW",
"translation": {
"name": {
"1": "Orientation de la poignée",
"2": "Handle orientation",
"3": "Orientación del mango",
"4": "Grifforientierung"
},
"values": {
"1": {
"0": "Vertical",
"1": "Horizontal"
},
"2": {
"0": "Vertical",
"1": "Horizontal"
},
"3": {
"0": "Verticale",
"1": "Horizontal"
},
"4": {
"0": "Vertikale",
"1": "Horizontal"
}
}
},
"defaultValue": 0
},
▪ typeID:3 - boolean
3DCloudbyme language option:
"decoStripOption": {
"typeID": 3,
"editable": "RW",
"translation": {
"name": {
"1": "Option bande déco",
"2": "Deco Strip Option",
"3": "Opción Deco Strip",
"4": "Deco Strip Option"
}
},
"defaultValue": 0
},
▪ typeID:7 - product
3DCloudbyme language option:
"handle": {
"ids": ["13776", "14087", "15476", null],
"tags": [],
"typeID": 7,
"editable": "RW",
"nullable": true,
"translation": {
"name": {
"1": "Poignée",
"2": "Handle",
"3": "Manejar",
"4": "Griff"
}
},
"defaultValue": "13776",
"allowAnyValue": false
},
With translation keys
It is possible to add translation with the help of translation key in 3DCLOUDBYME. To do so, toggle the button "Use translation key" to ON. Insert the translation key for parameter and its values. Translation keys should be available with appropriate values in the application master translation file. If the translation key does not have any assigned value, translation key with prefix "key_" is displayed in the application for that language.
3DCloudbyme translation key:
Structure of JSON for each data type parameter is similar to translations made by 3DCloudbyme without translation keys (refer to the section above "Without translation keys").
"handleOrientation": {
"typeID": 2,
"values": [0, 1],
"editable": "RW",
"translation": {
"name": {
"2": "key_handleOrientation"
},
"values": {
"2": {
"0": "key_vertical",
"1": "key_horizontal"
}
}
},s
"defaultValue": 0
},
Parameters Options
Parameters appear in the product properties panel of the application (see the picture below). In order to translate them, you can specify directly the translations for each language directly in the parameter display name. The best alternative is to create a translation key in the database and to link it to your parameter.
To create a translation key into the database, you can use these web services:
- [GET]translations/key
- [POST]translations
- [PUT]translations/key
- [DELETE]translations/key
See how to use them in the web services documentation.
The translation key and your parameter ID should be the same.
Then you can use this translation key in the parameter when calling POST or PUT products web service.
For more in depth information, see reference documentation on web services API for POST and PUT products routes.
Searchable Parameters Translation
Searchable parameters are the parameters which are present in the catalog filters.
These parameters will be used as aggregation parameters defined in application distribution parameters to filter the catalog.
Here are the steps to translate the searchable parameters:
Step 1 - Check application distribution parameter configuration
Make sure you have defined aggregationParameters property in application distribution parameters.
See ➡️ AggregationParameters 🔗 The value of "aggregationParameters" is a list of string. Each string represents the translation key of the searchable parameter.
Step 2 - Define the parameter through API
Once setting the translation key of the parameter, you need to define the parameter by using the API /parameters.
See ➡️ Parameters Webservice documentation:
▪ POST parameters 🔗
▪ PUT parameters/key 🔗
For example, here we use POST /parameters to define a searchable parameter called "commercialHeight".
POST /parameters
{
"key": "commercialHeight",
"searchType": "integer"
}
Note:
- The "searchType" is to indicate which type you want the parameter to be searched or be aggregated. It can be "string", "integer" or "float".
- The "key" is the key of parameter, and it is also considered as the translation key of searchable parameters. It needs to be the same string as you defined in "aggregationParameters" in application distribution parameter.
Step 3 - Configure the searchable parameters on products
Once defined the value of searchable parameters, you need to flag the products that can be filtered by the searchable parameters.
To do that, you need to add the parameters on products with the right type. For example, if we defined a searchable parameter "commercialHeight" with type "integer", in order to be filtered by this parameter, a table must have a parameter called "commercialHeight" and its type must be "integer".
Step 4 - Add translations for searchable parameters
Once the previous steps are done, the catalog filters will appear when browsing catalog that contains product with searchable parameters. But it is not translated. In order to make it translated, you need to add translations for the searchable parameters through API /translations. Make sure the translation key is what you have defined as the key of searchable parameter. Take example before, you need to add translations for the translation key "commercialHeight".
POST /translations
{
"languageID": 2,
"key": "commercialHeight",
"label": "Height"
}
See ➡️ Translations Webservice documentation:
▪ POST translations 🔗
▪ PUT translations/key 🔗