Locales + Components

[t-kelly]

Context

Our current approach to components has locales as a hard dependency components. At the time of building a collection of components, we scan each component for any locales and then assemble locales files based on the contents of a universal source (archetype-themes/locales).

Problems

Our approach presents both architectural and workflow problems:

1. Locales are state bearing -- A core principal we hold is separating presentation from state. We believe that in order for a piece of liquid to be truly reusable across multiple themes, it must rely on state that is passed to it and fallback to helpful defaults where possible. Linking components to locales during build enforces state being packaged with presentation -- a big no no.
2. Theme Specific Translations - Because locales define and and contain state, similar to setting schemas and settings data, it's something that we want control over at a theme by theme basis. We will reuse lots of translations from theme to theme, but will want the flexibility to do with them as we want for each project.
3. Central Locales Repo Workflow - Relying on a central repo to build components has made developing new components that require new translations cumbersome. You need to open a PR in the translations repo and merge it before you can install the latest version of components with the new translations.

Solution

1. Remove locales from component tooling - Components are a theme level concern, and tooling for them should be used at the theme level, e.g. theme-check.
2. Locales are state being passed into a component - Locales should be treated the same as every other piece of state a component handles. They should have a dedicated param + assign variable which value can be specified via the {% render %} tag and they should have helpful defaults to fallback on. In our case the defaults can be the current locale file key and then finally a static english string. This will remove the need to handle locales for the Component Explorer + Automated Test Fixtures.

[bertiful]

I deep-dived (dove deep?) into this.

While this approach you describe is feasible in theory, it quickly falls apart in practice. The only way this works is if you have simple/straightforward/static translation strings. For example:

{% assign cart_label = 'labels.cart' | t %}

<!-- outputs 'Cart' -->
{{ cart_label }}

This works great! And this is essentially what we're currently doing already, minus the additional assign. However, overriding the cart_label via the snippet param leads to weird results:

<!-- assume 'Hello' is passed to the `cart_label` param -->

{% assign cart_label = cart_label | default: 'labels.cart' | t %}

<!-- outputs 'Translation missing: en.Hello' -->
{{ cart_label }}

This doesn't work because the filter | t isn't exclusive to | default: 'labels.cart', i.e. it isn't grouped with that translation key, and applies to the value of cart_label instead, so this inherently becomes 'Hello' | t.

So then naturally you extract the translation out of the assign to its own assign:

{% assign default_cart_label = 'labels.cart' | t %}
{% assign cart_label = cart_label | default: default_cart_label %}

<!-- outputs 'Hello' if 'cart_label' is passed as a param -->
<!-- outputs 'Cart' if 'cart_label' isn't passed  -->
{{ cart_label }}

This works! But this only works assuming cart_label is being defined as part of the snippet call or the translation key exists in the theme's locale file.

The problem starts when the translation key doesn't actually exist in the theme, and theme-check will underline the key and say it doesn't have a matching entry (which is fine). But you then think "let's have it fall back gracefully, and we can add a fallback default value in case the translation key doesn't exist in the theme":

<!-- assume the 'labels.cart' key doesn't exist in the theme -->

{% assign default_cart_label = 'labels.cart' | t %}
{% assign cart_label = cart_label | default: default_cart_label | default: 'Some default value' %}

<!-- outputs 'Translation missing: en.labels.cart' -->
{{ cart_label }}

This fallback system, i.e. the same one we're using for our other params, doesn't work the same way as for other Liquid variables. The translation key, if not found, doesn't return nil, it returns Translation missing: {locale_code}{whatever_key} and so the hardcoded static English string is never reached.

Keep in mind, these problems I'm mentioning are strictly for static translation strings. What happens when we have dynamic translations like this:

{{ 'actions.terms_i_agree_html' | t: url: cart_terms_conditions_page.url }}

Or even worse, dynamic values within a loop:

{% for cart_discount in cart.cart_level_discount_applications %}
  {%- assign savings = cart_discount.total_allocated_amount | money -%}
  <div class="cart__discount">
    {{ 'info.you_save_amount' | t: saved_amount: savings }}
    ({{ cart_discount.title }})
  </div>
{% endfor %}

I personally don't see any way we can ever have a dynamic value as a customizable param, especially if it lives inside of a loop, but will give this more thought. My goal here was to outline that your aforementioned proposal isn't cut and dry.

[bertiful]

We discussed this with @t-kelly offline.

Our current goal is not to solve all locale-related issues, but to remove locales as a dependency for our components.

We can achieve this by abstracting the logic into a separate snippet that outputs the translation key's value or a fallback if it doesn't exist:

{{ 'my.key' | t: first_name: customer.first_name }}
<!-- becomes -->
{% assign first_name = 'my.key' | t: first_name: customer.first_name %}
{% render 't_with_fallback', t: first_name, fallback: 'Chris Berthe' %}

The t_with_fallback snippet would be:

{% if t contains 'Translation missing:' %}
  {{ fallback }}
{% else %}
  {{ t }}
{% endif %}

Currently, missing translations output a "Translation missing:" message instead of the desired fallback. This solution uses a horrendous if condition, but it's our best option until we propose a platform fix allowing static default strings. Once implemented, we can replace all instances of our snippet easily.

[t-kelly]

Might be worth checking if the error message changes based on the store language?

[bertiful]

Luckily Shopify returns "Translation missing" for all locales.