Localization

GraphCMS boasts a flexible localization API that you can use to publish content for all or specific locales in your project.

Localized content can be managed through the GraphCMS UI, or via GraphQL mutations.

Localizing fieldsAnchor

When adding a field that can be localized inside the schema editor, such as a string, mark the field as can be localized, and you will be able to perform all of the localization queries, and mutations outlined below.

The model will be updated to contain additional localized system fields that you can use to fetch localized content.

Fetching localized contentAnchor

Fetching localized content is done by fetching content the same way you are used to. For example, a product model containing localized fields can be queried like so:

{
  product(where: { id: "..." }) {
    name
  }
  products {
    name
  }
}

The above will return the default locale values for the fields requested.

Default localeAnchor

As shown as above, queried content will always return the default locale, unless told otherwise.

You can set the default locale inside Settings > Locales.

Fallback locale(s)Anchor

Locales will be returned in the order they are requests, from left to right.

In this example, we will request products with the locales en, and de.

{
  products(locales: [en, de]) {
    id
    locale
    name
  }
}

{
  "data": {
    "products": [
      {
        "id": "ck3ee0ltu3kfn0b73wbslopia",
        "locale": "en",
        "name": "Unisex Long Sleeve Tees"
      },
      {
        "id": "ck3itjds7hnwo0b66au5rkvm9",
        "locale": "en",
        "name": "Snapback"
      },
      {
        "id": "ck3oqti2stn5o0b20ogmpwxer",
        "locale": "en",
        "name": "Unisex Zip Hoodie"
      },
      {
        "id": "ck3shntzy1xxw0b324jfxcjtl",
        "locale": "en",
        "name": "Mug"
      }
    ]
  }
}

HTTP headerAnchor

You can pass the gcms-locales header when localized content with your required locales.

const fetch = require('cross-fetch');

const headers = {
  'Content-Type': 'application/json',
  'gcms-locales': 'en',
};

const body = JSON.stringify({ query: '{ products { name } }' });

const { products } = await fetch('<your-graphcms-endpoint>', {
  method: 'POST',
  headers,
  body,
});

You can also pass an array of locales to gcms-locales to define your fallback preference.

All localizationsAnchor

Whether you're fetching a single content entry, or multiple, you can fetch all localizations of that entry.

{
  products {
    id
    name
    localizations {
      id
      name
      locale
    }
  }
}

{
  "data": {
    "products": [
      {
        "id": "ck3ee0ltu3kfn0b73wbslopia",
        "name": "Unisex Long Sleeve Tees",
        "localizations": [
          {
            "id": "ck3ee0ltu3kfn0b73wbslopia",
            "name": "Unisex Longsleeve",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3itjds7hnwo0b66au5rkvm9",
        "name": "Snapback",
        "localizations": [
          {
            "id": "ck3itjds7hnwo0b66au5rkvm9",
            "name": "Cap",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3oqti2stn5o0b20ogmpwxer",
        "name": "Unisex Zip Hoodie",
        "localizations": [
          {
            "id": "ck3oqti2stn5o0b20ogmpwxer",
            "name": "Unisex Hoodie",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3shntzy1xxw0b324jfxcjtl",
        "name": "Mug",
        "localizations": [
          {
            "id": "ck3shntzy1xxw0b324jfxcjtl",
            "name": "Tasse mit Print",
            "locale": "de"
          }
        ]
      }
    ]
  }
}

Since the root graphql type returns the default locale en values, you'll notice the localizations response above returns just the de content entries.

Pass includeCurrent: true inside the localizations query arguments to include the default en locale.

{
  products {
    id
    name
    localizations(includeCurrent: true) {
      id
      name
      locale
    }
  }
}

{
  "data": {
    "products": [
      {
        "id": "ck3ee0ltu3kfn0b73wbslopia",
        "name": "Unisex Long Sleeve Tees",
        "localizations": [
          {
            "id": "ck3ee0ltu3kfn0b73wbslopia",
            "name": "Unisex Long Sleeve Tees",
            "locale": "en"
          },
          {
            "id": "ck3ee0ltu3kfn0b73wbslopia",
            "name": "Unisex Longsleeve",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3itjds7hnwo0b66au5rkvm9",
        "name": "Snapback",
        "localizations": [
          {
            "id": "ck3itjds7hnwo0b66au5rkvm9",
            "name": "Snapback",
            "locale": "en"
          },
          {
            "id": "ck3itjds7hnwo0b66au5rkvm9",
            "name": "Cap",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3oqti2stn5o0b20ogmpwxer",
        "name": "Unisex Zip Hoodie",
        "localizations": [
          {
            "id": "ck3oqti2stn5o0b20ogmpwxer",
            "name": "Unisex Zip Hoodie",
            "locale": "en"
          },
          {
            "id": "ck3oqti2stn5o0b20ogmpwxer",
            "name": "Unisex Hoodie",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3shntzy1xxw0b324jfxcjtl",
        "name": "Mug",
        "localizations": [
          {
            "id": "ck3shntzy1xxw0b324jfxcjtl",
            "name": "Mug",
            "locale": "en"
          },
          {
            "id": "ck3shntzy1xxw0b324jfxcjtl",
            "name": "Tasse mit Print",
            "locale": "de"
          }
        ]
      }
    ]
  }
}

Mutating localized contentAnchor

Just like you can query localized content, you can also create, update, upsert, and delete localized content using the Mutations API.

Let's continue with the products model in our examples below. We can use the auto-generated mutations for modifying the locales for each entry.

Create a localizationAnchor

mutation {
  updateProduct(
    where: { id: "..." }
    data: {
      localizations: {
        create: { locale: de, data: { name: "Tasse mit Print" } }
      }
    }
  ) {
    id
  }
}

You can also pass an array of localizations for locales that aren't your projects default. For example, here we create localizations for both de, and es.

mutation {
  updateProduct(
    where: { id: "..." }
    data: {
      localizations: {
        create: [
          { locale: de, data: { name: "Tasse mit Print" } }
          { locale: es, data: { name: "Taza con estampado" } }
        ]
      }
    }
  ) {
    id
  }
}

The examples here assume you already have a product that you can update. It is possible to create a new entry, with the base locale, and the localized content via localizations at the same time:

mutation {
  createProduct(
    data: {
      name: "Mug"
      localizations: {
        create: [
          { locale: de, data: { name: "Tasse mit Print" } }
          { locale: es, data: { name: "Taza con estampado" } }
        ]
      }
    }
  ) {
    id
    localizations(includeCurrent: true) {
      title
    }
  }
}

Update a localizationAnchor

mutation {
  updateProduct(
    where: { id: "..." }
    data: { localizations: { update: { locale: en, data: { name: "Mug" } } } }
  ) {
    id
  }
}

Upsert a localizationAnchor

Just like you can create, or update content entries by unique filters, you can either also upsert localizations. Simply pass the locale you want to update, or create if it does not exist.

mutation {
  createProduct(
    where: { id: "..." }
    data: {
      localizations: {
        upsert: {
          locale: de
          create: { name: "Tasse mit Print" }
          update: { name: "Tasse mit Print" }
        }
      }
    }
  ) {
    id
  }
}

Delete a localizationAnchor

You can delete all but the default localization using the auto-generated delete mutation.

mutation {
  deleteMessage(
    where: { id: "..." }
    data: { localizations: { delete: { locale: de } } }
  ) {
    id
  }
}