Content Delivery API > Localization

Get your project locales

First, you can fetch the list of locales configured in a project with the following query:

query {
  _site {
    locales # -> ["en", "it", "fr"]
  }
}

Get the localizations available for a record

In case you have a model with some localized fields, and the model itself does not require the presence of a localization for each one of the locales configured in a project, you might need to know which localizations are actually present for each record.

The _locales field gives you exactly this information:

query {
  allBlogPosts {
    _locales # -> ["en", "it"]
    title
  }
}

Filter records by available localizations

The same _locales field can also be used to filter your records. For example, you can fetch only the records which have both an en and it localizations this way:

query {
  allBlogPosts(filter: {_locales: {allIn: [it]}}) {
    title
  }
}

You can also use the anyIn criteria to fetch records which contain at least one of the requested localizations, or notIn to fetch records which do not have any of the specified localizations.

Fetching localized content

When you're fetching the value of a localized field, by default it will be returned to the project default locale — that is, the first locale in your project settings:

query {
  _site {
   locales # -> ["en", "it"]
 }
  allBlogPosts {
    title  # -> will return the title value in "en" locale
  }
}

To change that, you can add a locale argument to queries to specify another locale:

query {
  allBlogPosts(locale: it) {
    title  # -> will return the title value in "it" locale
  }
}

You can also specify a different locale on a per-field basis:

query {
  allBlogPosts(locale: it) {
    title # -> will return the title value in "it" locale
    enTitle: title(locale: en) # -> will return the title value in "en" locale
  }
}

Fallback locales

You can also specify a list of fallback locales together with the locale argument:

query {
  allBlogPosts(locale: it_IT, fallbackLocales: [it, en]) {
    title
  }
}

If the field value for the specified locale is null-ish (null, empty string or empty array), the system will try to find a non null-ish value in each of the localizations specified in the fallbackLocales argument. The order of the elements in the fallbackLocales argument is important, as the system will start from the first element in the array, and go on from there.

Just like the locale argument, you can specify different fallback locales on a per-field basis:

query {
  allBlogPosts {
    title(locale: it_IT, fallbackLocales: [it, en])
  }
}

Fetching all localizations

If you want to get the value of a field in every available localization, you can use the _all[FIELD]Locales field:

query {
  allBlogPosts {
    _allTitleLocales {
      locale
      value
    } # -> returns [{ locale: "en", value: "Hi!"}, { locale: "it", value: "Ciao!"}]
  }
}

Learn more about localization with DatoCMS

DatoCMS allows a great deal of customization when dealing with localization. Check out these tutorial videos for a hands-on approach:

Localizing Content in DatoCMS

Play video »

Creating a localized blog using Next.js

Play video »