Text Localization

When managing your storefront, you'll often work with text that needs to be translated into multiple languages to support users across multiple geographies. This doc covers how we manage localized text objects via our APIs.

Certain API objects, like Items, have a text field used to define translations for all relevant strings on that object. Every text field has the same structure:

{
  "en-US": {
    "field1": "...",
    "field2": "...",
  },
  "de-DE": {
    "field1": "...",
    "field2": "...",
  },
  // ...
}

The keys of this object are IETF BCP 47 locale codes. The structure of the value object is the same for each locale, and is specific to the API object you're modifying. For example, the Item object's text field has the following structure:

{
  "en-US": {
    "nameSingular": "gem",
    "namePlural": "gems",
    "description": "A gem used to purchase special upgrades"
  },
  "de-DE": {
    "nameSingular": "Juwel",
    "namePlural": "Juwelen",
    "description": "Ein Edelstein, mit dem besondere Upgrades erworben werden können"
  },
  // ...
}

Region-specific overrides

IETF region codes are layered: en refers to English in general, en-GB refers to English in Great Britain specifically, and so on. In most cases, it's unlikely that there will be significant differences between, e.g. en-US and en-GB translations, so you can just use en to use a set of translations for any locale starting with en.

If, however, you then need to override translations for one sub-locale, you'll need to pass in the entire set of translations, not just the translations you want to override:

// ❌ incorrect
{
  "en": {
    "nameSingular": "gem",
    "namePlural": "gems",
    "description": "A gem used to purchase special upgrades"
  },
  "en-GB": {
    "description": "A gem used to purchase special upgrades, old chap"
  },
  // ...
}
  
// ✅ correct
{
  "en": {
    "nameSingular": "gem",
    "namePlural": "gems",
    "description": "A gem used to purchase special upgrades"
  },
  "en-GB": {
    "nameSingular": "gem",
    "namePlural": "gems",
    "description": "A gem used to purchase special upgrades, old chap"
  },
  // ...
}