Localization - Concept & Rules
What this covers
The core principles behind localization in DJUST: IETF locale tags, what is localized vs canonical, how fallback works, and practical guidance for integrators.
Principles
- IETF locale tags only (e.g.,
fr-FR,en-GB,de-DE). Use full tags everywhere: data models, payloads, and content authoring. - Localized vs canonical:
- Localized: human-readable labels (names, display values, descriptions).
- Canonical: the stored values (codes, keys, URLs, numbers) are not locale-dependent.
- Server returns canonical + label maps. UIs choose which label to render (requested locale), applying a deterministic fallback when missing.
- Formatting (dates, numbers, currency) is a UI concern. API payloads keep canonical forms; do not expect server-side formatting by locale.
- Platform-wide scope. All customer-facing data must be translatable regardless of source (Back Office, imports, APIs).
What is localized (and what is not)
| Area | Localized (per locale) | Canonical (single value) |
|---|---|---|
| Field/option labels | Yes — {"fr-FR":"Nom","en-GB":"Name"} | - |
| Descriptions / help text | Yes — per locale maps | - |
| ENUM display options | Yes — labels per locale | key (e.g., "PICKUP") |
| MEDIA values (all entities) | - | URL/string (e.g., "https://cdn…/file.pdf") |
| Numbers, codes, references | - | canonical code/value (UI formats for display) |
| Navigation categories | Yes — category names, breadcrumbs | canonical category ids |
| Product / Variant | Yes — titles, marketing labels, descriptions | variant/product ids, SKU, attribute values (keys/codes) |
| Attributes (names & option labels) | Yes — localized names/labels | attribute codes and option keys |
| Suppliers | Yes — supplier display names, descriptions | supplier ids/codes |
| Orders (header labels only) | Yes — human-readable labels if present in BO | order id/reference, status codes remain canonical |
| Order statuses (labels) | Yes — localized label strings | status codes canonical |
| Emails (template content) | Yes — subject/body per locale | template identifiers, links, media URLs |
Think “labels localize, values don’t”. Your UI always renders the label for the selected locale; it stores/sends the same canonical value regardless of locale.
Fallback for labels (deterministic)
When a label is missing for the requested locale, DJUST applies this chain:
- Requested exact IETF tag (e.g., en-GB)
- Store default locale
- Tenant default locale
- Empty string (if no translation exists at all)
This applies to labels only. Canonical values never fall back — they’re the same everywhere.
Fallback by context
The general chain above applies everywhere, but each context has specific nuances:
| Context | Behavior |
|---|---|
| Indexation | At index time, if the requested locale has no value, the tenant default locale is used. If still empty, the field is indexed as "". One index is created per store x store-view x locale combination. |
| Front APIs | When Front Office APIs are called, localized data is returned in the requested locale. If missing, the same fallback chain applies (store default → tenant default). |
| Imports | At import time, at least one locale is required for mandatory fields (e.g. product name). It does not have to be the default locale. Missing translations are resolved at indexation/display time via fallback. |
| Emails | The customer user’s locale is used. If the template does not exist in that locale, the store default locale is used, then the tenant default. |
| Back Office | Information is displayed in the store’s default locale. If not available, the tenant default locale is used. |
Worked example (ENUM)
{
"key": "PICKUP",
"labels": {
"fr-FR": "Retrait magasin",
"en-GB": "Click & Collect",
"de-DE": "Abholung im Geschäft"
}
}- Stored value in orders, carts, or CFs: "
PICKUP". - Rendered label depends on requested locale and the fallback chain.
Best practices
Do:
- Use IETF tags consistently in content and payloads.
- Treat labels as localized, values as canonical.
- Apply the fallback chain only to labels.
Don’t:
- Don’t change stored values by locale.
- Don’t rely on server to format numbers/dates/currency.
- Don’t store localized strings as values; always store canonical keys and localize labels only.
FAQ
-
Q: Can I request “the server’s best label” via a special header?
A: The platform exposes label maps. Clients pick the appropriate label and apply fallback in UI/business logic.
-
Q: Do MEDIA values vary by locale?
A: No. MEDIA stores URLs/canonical strings. If you need per-language assets, model separate fields per language.
-
Q: Are order status labels localized?
A: Yes (labels), but status codes are canonical. UIs pick the localized label and keep the code for logic/filters.
-
Q: Can navigation/category trees be localized?
A: Yes—names and breadcrumbs are localized; category ids remain canonical.
-
Q: Can I change the tenant’s default locale after creation?
A: No. The default locale is set at tenant creation and cannot be changed. Changing it would require a full environment reset and data re-import.
-
Q: What happens if a product has no translation in the default locale?
A: At import, it is accepted as long as at least one locale is provided. At display/indexation time, the fallback chain applies — the field may end up as an empty string if no locale has a value.
Updated 25 days ago