All Tutorials

Naming and grouping your translation keys

All Tutorials

Naming and grouping your translation keys

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:

  • general.404.title
  • general.404.subtext

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.

  • general

    404, breadcrumbs, search (results page and blank slates), pagination

  • blogs

    article, article comments, blog sidebar

  • cart

    cart contents, updates, notes, link to checkout

  • collections

    collection, collection loop

  • products

    product, product loop, related products

  • layout

    general field titles and identifiers

  • customer

    account, orders (list and details), account activation, addresses, login, password, registration

  • contact

    contact form, form errors

  • home_page

    blank slate, featured, help

  • gift_cards title, usage terms

  • checkout_and_system

    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

<div id="404" class="row">
    <div class="span12">
        <h2>Page not found</h2>
        <span class="subtext">Oops! Something went wrong and we couldn't find the page you were looking for.</span>

404.liquid after internationalization

<div id="404" class="row">
    <div class="span12">
        <h2>{{ 'general.404.title' | t }}</h2>
        <span class="subtext">{{ 'general.404.subtext' | t }}</span>


  "general": {
    "404": {
      "title": "Page not found",
      "subtext": "Oops! Something went wrong and we couldn't find the page
        you were looking for."

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.

Second-level objects

2nd-level objects define the sections in a tab.

Translation-level objects

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.

Translation keys in JavaScript

When you include translation keys in JavaScript, either as part of a script tag in a template file or a .js.liquid asset file, follow these recommendations:

  • Apply the Liquid json filter to your translated key. With that filter, you will avoid unmatched quotes in your JavaScript which would result in a JavaScript syntax error. See the coding examples below.
  • The json filter 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 json filter adds quotes, use the JavaScript + 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 .html suffix on all translation keys that end up being used in JavaScript, to prevent &#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 &#39; and &#34; when added with $.val() or alert. Shopify will escape the quotes once, and then JavaScript will escape the resulting ampersands.)
var link = '<a href="#">' + {{ 'layout.navigation.more_html' | t | json }} + '</a>';
addToCartText.html({{ 'products.product.add_to_cart_html' | t | json }});
addToCartButton.val({{ 'products.product.add_to_cart_html' | t | json }});

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.