Backend API

Content localization is supported by providing alternative values for each configured locale. Any string or array of strings can be set in multiple locales with the $locale parameter when creating or updating objects.

Locales can be specified with or without a country code (e.g., en and en-US).

Use the format $locale: { <code>: { <field>: value } } with any PUT or POST request. For nested values, the $locale parameter must be defined on the nearest parent object.

All locale content is optional using this API, even if the setting Require content for this locale is enabled in the Swell dashboard.

Example setting localized content
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/products/5cad15bc9b14d1990724663a', {
  name: 'Test product',
  tags: ['tag1', 'tag2'],
  $locale: {
    fr: {
      name: 'Test produit',
      tags: ['étiqueter1', 'étiqueter2']
    },
    es: {
      name: 'Producto de prueba',
      tags: ['etiqueta1', 'etiqueta2']
    },
  },
});

Use the query parameter $locale: <code>, or alternatively an HTTP header X-Locale: <code> with any GET request. All fields with localized values will be returned according to the locale code and fallback settings.

Example retrieving localized content
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  $locale: 'fr'
});
Response
{
  "count": 36,
  "results": [
    {
      "id": "5cad15bc9b14d1990724663a",
      "name": "Test produit",
      "tags": ["étiqueter1", "étiqueter2"],
      ...
    }
  ],
  "page": 1,
  ...
}

To retrieve records with $locale values in order to review localized content or build custom localization interfaces, pass an array of locale codes using the parameter $locale: [<code>, ...] with any GET request. All objects with $locale values will be returned matching the specific locale codes requested.

Example retrieving locale values
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  $locale: ['en', 'fr', 'es']
});
Response
{
  "count": 36,
  "results": [
    {
      "id": "5cad15bc9b14d1990724663a",
      "name": "Test product",
      "$locale": {
        "en": {
          "name": "Test product",
          "tags": ["tag1", "tag2"]
        },
        "fr": {
          "name": "Test produit",
          "tags": ["étiqueter1", "étiqueter2"]
        },
        "es": {
          "name": "Producto de prueba",
          "tags": ["etiqueta1", "etiqueta2"]
        },
      }
      ...
    }
  ],
  "page": 1,
  ...
}