Naming and grouping your translation keys
The Shopify Language Editor uses the translation keys that you build into your theme, to enable merchants to modify or create translations of their storefronts.
Basic key structure
A translation key takes the form:
Each level of the key is used to navigate to a level of the hierarchy of the Shopify Language Editor:
- 1st level: Translation category References one of the top-level tabs in the Shopify Language Editor.
- 2nd level: Translation group References a group of related translations under a top-level tab in the Shopify Language Editor.
- 3rd level: Translation description In a template file, this labels the corresponding translation in the locale file.
For example, an internationalized
404.liquid template file might contain code like this:
The two translation keys in this example are:
The same keys in a locale file for this theme would contain the translations:
Organizing your translation keys
To ensure that translations are mapped correctly, and to keep the process as simple as possible for merchants, make sure that:
- your keys and key groupings closely reflect the structure of your theme
- the first two levels of the keys in your template files are consistent with the 1st and 2nd level key grouping in your locale files.
Design keys to reflect your theme structure
Formulate the first two levels of your keys in line with the organizational design of your theme. The structure will typically resemble the following arrangement, but you can vary it, and add or remove keys as necessary.
404, breadcrumbs, search (results page and blank slates), pagination
article, article comments, blog sidebar
cart contents, updates, notes, link to checkout
collection, collection loop
product, product loop, related products
general field titles and identifiers
account, orders (list and details), account activation, addresses, login, password, registration
contact form, form errors
blank slate, featured, help
gift_cards title, usage terms
date and day formats, form fields, error messages, checkout flow
Use translation keys consistently between files
Be sure to use translation keys consistently between your template files and your locale files.
As an example, compare the following two versions of the
404.liquid template file:
404.liquid before internationalization
404.liquid after internationalization
How keys determine the layout of the Shopify Translation Editor
The grouping and sequence of your translation keys dictate how the information is displayed in the Shopify Language Editor.
Top-level translation key groups
1st-level groups are used to determine the tabbed interface in the Shopify Language Editor.
2nd-level objects define the sections in a tab.
The third level represents the translation strings.
Translation keys in code snippets
If you have translation keys in snippets, classify them based on the snippet's role. For example, a key included in a
related-product.liquid snippet should be included in your products group.
.js.liquid asset file, follow these recommendations:
- Apply the Liquid
jsonfilter will wrap your translation in quotes, so don't add your own quotes around your Liquid tag. See the coding examples below.
- Also, because the
+operator to concatenate your translation to surrounding HTML segments. Don't just insert the Liquid tag as is within an HTML segment. See the first coding example below.
- Finally, use the
&#XX;characters from showing up on your store pages. (Shopify escapes all translations except those that use
.html. For example, as a result of not using
.html, single quotes and double quotes in a translation will end up being rendered as
"when added with
If you're submitting to the Shopify Theme Store
There are no limitations to creating new keys or removing current ones for your theme. If you submit to the Shopify Theme Store, we will look for robust key organization before we accept your theme.
Good key organization leads to better user experience for merchants who use the Shopify Language Editor.