Using Locales in APIs

What this covers

How to read and write localized data correctly. This page stays aligned with existing contracts and avoids adding non-standard params.

Reading localized data

• Expect objects to include label maps where applicable (names, descriptions, option labels).
• Entities that typically expose label maps include: Product, Variant, Navigation category, Attribute/option, Supplier, and Order status labels.
• Your client picks the label using the requested locale, then applies the fallback chain if missing.
• The canonical value is always present and does not depend on locale.

Read - conceptual snippet

{
  "name": { "fr-FR": "Nom", "en-GB": "Name" },
  "description": { "fr-FR": "Description", "en-GB": "Description" },
  "enumValues": [
    { "key": "STANDARD", "labels": { "fr-FR": "Standard", "en-GB": "Standard" } },
    { "key": "PICKUP",   "labels": { "fr-FR": "Retrait magasin", "en-GB": "Click & Collect" } }
  ],
  "value": "PICKUP"
}

Writing localized metadata (labels) vs values

• When updating labels/metadata (e.g., CF name/description or ENUM option labels), send maps keyed by IETF tags.
• When setting values, always send the canonical form (key/URL/code/number).

Write - conceptual patterns

// Update localized metadata (labels)
{
  "name": { "fr-FR": "Nom", "en-GB": "Name" },
  "description": { "fr-FR": "Description", "en-GB": "Description" }
}

// Set an ENUM value (canonical key)
{ "value": "PICKUP" }

// Set a MEDIA value (canonical URL)
{ "value": "https://cdn.example.com/files/invoice_2026_00042.pdf" }

⚠️

Localization is not negotiated via a global “active locale” header in most surfaces. Clients are responsible for label selection and fallback.

Validation & compatibility notes

• Use IETF tags that are supported by the store/tenant where you render content.
• If a label is missing, rely on the fallback chain rather than sending partial non-IETF keys.
• Refer to the API Reference for route-specific validation/error semantics; do not assume implicit server formatting.

End-to-end testing matrix

• Single store, single locale: labels render without fallback.
• Single store, multiple locales: switch locales and verify each label set; confirm fallback when intentionally missing.
• ENUM flows: write canonical key; confirm UI renders localized label in each locale.
• MEDIA flows (all entities): upload/link once; confirm the same URL is used across locales; UI may show different CFs if you model per-language assets.
• Navigation. Category names/breadcrumbs render correctly per locale; category ids remain stable.
• Suppliers. Supplier names render per locale; ids/codes remain stable.

Performance notes

• Label maps are lightweight; cache normalized (value → chosen label) pairs per locale to reduce repeat selection.
• When fetching many items, prefer bulk/list endpoints and perform label selection client-side in a single pass.