Store Locales & Overrides

What this covers

How stores declare supported locales and a default; how that influences label fallback; and practical patterns for multi-store, multi-locale sites.

Store configuration (conceptual)

Each store defines:

• defaultLocale - the store’s primary locale (e.g., fr-FR).
• supportedLocales - set of IETF tags allowed for UI rendering.

Store locales must be a subset of the tenant’s locales. You cannot add a locale to a store if it does not exist at the tenant level.

⚠️

Tenant default locale is immutable. It is set at tenant creation and cannot be changed afterwards. See Managing Locales for details.

Example

{
  "id": "STORE-FR",
  "defaultLocale": "fr-FR",
  "supportedLocales": ["fr-FR", "en-GB"]
}

How it’s used at runtime

• Your UI chooses a requested locale (user preference, URL, or store default).
• When a label is missing for that locale, apply fallback: store default → tenant default → system default.
• The scope (Account/Store/Store-view) you send to APIs determines which content set you receive; label maps are returned with the object.

✅

Changing the requested locale only affects which label you show — not the stored values.

Indexing & search (per locale)

• Per-locale documents. Search/index pipelines produce language-aware documents for localized fields (e.g., product/variant title, category name).
• Index per store x store-view x locale. Each index is named following the pattern {tenant}_{store}_{storeView}_{locale}. Only the locale combinations actually configured on each store are indexed — not all possible tenant-level combinations.
• Index selection. At query time, the UI (or API surface in scope) selects the effective locale; queries run against the corresponding language index/fields.
• Reindex triggers. Updating localized labels (product, variant, attributes, navigation) triggers reindex for the impacted locale only where possible.
• Fallback at index time. If a field has no value in the target locale, the tenant default locale is used. If still empty, the field is indexed as "".
• Fallback vs index. Fallback is a rendering rule; try to keep indexes complete per locale to reduce reliance on runtime fallback.

Patterns & edge cases

• Multi-store with shared catalog: ensure all stores’ supportedLocales cover the locales you intend to render; otherwise, labels may fall back more often.
• Gradual rollout: start with a minimal set (e.g., fr-FR) and add locales iteratively. You can publish labels progressively; fallback ensures continuity.
• Content completeness: build a report to detect missing labels per locale for critical entities (products, attributes, CF names, ENUM options).

Testing checklist

• Store default renders labels without fallback when present.
• Switching to a supported locale renders the correct label.
• Missing labels follow the fallback chain deterministically.
• No request assumes server-formatted numbers/dates/currency.
• Reindex after localized updates is scoped to changed locales.
• Queries return language-appropriate hits (tokenization/stemming per locale).