Localizing Content
Products information
This section is about adding translations / localization of product information in Bathroom planner. It can be done either by API or with the help of 3dcloudbyme.
❗️ Note that there is a fixed width for those items of 75px: this is the only way to ensure the label won’t shift from the center of the icon. We have a limitation of 2 lines of text. This means approximately 30 characters (on a 20 characters “w” base). Note also that the font used will impact this number. We can’t enforce this rule, but the translations should follow these guidelines.
The Bathroom planner has 3 steps:
▪ Step 1: Floorplan
▪ Step 3: Design your bathroom
▪ Step 4: Finalize
Note: There is no step 2 in the Bathroom application.
Products can be added in a project in Step 1 & Step 3 of the Bathroom planner.
Products in Step1 (Floorplan)
Products in Step 1 are categorized in following three groups: Room objects, Openings and Coverings.
Translations can be added for following product information:
▪ Name, short description and commercial description
▪ Parameters (width, depth, height, circumference, etc.)
▪ Aggregation parameters (Color palette)
Name, short description and commercial description
For products in step 1 and step 3, the syntax and the way to add the description translations is the same. 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.)
Room Objects
All parameters of products in room objects (width, length, depth, circumference etc. are highlighted by green color in fig.1 ) are translated directly in the product's JSON while creating or updating product using product API. Areas marked in red in fig.1 are translated from application master translation file. For more details, refer to the section Localizing Application above.
For translation of above mentioned parameters: First, it is necessary to put the translation keys for each languageID into the database using [POST] Translation Key API (Read Note for good practices).
JSON for each language ID:
{
"key": " depthKey ",
"languageID": "2",
"label": "Depth"
}
{
"key": " widthKey ",
"languageID": "2",
"label": "Width"
}
{
"key": " heightKey ",
"languageID": "2",
"label": "Height"
}
Now add translation keys into the product JSON:
"parameters": {
"definition": {
"depth": {
"max": null,
"min": null,
"step": 1,
"typeID": 1,
"editable": "RW",
"translation": {
"name": "depthKey"
},
"defaultValue": 900
},
"width": {
"max": null,
"min": null,
"step": 1,
"typeID": 1,
"editable": "RW",
"translation": {
"name": "widthKey"
},
"defaultValue": 1200
},
"height": {
"max": null,
"min": null,
"step": 1,
"typeID": 1,
"editable": "RW",
"translation": {
"name": "heightKey"
},
"defaultValue": 450
}
}
},
Product parameters shall now be translated according to the translation keys added.
Openings
Unlike the Room Objects, 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.
Aggregation parameters (Color palette)
This feature is required only for Coverings (paints, wallpapers, floor tiles, etc.). 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"
}
}
},
Products in Step3 (Design your Bathroom)
Translations can be added for following product information:
▪ Name, short description and commercial description
▪ Parameters (any range parameter which is visible/editable in the edit properties panel)
▪ Aggregation parameters (type, material, etc.)
Name, short description and commercial description
Setting translation for Name, short description and commercial description is same as for products from Step 1.
Parameters (any range parameter which is visible/editable in the edit properties panel)
The easiest and the quickest way to put parameters translations is, using translation keys through [POST] Translation Key API (Read Note for good practices of API). To do so, translations need to be added in parameters of each product, with a certain consistency.
Including linear parameters and their names that are cabinet subset. They correspond to the translation of the related driving parameters. For example, for worktop it is the translation of worktopOption parameter.
Examples for each data type parameter below:
▪ typeID: 1 - real (length)
"sinkYOffset": {
"max": null,
"min": 0,
"step": 1,
"typeID": 1,
"editable": "RW",
"translation": {
"name": "OffsetValueKey"
}
},
"defaultValue": 0
},
▪ typeID:2 - integer
Array with possible values can only be filled with predefined values to specific parameter.
An object in translation values, should include values appropriate for values from the array with desired translation keys.
"handleOrientation": {
"typeID": 2,
"values": [0, 1],
"editable": "RW",
"translation": {
"name": "handleOrientationKey",
"values": {
"0": "handleOrientationLeftKey",
"1":"handleOrientationRightKey"
}
},
"defaultValue": 0
},
OR
"sideSinkXOffset": {
"typeID": 2,
"values": [-1,1],
"editable": "RW",
"translation": {
"name": "sideSinkXOffsetKey",
"values": {
"1": " sideSinkXOffsetKey_rightKey",
"-1": " sideSinkXOffsetKey_leftKey"
}
},
"defaultValue": -1
},
▪ typeID:3 - Boolean
"leftCorniceBack": {
"typeID": 3,
"editable": "RW",
"translation": {
"name": "leftCorniceBackKey"
}
},
"defaultValue": 1
},
▪ typeID:4 - string
"commercialDimensions": {
"typeID": 4,
"values": ["W600 x D370 x H800"],
"editable": null,
"translation": {
"name": : "commercialDimensionsKey"
},
"defaultValue": "W600 x D370 x H800"
},
▪ typeID:7 - product
"drawerLight": {
"ids": ["15468", null],
"tags": [],
"typeID": 7,
"editable": "RW",
"nullable": true,
"translation": {
"name": "drawerLightKey"
}
},
"defaultValue": "154648"
},
To translate keys, it is necessary to put all translation keys through [POST] Translation Key / [PUT] Translation Key API to proper languageID.
Good practice is to prefix or suffix the phrase translation key by "Key" phrase.
For more information, refer to List of available languages and IDs documentation 🔗
Webservice documentation:
▪ PUT translation key 🔗
▪ POST translation key 🔗
With this kind of body:
{
"key": " handleOrientationLeftKey ",
"languageID": "1",
"label": "Ouverture gauche"
}
Or for english
{
"key": " handleOrientationLeftKey ",
"languageID": "2",
"label": "Left opening side"
},
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"
},
Adding translations with 3DCloud
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 edit properties panel of the application. 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 (as shown below with "Depth" and "Width"). 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 "commercialDepth".
POST /parameters
{
"key": "commercialDepth",
"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 "commercialDepth" with type "integer", in order to be filtered by this parameter, a base cabinet must have a parameter called "commercialDepth" 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 "commercialDepth".
POST /translations
{
"languageID": 2,
"key": "commercialDepth",
"label": "Depth"
}
See ➡️ Translatoins Webservice documentation:
▪ POST translations 🔗
▪ PUT translations/key 🔗
Translation guidelines
There is no real limitation in the code on the number of characters that can be contributed. The recommendations you will find here are to help you provide texts that will not have negative impacts on the interface. The recommendations are based on the smallest resolution supported (980x648px), with the default product font family & size (helvetica, M=14px). By changing these parameters, the results could be different. The number of characters will be presented with examples using the “x” letters to give approximate length depending on the letters & spaces.
Header
Related translation keys:
- planner.index.step1
- planner.index.step3
- planner.index.step4
Sample:
Guideline: keep it short and start when possible by an action verb.
Behavior: the navigation steps do not have a fixed width. The space they use is related to the needed space for the others to display everything in the limit of 3 lines (spaces in the translation key are needed to jump to a new line).
Warning: there is no break word rule on this component, so if longer words are contributed without any spacing, it will push out the right part of the header with mandatory actions like close & save.
Examples:
11 characters per step (based on “x”) to keep it on 1 line.
Maximum, we reach 35 characters (with spaces) per step (based on “x”) on 3 lines.
Minimal we tested with just numbers (1 character per step)
TO AVOID: be careful to be consistent on the way you write them to avoid mixing really small & large labels and labels with no spacing inside that will not break.
Top bar buttons
Related translation keys:
Step 1 buttons:
- planner.design_room_state.button_importplan
- planner.design_room_state.button_drawplan
- navigation_catalog.design_room_state.openings
- navigation_catalog.design_room_state.objects
- navigation_catalog.design_room_state.covering
- planner.design_room_state.button_watersupply
Step 3 buttons: - navigation_catalog.detailed_design_state.cabinets
- navigation_catalog.detailed_design_state.appliances
- navigation_catalog.detailed_design_state.dining
- navigation_catalog.detailed_design_state.accessories
- planner.detailed_design_state.search
- media_tool.takeAPicture
Sample:
Guideline: keep it short and avoid very long words that could be split in half (see warning section below).
Behavior: There is a fixed width for those buttons of 75px (on a resolution with a width smaller than 1200px): this is the only way to ensure the label won’t shift from the center of the icon and that we keep the same space for and between each button to avoid unbalanced display.
75px is a value chosen so the topbar does not break in the smallest resolution (viewport of 980px width).
The text can take a maximum of two lines.
Resolution exception: On devices with a resolution wider than 1200px, the buttons fixed width is larger: 95px. This allows a larger translation key, but beware, as the rule of 75px width still applies to all smaller devices.
Warning: We can’t enforce this rule, but the translations should follow these guidelines, or else the text will create a third line that won’t be visible.
The word-break rule is not locally specific, as this is only CSS: if the translation has no space in it and is longer than the specified max-width, the CSS rule will break the word when there is no more space (not when grammatically relevant). In this case, we recommend adding a space in the translation where it should break according to the local grammar rule.
Examples:
Maximum: 14 characters per label (based on “x”) to keep it on 1 line (on resolution smaller than 1200px).
Maximum, we reach 30 characters (spaces included) per label (based on “x”) on 2 lines (on resolution smaller than 1200px).
Product card
Behavior:
Title: The rule is set for a maximum of 1 line of text for the product title, with an ellipsis at the end if it is longer and an attribute title holding the entire name (when mouse hovers the title, a native tooltip shows the entire text).
Description: We have two different fixed heights for the description because of the different cases we can handle: with/without energy label, with/without dimensions and we need those 2 items to be stacked at the bottom, even if the description is small. The description can have 3 or 4 lines depending on those cases.
Warning: If the description text is too long, it won’t be visible. For your information: there is no word-break rule in the description, as there should never be a text without any space in it, but should this happen, it won’t break into several lines and be hidden.
Please be aware that the maximum characters numbers in the following examples cannot be totally accurate, because it depends on the width of each word individually and on how spaces are dispatched within the text.
Examples:
Title: Maximum, we reach 30 characters (spaces included, based on “x”) without ellipsing.
Description: Maximum, we reach 140 characters (spaces included, based on “x”) IF the product does not have energy label + dimension and has 4 lines of text available, which is the largest space possible.
Title: When the title exceeds the maximum characters, it is ellipsed.
Description: Maximum we reach with 105 characters (spaces included, based on “x”) IF the product has energy label + dimension and has 3 lines of text available, which is the smallest space possible.
Help center tabs
Related translation keys:
- planner.help_center.tool_tips
- planner.help_center.planning
Guideline: keep it short and avoid very long words that would get cut off.
Behavior: there is a fixed height on the help center header (containing "Help center" title and the tabs) in order to keep it fixed when help center has a inner scroll.
The tabs will grow if there is more than 1 line of text, but 3 should be a maximum to keep a safe margin between the tabs and the scrollable content.
The tab texts are styled as uppercase.
Warning: there is no break-word rule on the tabs, so if longer words are contributed without any spacing, it will push out the other tab until it gets out of the help center container.
Also, in the "Planning" tab, a counter can be displayed on the right of the tab, therefor we should avoid words that are too long and would be displayed underneath it.
Examples:
Maximum 9 "x" for a single word.
Example with 2 lines of 9 "x".
Maximum: 3 lines.
Minimum: 1 character.