Multilingual Attribute Values

The Delivery API supports multilingual attribute values. When your Tweakwise instance contains translated attribute data, the API returns attribute values in the language that matches the request context, enabling headless and custom storefronts to display localised product information without client-side translation logic.

Proposed placement

Delivery API section, after the existing navigation and facets reference pages.

How it works

When multilingual attribute values are configured in your Tweakwise instance (via the feed or Backend API), the Delivery API resolves the correct language for each attribute value at response time. The language is determined by the profile or language context associated with the request.

Request

Include the language context in your Delivery API request using the tn_parameters or the language-specific profile key, depending on your instance configuration. A typical navigation or search request does not change shape — the multilingual resolution happens server-side based on the configured language mapping.

GET /navigation/{instancekey}?tn_q=shoes&tn_lang=en

Response

Attribute values in the response, including facet labels, product attributes, and filter display names, are returned in the resolved language:

{
  "properties": [
    {
      "name": "color",
      "values": ["Blue"]
    },
    {
      "name": "material",
      "values": ["Leather"]
    }
  ],
  "facets": [
    {
      "facetSettings": {
        "title": "Colour"
      },
      "attributes": [
        {
          "title": "Blue",
          "nrofresults": 42
        },
        {
          "title": "Red",
          "nrofresults": 18
        }
      ]
    }
  ]
}

When the same request is made with a different language context (e.g. tn_lang=nl), the translated values are returned instead:

{
  "properties": [
    {
      "name": "color",
      "values": ["Blauw"]
    }
  ],
  "facets": [
    {
      "facetSettings": {
        "title": "Kleur"
      },
      "attributes": [
        {
          "title": "Blauw",
          "nrofresults": 42
        },
        {
          "title": "Rood",
          "nrofresults": 18
        }
      ]
    }
  ]
}

Implementation notes

• Feed setup required: Multilingual attribute values must be present in your product feed or pushed via the Backend API with the appropriate LanguageKey. The Delivery API does not translate values on the fly; it serves pre-indexed translations.
• Fallback behaviour: If a translation is missing for the requested language, the publish pipeline falls back to the default language value configured in the app settings.
• Facet filtering: When a shopper selects a translated facet value, the filter parameter sent back to the API should use the value exactly as returned in the response. The API matches on the resolved language value.

FAQ

Q: Do I need separate Tweakwise instances per language?
No. Multilingual attribute values are resolved within a single instance. You configure translations in your feed or via the Backend API, and the Delivery API returns the correct language based on the request context.

Q: What happens if a translation is missing?
The publish pipeline substitutes the default-language value for any empty translation. This means the Delivery API always returns a non-empty value.

Q: Does this affect filter parameters in subsequent requests?
Yes. Always use the attribute values exactly as returned by the API in your filter parameters. Since values are language-specific, a Dutch facet value like "Blauw" must be sent back as tn_fk_color=Blauw, not the English equivalent.