Locales and translations
Locales define the languages a project can resolve. Translations provide language-specific values for supported fields without duplicating the underlying product, category, collection, attribute, or other translatable resource.
Locale lifecycle
Create the locale codes the project supports, activate the ones clients may request, and choose the default. Removing or deactivating a locale affects resolution, so inspect existing translations and consuming storefronts before changing its lifecycle.
Storefront operations accept locale where translated fields can be resolved. When the requested translation is missing, Thor uses the configured default behavior; clients must still tolerate an absent optional value. Test requested, default, and missing-locale cases with the same resource.
Translation keys and values
translationsUpsertBulk accepts an entity ID and a list of key, locale code, and value entries. Use the exact translation keys exposed by the entity’s translatable fields; do not invent parallel metafields for ordinary localized names and descriptions.
For high-volume work:
- translationsExport creates an asynchronous export job filtered by entity types and locale codes.
- translationsImport uploads a translation file for asynchronous processing.
- Query the returned job until it reaches a terminal state, then inspect its errors before treating the sync as complete.
Do not invent translation keys. Use the keys exposed by the translatable entity contract. A translation associates an entity, field key, locale code, and value; the entity remains the identity and lifecycle owner.
Import and export
Choose translations or custom data
- Put customer-facing translated prose in translations.
- Put operational or domain-specific structured values in metafields.
- Put searchable merchandising concepts in native tags, categories, collections, and attributes where possible.