Custom Fields & Attributes — Localization

What this covers

How localization applies to Custom Fields (CF) and Attributes across all entities that support them (orders, products, accounts, etc.). Includes MEDIA specifics and ENUM patterns.

CF - what localizes vs what remains canonical

• CF metadata (name/description): localized maps keyed by IETF tags.
• CF values: canonical.
  • TEXT/NUMBER/BOOLEAN: raw values.
  • ENUM: store the key; labels are localized.
  • MEDIA: store the URL or pointer; it is not localized.

Example - CF with localized metadata

{
  "customField": {
    "code": "DELIVERY_NOTE",
    "type": "TEXT",
    "name": {
      "fr-FR": "Bon de livraison",
      "en-GB": "Delivery note"
    },
    "description": {
      "fr-FR": "Référence du BL",
      "en-GB": "Delivery note reference"
    }
  },
  "value": "BL-2026-00042"
}

Example - CF ENUM (key + labels)

{
  "customField": {
    "code": "SHIPPING_METHOD",
    "type": "ENUM",
    "values": [
      { "key": "STANDARD", "labels": { "fr-FR": "Standard", "en-GB": "Standard" } },
      { "key": "PICKUP",   "labels": { "fr-FR": "Retrait magasin", "en-GB": "Click & Collect" } }
    ]
  },
  "value": "PICKUP"
}

Example - CF MEDIA (all entities)

{
  "customField": {
    "code": "INVOICE_PDF",
    "type": "MEDIA",
    "name": { "fr-FR": "Facture PDF", "en-GB": "Invoice PDF" }
  },
  "value": "https://cdn.example.com/docs/invoice_2026_00042.pdf"
}

⚠️

MEDIA values are always canonical URLs. If you need different assets per language, define separate CFs per language (e.g., INVOICE_PDF_FR, INVOICE_PDF_EN) and show/hide per locale in UI.

Attributes (e.g., product, variant)

• Stored attribute values are canonical (codes/keys/measures).
• Labels for attributes and options are localized per the same rules as CFs.
• ENUM attributes mirror the CF ENUM pattern (canonical key + localized labels).

Suppliers & Orders (entity coverage addendum)

• Suppliers. Localize display names and short descriptions; ids/codes remain canonical.
• Orders. Most fields are canonical; when header-level display labels exist (e.g., a localized order “type” label in BO), treat them like any other label map.
• Order status labels. Provide localized labels alongside the canonical status codes; UIs render labels per locale and keep codes for logic.

Mirakl-specific behavior for Custom Fields

When importing custom fields from Mirakl (offers, stores, orders, order lines):

• Mirakl does not translate its custom fields — values are single-language only.
• DJUST propagates the Mirakl value identically across all active locales on the tenant. No locale-specific suffix is used during import.
• If you need locale-specific custom field values, they must be maintained manually in the Back Office or via a dedicated API import after the Mirakl sync.

✅

This applies to all Mirakl custom field entity types: offers (input), stores (input), orders (output), and order lines (output).

Authoring & governance

• Maintain a locale checklist for each CF/Attribute: which locales are in scope, % coverage, and pending items.
• Avoid duplication: reuse canonical keys/codes; localize only labels.
• Establish a review flow: content author → validator → publish; avoid mixing label authoring with value governance.

Common pitfalls (and how to avoid them)

• Over-localizing values (e.g., storing localized strings instead of keys): store keys; render labels.
• Assuming MEDIA is localized: it’s not. Model per-language assets explicitly as separate CFs/attributes if required (e.g., BROCHURE_PDF_FR, BROCHURE_PDF_EN).
• Inconsistent locale keys: always full IETF tags; don’t mix cases or separators.