{"_id":"590bedd7a160210f00b63f5b","category":{"_id":"560b5cbec341310d00de2a01","pages":["560b5d0b3616ac17004f1c99","560b5d405148ba0d009bd0c9","560b5d62af40a70d003df332","560b5d953bcbd80d0077d0fd","560b5fa83616ac17004f1c9d","569c8c15d326c80d0068f7b7","56d37d35d3f4650b007495ea","56d4ed5f8001e30b0089700c"],"__v":8,"project":"55a6e72e8cc73e0d00096635","version":"55a6e72f8cc73e0d00096638","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-30T03:53:34.449Z","from_sync":false,"order":14,"slug":"templates-required-directory","title":"Templates Reference"},"user":"55a6caa022cfa321008e01d6","version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":0,"parentDoc":null,"project":"55a6e72e8cc73e0d00096635","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-05T03:13:27.989Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":16,"body":"[block:html]\n{\n  \"html\": \"<head>\\n<title>Multi-Language Checkout</title>\\n<meta name=\\\"description=\\\" content=\\\"Steps to translate country names, state names, and other display text within your theme's Optimized One-Page Checkout and order confirmation templates. Supports store internationalization and localization.\\\">\\n</head>\"\n}\n[/block]\nUse these guidelines to enable multi-language text display on your Stencil theme's Optimized&#160;One-Page Checkout and order confirmation pages:\n\n* [Multi-Language Setup](#lang)\n* [Browsing Hidden Translation Keys](#keys)\n* [Adding Your Own Translation Values](#json)\n* [Localized Country and State Names](#places)\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Enable Optimized One-Page Checkout First\",\n  \"body\": \"The options on this page require that you first [enable](/docs/optimized-checkout-prereqs) Optimized One-Page Checkout.\"\n}\n[/block]\n## <span id=\"lang\"> Multi-Language Setup </span>\n\nIn Stencil's default Cornerstone theme, both the Optimized One-Page Checkout and the order confirmation pages contain Handlebars abstracted `{{lang}}` statements to facilitate automatic translation into different locales' natural languages.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"For an overview of how Handlebars `{{lang}}` statements work – including how to supply the statements with language-specific values – please see this documentation's section on [Internationalization](/docs/i18n-l10n).\",\n  \"title\": \"{{lang}} Basics\"\n}\n[/block]\nIn the default checkout page template (located at `<theme-name>/templates/pages/checkout.html`), one example that you can directly view is the page header:\n\n<pre>&lt;h1 class=\"is-srOnly\"&gt;{{<b>lang</b> 'checkout.title'}}</h1>\n</pre>\n\nThese `{{lang}}` statements, like the example above, enable automatic rendering of their parameters into languages that shoppers have selected in their browser preferences. \n\n## <span id=\"keys\"> Browsing Hidden Translation Keys </span>\n\nBigCommerce exposes only part of the checkout page's structure through the local template referenced above. For&#160;security purposes – and also to offer all stores new checkout features simultaneously – most checkout content is hidden.\n\nThis hidden content includes many more key/value pairs that support translation. However, you can see all the available keys – with their default English-language values – in this sample `en.json` file:\n<a href=\"https://developer.bigcommerce.com/assets/opt-checkout-en.json\" target=\"_blank\">https://developer.bigcommerce.com/assets/opt-checkout-en.json</a>\n\n## <span id=\"json\"> Adding Your Own Translation Values </span>\n\nYou can provide values for all of checkout's supported translation keys – for all the languages you want to support – even without direct access to the hidden parts of the checkout template. Here is how:\n\n1. [Download](https://developer.bigcommerce.com/assets/opt-checkout-en.json.zip) and unzip a local copy of the sample file linked above.\n\n2. Copy the file's entire contents to your clipboard:\n    ```\n{\n    \"optimized_checkout\": {\n        \"address\": {\n            \"address_line_1_label\": \"Address Line 1\",\n            \"address_line_1_required_error\": \"Address Line 1 is required\",\n            \"address_line_2_label\": \"Address Line 2\",\n            \"address_line_2_required_error\": \"Address Line 1 is required\",\n            \"address_not_recognized_heading\": \"We did not recognize your address\",\n            \"city_label\": \"City\",\n            [...]\n            \"order_without_support_number_text\": \"An email will be sent containing information about your purchase. If you have any questions about your purchase, email us at <a ng-href=\\\"mailto:{supportEmail}?Subject=Order {orderNumber}\\\" target=\\\"_top\\\">{supportEmail}</a>.\",\n            \"thank_you_customer_heading\": \"Thank you {name}!\",\n            \"thank_you_heading\": \"Thank you!\",\n            \"order_status_update_facebook_messenger_heading\": \"Get instant updates of your order to Messenger\"\n        }\n    }\n}\n    ```\n3. Paste this whole `optimized_checkout` JSON block into your theme's `en.json` file, and into an `xx.json` file for each language into which you want to translate your checkout page's text. (To see requirements for naming and deploying these translation files, please this documentation's [Internationalization](/docs/i18n-l10n) section.)\n\n4. Replace the keys' values with appropriate phrases in each file's target language.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Limitations on Checkout Keys\",\n  \"body\": \"* For checkout, you cannot define keys beyond those that we provide in our sample file.\\n\\n* However, you have the option of omitting any of the key/value pairs we provide. In this case, on your theme's checkout page, any text elements with undefined keys will fall back to English.\"\n}\n[/block]\n## <span id=\"places\"> Localized Country and State Names </span>\n\nWithin the Optimized One-Page Checkout page's `Shipping Address` and `Billing Address` sections, BigCommerce currently provides automatic translation of drop-down lists' displayed `Country` and `State` names into 12 supported languages. Here are the steps for enabling this translation:\n\n1. As for the translation options described above, you must [enable](/docs/optimized-checkout-prereqs) Optimized One-Page Checkout.\n\n2. Within your `<theme-name>/lang/` subdirectory, you must provide a `xx.json` file with the appropriate two-letter prefix for one or more of the `Supported Languages` in the [Naming Requirements](#namereq) table below. (The naming conventions we follow are explained on [this page](/docs/the-schema).)\n\n3. We recommend that you populate that file with the checkout-specific keys/values covered above at [Adding Your Own Translation Values](#json). \n\n  (This is not strictly necessary to translate the drop-down lists, but it is necessary to provide a consistent translation of the surrounding `Address` sections. You do _not_ need to provide any keys/values for the `Country`/`State` names, whose translations are predefined within the BigCommerce platform.)\n\n4. As with the translation options described above, the storefront will automatically display the translated `Country`/`State` names to visitors who have selected one of the supported languages in their browser's locale preferences.\n\n### <span id=\"namereq\"> Country/State Translation – Naming Requirements </span>\n\nBigCommerce Optimized One-Page Checkout will currently translate displayed `Country`/`State` names if your Stencil theme includes `.../lang/xx.json` files named as shown below.\n\n| Supported Language | Required Translation File Name |\n|------|------|\n|  German | `de.json` |\n| Spanish | `es.json` |\n| French | `fr.json` |\n| Hindi | `hi.json` |\n| Italian | `it.json` |\n| Japanese | `ja.json` |\n| Korean | `ko.json` |\n| Dutch | `nl.json` |\n| Punjabi | `pa.json` |\n| Tamil | `ta.json` |\n| Chinese Simplified | `zh-TW.json` |\n| Chinese Traditional | `zh.json` |\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Stencil's Overall Limitations on Translation\",\n  \"body\": \"* Your theme's content will translate only to the extent that you have created JSON files in your `<theme-name>/lang/` subdirectory for each language that you choose to support, and have included key/value pairs for the parameters (beyond `Country`/`State`) that you choose to translate.\\n\\n* Stencil's multi-language capabilities are currently limited to these specific strings that you specify within the theme. The Stencil framework does not currently translate content rendered from a store's database – for example, products' names. \\n\\n* Within these limitations, if you intend to do business internationally, we recommend that you specify appropriate alternate-language strings for key parts of your storefront, product catalog, and checkout. Doing so will make browsing, purchasing, and payment easier for users in your target market(s). For an overview of all localization options, please see [Localizing Stores](/docs/localizing-stores).\"\n}\n[/block]","excerpt":"","slug":"multi-language-checkout","type":"basic","title":"Multi-Language Checkout"}

Multi-Language Checkout


[block:html] { "html": "<head>\n<title>Multi-Language Checkout</title>\n<meta name=\"description=\" content=\"Steps to translate country names, state names, and other display text within your theme's Optimized One-Page Checkout and order confirmation templates. Supports store internationalization and localization.\">\n</head>" } [/block] Use these guidelines to enable multi-language text display on your Stencil theme's Optimized&#160;One-Page Checkout and order confirmation pages: * [Multi-Language Setup](#lang) * [Browsing Hidden Translation Keys](#keys) * [Adding Your Own Translation Values](#json) * [Localized Country and State Names](#places) [block:callout] { "type": "warning", "title": "Enable Optimized One-Page Checkout First", "body": "The options on this page require that you first [enable](/docs/optimized-checkout-prereqs) Optimized One-Page Checkout." } [/block] ## <span id="lang"> Multi-Language Setup </span> In Stencil's default Cornerstone theme, both the Optimized One-Page Checkout and the order confirmation pages contain Handlebars abstracted `{{lang}}` statements to facilitate automatic translation into different locales' natural languages. [block:callout] { "type": "success", "body": "For an overview of how Handlebars `{{lang}}` statements work – including how to supply the statements with language-specific values – please see this documentation's section on [Internationalization](/docs/i18n-l10n).", "title": "{{lang}} Basics" } [/block] In the default checkout page template (located at `<theme-name>/templates/pages/checkout.html`), one example that you can directly view is the page header: <pre>&lt;h1 class="is-srOnly"&gt;{{<b>lang</b> 'checkout.title'}}</h1> </pre> These `{{lang}}` statements, like the example above, enable automatic rendering of their parameters into languages that shoppers have selected in their browser preferences. ## <span id="keys"> Browsing Hidden Translation Keys </span> BigCommerce exposes only part of the checkout page's structure through the local template referenced above. For&#160;security purposes – and also to offer all stores new checkout features simultaneously – most checkout content is hidden. This hidden content includes many more key/value pairs that support translation. However, you can see all the available keys – with their default English-language values – in this sample `en.json` file: <a href="https://developer.bigcommerce.com/assets/opt-checkout-en.json" target="_blank">https://developer.bigcommerce.com/assets/opt-checkout-en.json</a> ## <span id="json"> Adding Your Own Translation Values </span> You can provide values for all of checkout's supported translation keys – for all the languages you want to support – even without direct access to the hidden parts of the checkout template. Here is how: 1. [Download](https://developer.bigcommerce.com/assets/opt-checkout-en.json.zip) and unzip a local copy of the sample file linked above. 2. Copy the file's entire contents to your clipboard: ``` { "optimized_checkout": { "address": { "address_line_1_label": "Address Line 1", "address_line_1_required_error": "Address Line 1 is required", "address_line_2_label": "Address Line 2", "address_line_2_required_error": "Address Line 1 is required", "address_not_recognized_heading": "We did not recognize your address", "city_label": "City", [...] "order_without_support_number_text": "An email will be sent containing information about your purchase. If you have any questions about your purchase, email us at <a ng-href=\"mailto:{supportEmail}?Subject=Order {orderNumber}\" target=\"_top\">{supportEmail}</a>.", "thank_you_customer_heading": "Thank you {name}!", "thank_you_heading": "Thank you!", "order_status_update_facebook_messenger_heading": "Get instant updates of your order to Messenger" } } } ``` 3. Paste this whole `optimized_checkout` JSON block into your theme's `en.json` file, and into an `xx.json` file for each language into which you want to translate your checkout page's text. (To see requirements for naming and deploying these translation files, please this documentation's [Internationalization](/docs/i18n-l10n) section.) 4. Replace the keys' values with appropriate phrases in each file's target language. [block:callout] { "type": "warning", "title": "Limitations on Checkout Keys", "body": "* For checkout, you cannot define keys beyond those that we provide in our sample file.\n\n* However, you have the option of omitting any of the key/value pairs we provide. In this case, on your theme's checkout page, any text elements with undefined keys will fall back to English." } [/block] ## <span id="places"> Localized Country and State Names </span> Within the Optimized One-Page Checkout page's `Shipping Address` and `Billing Address` sections, BigCommerce currently provides automatic translation of drop-down lists' displayed `Country` and `State` names into 12 supported languages. Here are the steps for enabling this translation: 1. As for the translation options described above, you must [enable](/docs/optimized-checkout-prereqs) Optimized One-Page Checkout. 2. Within your `<theme-name>/lang/` subdirectory, you must provide a `xx.json` file with the appropriate two-letter prefix for one or more of the `Supported Languages` in the [Naming Requirements](#namereq) table below. (The naming conventions we follow are explained on [this page](/docs/the-schema).) 3. We recommend that you populate that file with the checkout-specific keys/values covered above at [Adding Your Own Translation Values](#json). (This is not strictly necessary to translate the drop-down lists, but it is necessary to provide a consistent translation of the surrounding `Address` sections. You do _not_ need to provide any keys/values for the `Country`/`State` names, whose translations are predefined within the BigCommerce platform.) 4. As with the translation options described above, the storefront will automatically display the translated `Country`/`State` names to visitors who have selected one of the supported languages in their browser's locale preferences. ### <span id="namereq"> Country/State Translation – Naming Requirements </span> BigCommerce Optimized One-Page Checkout will currently translate displayed `Country`/`State` names if your Stencil theme includes `.../lang/xx.json` files named as shown below. | Supported Language | Required Translation File Name | |------|------| | German | `de.json` | | Spanish | `es.json` | | French | `fr.json` | | Hindi | `hi.json` | | Italian | `it.json` | | Japanese | `ja.json` | | Korean | `ko.json` | | Dutch | `nl.json` | | Punjabi | `pa.json` | | Tamil | `ta.json` | | Chinese Simplified | `zh-TW.json` | | Chinese Traditional | `zh.json` | [block:callout] { "type": "warning", "title": "Stencil's Overall Limitations on Translation", "body": "* Your theme's content will translate only to the extent that you have created JSON files in your `<theme-name>/lang/` subdirectory for each language that you choose to support, and have included key/value pairs for the parameters (beyond `Country`/`State`) that you choose to translate.\n\n* Stencil's multi-language capabilities are currently limited to these specific strings that you specify within the theme. The Stencil framework does not currently translate content rendered from a store's database – for example, products' names. \n\n* Within these limitations, if you intend to do business internationally, we recommend that you specify appropriate alternate-language strings for key parts of your storefront, product catalog, and checkout. Doing so will make browsing, purchasing, and payment easier for users in your target market(s). For an overview of all localization options, please see [Localizing Stores](/docs/localizing-stores)." } [/block]