Importing Localized Data

What this covers

How localized data behaves during imports (CSV/SFTP, API Connector, Mirakl Connector): column format, partial vs full update modes, and how absent or empty locales are handled.

Column format for localized fields

Localized fields in CSV imports use the pattern:

fieldName[locale]

Examples:

For list-type attributes, multiple values in a single locale column are separated by ||.

✅

Main locale fallback: if the column fieldName[mainLocale] is blank but a non-suffixed column fieldName exists, the system reads from the non-suffixed column as the main locale value.

Translatable fields (per entity)

Import modes and locale behavior

DJUST supports two import modes that affect how locale values are handled:

Add (Partial)

Only adds or updates values. Existing data is never deleted.

Add and Replace (Full)

Adds or updates values, and allows explicit deletion via empty values.

✅

In both modes, locales that are absent from the file are always preserved. The system never drops locales that are not included in the import payload.

Example

Starting state: matiere[en-GB] = "Leather", matiere[es-ES] = "Cuero"

Import file contains only matiere[fr-FR] = "Cuir" and matiere[es-ES] = ""

Validation rules at import

• At least one locale must be provided for required translatable fields (e.g. product name). It does not have to be the default locale.
• Locale codes in column headers must match active locales configured on the tenant.

Mirakl Connector specifics

When importing from Mirakl, locale handling has specific behaviors:

Locale format conversion

Mirakl uses underscore format (en_GB) while DJUST uses hyphen format (en-GB). The system converts automatically between the two.

A fallback matching rule also applies: if no exact match is found (e.g. en_GB), the system tries a prefix match (e.g. en).

Multilingual parameter modes

The Mirakl connector supports two modes for mapping localized attributes:

In AUTO mode, the connector automatically detects the locale from the attribute code suffix (e.g. productName_fr_FR is mapped to locale fr-FR).

Custom fields from Mirakl

Mirakl does not translate its custom fields. When custom field values are imported from Mirakl (offers, stores, orders, order lines), DJUST propagates the value identically across all active locales. No locale suffix is used for these fields.

API Connector

For JSON-based API connector imports, localized values use a LocalizedValueSpecification structure:

{
  "localeFieldName": "locale",
  "localeValue": "en-GB",
  "valueFieldName": "value"
}

This maps a JSON path to a specific locale, allowing structured locale-aware payloads.

Impact on indexation

After an import that modifies localized data, a reindex is triggered. Indexes are scoped per locale — only the indexes corresponding to the impacted locales are rebuilt when possible.