How to handle multi-language translation for a string on theme app extension?

Shopify Discussion

Topic summary

A developer is seeking guidance on managing translations for customizable strings in a theme app extension for a multilingual Shopify store.

Recommended Solution:

Use Shopify’s built-in i18n (internationalization) system:

  • Create a locales folder at the extension root with separate JSON files for each language (e.g., en.default.json, fr.default.json)
  • Define translation keys in each JSON file with corresponding translated strings
  • Reference keys in Liquid templates using the t filter: {{ 'custom_label' | t }}
  • Shopify automatically serves the correct language based on the user’s storefront language selection

For merchant-editable content:

  • Mark settings as "translatable": true in the extension’s schema file
  • This enables merchants to manage translations through Shopify admin or the Translate & Adapt app

This approach separates translation logic from code and leverages Shopify’s native multilingual infrastructure.

Summarized with AI on October 27. AI used: claude-sonnet-4-5-20250929.
1

I have a use case involving a multilingual store that uses a theme app extension with customisable content. I’m trying to understand how the translation of these customisable strings is managed when the store supports multiple languages.
What would be the recommended approach for handling translations in this scenario?

2

Hi,

For a theme app extension in a multilingual store, the recommended way to handle translatable strings is through Shopify’s i18n (internationalization) system, which works with the locales directory inside your app extension.

Here’s a straightforward way to approach it:

1. Use the locales folder inside your extension
Create a folder named locales at the root of your theme app extension. Inside that, add separate .json files for each language you want to support. For example:

/locales/en.default.json
/locales/fr.default.json
/locales/de.default.json

Each file should include the translatable keys like this:

{
  "custom_label": "Your custom string"
}

2. Refer to translation keys in your Liquid file
Instead of hardcoding strings in your Liquid, use the t filter. For example:

{{ 'custom_label' | t }}

Shopify will automatically pick the correct language version based on the user’s selected storefront language.

3. Updating strings through the Shopify admin (optional)
If your app uses shopify.extension.toml, and you’ve defined settings that are meant to be translatable, Shopify allows the merchant to manage translations for those settings in the admin when multiple languages are enabled.

4. For dynamic or user-generated content
If you’re working with content added by merchants (like custom text blocks), you’d need to make sure those settings are marked as translatable in your schema. You can set this using “translatable”: true for a setting in your extension’s schema file.

This makes the values show up in the Translate & Adapt app or other translation tools connected to the store.