Adding support for a language to HCL Commerce

You can use REST API to update your environment database to add support to HCL Commerce for displaying text and content in a language other than the default supported languages.

Before you begin

When you are adding a language, you need to know and use the ISO 639-1 (alpha-2) language code and ISO 3166-1 (alpha-2) country code for the language. For more information about these standards, see You also need to ensure that your locale (language code and country code) is a valid combination that is supported by Java. For more information, see :

Procedure

  1. Compose the REST API request to add a language within HCL Commerce.
    To add a language you need to use the following administrative REST API:
    • Languages (https://localhost:443/rest/admin/v2/languages)
    To compose the API call you need the following details for identifying the locale for the language to be added.
    • The language code. This code must follow the ISP 639-1 (alpha-2) standard, such as "nl" for the Dutch (Netherlands) language.
    • The country code. This code must follow the ISP 3166-1 (alpha-2) standard, such as "NL" for the Netherlands.
    • The language ID. This ID must be a negative integer. This ID is used to identify the language locale within HCL Commerce.
    These codes must be joined using an underscore (" _ ") character to form the locale that is used to identify the language, such as "nl_NL". With this information, you can construct the first POST body for the API call. The body of the call can resemble the following sample body:
    
{
  \"id\": {{langId_nl}},
  \"localeName\": {{localeName}},
  \"language\": {{language}},
  \"country\": {{country}},
  \"variant\": null,
  \"encoding\": \"UTF-8\",
  \"mimeCharSet\": \"UTF-8\"
}
  2. Compose the REST API request to add the descriptive information, such as a display name, for the new language.
    When you are adding language descriptive information you need to use the following administrative REST API:

    This descriptive display name is used by shoppers and business users to identify the language. This name can be visible in the storefront when users are browsing the store in that language or within other languages. The name also displays for the language within Management Center. When you are adding a new language, add a name for your new language in all of the supported languages for your site so that storefront users can identify the new language in whichever supported language they are browsing a store within. Also add a descriptive name for all of your supported languages within your new language so that users can identify the other languages when they are browsing a store within your new language.

    The body of the call to add descriptive information can resemble the following body structure:
    
{
  \"descriptionLanguageId\": {{langId_nl}},
  \"description\": {{ownLanguage}},
  \"languageId\": {{langId_nl}}
}
    • The descriptionLanguageId parameter indicates the language ID of the language for which the description is associated.
    • The languageId parameter indicates the language that must be actively selected for description to be used. For instance, when the value for this ID is "-1" (United States English) the value for the description is the descriptive name for the language that is set with the descriptionLanguageId value.
    You need to complete multiple POST calls to include a description for your newly added language for all supported languages for your store and to include a description of all supported languages for your store within your newly added language.
  3. Run your REST API calls add the language to HCL Commerce.
    To run your REST API calls, you can bundle your REST calls into a JSON collection with the API calls for adding the language to a store to run all the calls in sequence. The following collection shows how to bundle the API calls for adding a language. 
    {
	"info": {
		"_postman_id": "ae005479-0194-47e1-941a-19201b53f624",
		"name": "New Language",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "Create",
			"item": [
				{
					"name": "Post Language",
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "username",
									"value": "{{username}}",
									"type": "string"
								},
								{
									"key": "password",
									"value": "{{password}}",
									"type": "string"
								}
							]
						},
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"type": "text"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n\t\"id\": {{langId_nl}},\n    \"localeName\": {{localeName}},\n    \"language\": {{language}},\n    \"country\": {{country}},\n    \"variant\": null,\n    \"encoding\": \"UTF-8\",\n    \"mimeCharSet\": \"UTF-8\"\n}"
						},
						"url": {
							"raw": "https://{{ts-hostname}}:{{ts-port}}/rest/admin/v2/languages",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "{{ts-port}}",
							"path": [
								"rest",
								"admin",
								"v2",
								"languages"
							]
						}
					},
					"response": []
				},
				{
					"name": "PostLanguage Description in new language",
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "password",
									"value": "{{password}}",
									"type": "string"
								},
								{
									"key": "username",
									"value": "{{username}}",
									"type": "string"
								}
							]
						},
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"type": "text",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n\t\"descriptionLanguageId\": {{langId_nl}},\n\t\"description\": {{ownLanguage}},\n\t\"languageId\": {{langId_nl}}\n}\n"
						},
						"url": {
							"raw": "https://{{ts-hostname}}:{{ts-port}}/rest/admin/v2/language-descriptions",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "{{ts-port}}",
							"path": [
								"rest",
								"admin",
								"v2",
								"language-descriptions"
							]
						}
					},
					"response": []
				},
				{
					"name": "Post English Language Description in new Language",
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "password",
									"value": "{{password}}",
									"type": "string"
								},
								{
									"key": "username",
									"value": "{{username}}",
									"type": "string"
								}
							]
						},
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"type": "text",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n    \"descriptionLanguageId\": {{langId_en}},\n    \"description\": {{englishNewLanguage}},\n    \"languageId\": {{langId_nl}}\n}"
						},
						"url": {
							"raw": "https://{{ts-hostname}}:{{ts-port}}/rest/admin/v2/language-descriptions",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "{{ts-port}}",
							"path": [
								"rest",
								"admin",
								"v2",
								"language-descriptions"
							]
						}
					},
					"response": []
				},
				{
					"name": "Post Langugae Description in English",
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "password",
									"value": "{{password}}",
									"type": "string"
								},
								{
									"key": "username",
									"value": "{{username}}",
									"type": "string"
								}
							]
						},
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"type": "text",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n\t\"descriptionLanguageId\": {{langId_nl}},\n\t\"description\": {{englishLanguage}},\n\t\"languageId\": {{langId_en}}\n}\n"
						},
						"url": {
							"raw": "https://{{ts-hostname}}:{{ts-port}}/rest/admin/v2/language-descriptions",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "{{ts-port}}",
							"path": [
								"rest",
								"admin",
								"v2",
								"language-descriptions"
							]
						}
					},
					"response": []
				},
				{
					"name": "Post Languages to SAS",
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "password",
									"value": "{{password}}",
									"type": "string"
								},
								{
									"key": "username",
									"value": "{{username}}",
									"type": "string"
								}
							]
						},
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"type": "text",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\r\n  \"storeId\": {{storeAssetStroreId}},\r\n  \"languageId\": {{langId_nl}},\r\n  \"currency\": null\r\n}"
						},
						"url": {
							"raw": "https://{{ts-hostname}}:{{ts-port}}/rest/admin/v2/store-languages?",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "{{ts-port}}",
							"path": [
								"rest",
								"admin",
								"v2",
								"store-languages"
							],
							"query": [
								{
									"key": "languageId",
									"value": "-1",
									"disabled": true
								}
							]
						}
					},
					"response": []
				},
				{
					"name": "Post Languages to CAS",
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "password",
									"value": "{{password}}",
									"type": "string"
								},
								{
									"key": "username",
									"value": "{{username}}",
									"type": "string"
								}
							]
						},
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"type": "text",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "\r\n{\r\n  \"storeId\": {{catalogAssetStoreId}},\r\n  \"languageId\": {{langId_nl}},\r\n  \"currency\": null\r\n}"
						},
						"url": {
							"raw": "https://{{ts-hostname}}:{{ts-port}}/rest/admin/v2/store-languages?",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "{{ts-port}}",
							"path": [
								"rest",
								"admin",
								"v2",
								"store-languages"
							],
							"query": [
								{
									"key": "languageId",
									"value": "-1",
									"disabled": true
								}
							]
						}
					},
					"response": []
				},
				{
					"name": "Post Languages to Store",
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "password",
									"value": "{{password}}",
									"type": "string"
								},
								{
									"key": "username",
									"value": "{{username}}",
									"type": "string"
								}
							]
						},
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"type": "text",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\r\n  \"storeId\": {{esiteStoreId}},\r\n  \"languageId\": {{langId_nl}},\r\n  \"currency\": null\r\n}"
						},
						"url": {
							"raw": "https://{{ts-hostname}}:{{ts-port}}/rest/admin/v2/store-languages?",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "{{ts-port}}",
							"path": [
								"rest",
								"admin",
								"v2",
								"store-languages"
							],
							"query": [
								{
									"key": "languageId",
									"value": "-1",
									"disabled": true
								}
							]
						}
					},
					"response": []
				}
			]
		},
		{
			"name": "Build Index",
			"item": [
				{
					"name": "BUILD INDEX",
					"event": [
						{
							"listen": "test",
							"script": {
								"id": "1597ae48-ade9-48ce-b346-09a43a00ff06",
								"exec": [
									"pm.environment.set(\"JobId\", pm.response.json().jobStatusId);",
									""
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "password",
									"value": "passw0rd",
									"type": "string"
								},
								{
									"key": "username",
									"value": "spiuser",
									"type": "string"
								}
							]
						},
						"method": "POST",
						"header": [],
						"body": {
							"mode": "raw",
							"raw": ""
						},
						"url": {
							"raw": "https://{{ts-hostname}}:{{ts-port}}/wcs/resources/admin/index/dataImport/build?masterCatalogId=10001",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "{{ts-port}}",
							"path": [
								"wcs",
								"resources",
								"admin",
								"index",
								"dataImport",
								"build"
							],
							"query": [
								{
									"key": "masterCatalogId",
									"value": "10001"
								}
							]
						}
					},
					"response": []
				},
				{
					"name": "JOB STATUS",
					"request": {
						"auth": {
							"type": "basic",
							"basic": [
								{
									"key": "password",
									"value": "passw0rd",
									"type": "string"
								},
								{
									"key": "username",
									"value": "spiuser",
									"type": "string"
								}
							]
						},
						"method": "GET",
						"header": [],
						"body": {
							"mode": "raw",
							"raw": ""
						},
						"url": {
							"raw": "https://{{ts-hostname}}:3738/search/admin/resources/index/build/status?jobStatusId={{JobId}}",
							"protocol": "https",
							"host": [
								"{{ts-hostname}}"
							],
							"port": "3738",
							"path": [
								"search",
								"admin",
								"resources",
								"index",
								"build",
								"status"
							],
							"query": [
								{
									"key": "jobStatusId",
									"value": "{{JobId}}"
								}
							]
						}
					},
					"response": []
				}
			]
		}
	]
}
    To use this collection, you need to define the environment variables for the API. The API calls within the collection are structured with variables. The values that are used for the variables can be included within a separate JSON file. The following file includes sample values for defining the Dutch Netherlands language. 
    {
	"id": "436186fc-583d-4a22-ab90-a79f8ed560e8",
	"name": "Language",
	"values": [
		{
			"key": "language",
			"value": "\"nl\"",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "country",
			"value": "\"NL\"",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "localeName",
			"value": "\"nl_NL\"",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "langId_nl",
			"value": "-1015",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "langId_en",
			"value": "-1",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "ts-hostname",
			"value": "localhost",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "ts-port",
			"value": "443",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "search-port",
			"value": "3738",
			"description": "",
			"enabled": true
		},
		{
			"key": "ownLanguage",
			"value": "\"Nederland\"",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "englishLanguage",
			"value": "\"Dutch Netherlands\"",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "englishNewLanguage",
			"value": "\"Verenigde Staten Engels\"",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "username",
			"value": "wcsadmin",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "password",
			"value": "wcs1admin",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "esiteStoreId",
			"value": "1",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "storeAssetStroreId",
			"value": "11001",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		},
		{
			"key": "catalogAssetStoreId",
			"value": "10501",
			"description": {
				"content": "",
				"type": "text/plain"
			},
			"enabled": true
		}
	],
	"_postman_variable_scope": "environment",
	"_postman_exported_at": "2019-04-04T14:03:22.468Z",
	"_postman_exported_using": "Postman/7.0.7"
}
    Replace the sample values that are set within the file with the values for the stores and the language that you are adding to your environment. You can then use the collection and values files to run the API requests to add the language.