Managing Locales

What this covers

How to set up and manage locales at the tenant and store levels: adding, activating, deactivating, deleting locales, and key constraints you must know before going live.

Locale model

Each locale in DJUST is defined by:

⚠️

A locale must be active before it can be set as main. Conversely, the main locale cannot be deactivated or deleted.

Tenant-level locales

Concept

Every tenant has a set of locales configured at initialization. These locales define the full language repertoire available across the entire platform. Store-level locales are always a subset of tenant locales.

Key constraint: the default locale is immutable

The tenant's main locale (default) is set at tenant creation and cannot be changed afterwards. Changing it would require a full environment reset and re-import of all data to ensure consistency.

How to manage

Tenant locales can be managed through:

• Back Office: General settings > Locales management
• Admin API: see endpoints below

Mirakl context

When the platform is connected to Mirakl, tenant locales are synchronized automatically via the Mirakl L01 API (platform languages). In this case:

• All active languages from Mirakl are imported with active = true.
• The platform_default flag from Mirakl maps to the main field.
• Manual editing of locales in the Back Office is disabled to prevent desynchronization.

Store-level locales

Concept

In a multi-store setup, each store can define its own set of locales and its own default locale. Store locales must be chosen from the tenant's locale pool — you cannot add a locale to a store if it does not exist at the tenant level.

Each store has:

• Supported locales: the set of IETF tags available for that store.
• Default locale (main = true): the store's primary locale, used for fallback and Back Office display.

How to manage

Validation rules

The platform enforces these constraints:

For the full list of error and warning codes, see Error / Warning codes.

Fallback chain

When a localized label is missing for the requested locale, DJUST applies this deterministic chain:

flowchart LR
    %% Styles (Readme)
    classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
    classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
    classDef ok       fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
    classDef stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

    A["📘 Client requests label<br>for locale e.g. en-GB"]:::read --> B{"Label exists<br>for requested locale?"}:::decision
    B -->|Yes| C["✅ Return label"]:::ok
    B -->|No| D{"Store default<br>locale configured?"}:::decision
    D -->|Yes| E{"Label exists for<br>store default?"}:::decision
    E -->|Yes| C
    E -->|No| F{"Label exists for<br>tenant default?"}:::decision
    D -->|No| F
    F -->|Yes| C
    F -->|No| G["Empty string"]:::stop

✅

This fallback applies to labels only (names, descriptions, option display values). Canonical values (codes, keys, URLs) are never locale-dependent.

Impact on other features