If you are working with content that needs to be available in multiple languages, locales let you define localizations of content and select a specific locale when querying the Content Delivery API.

Every Space has its own set of locales, and each locale is uniquely identified by its ISO code (e.g., en-US or de-AT). There's always one default locale defined when you create a space, shown by default in the Contentful web app and used for Content Delivery API queries that do not request a specific locale.

Adding a locale

You can add a new locale to a space in the Contentful web app or by using the Content Management API.

With the Web App

To add a locale in the web app, open Settings -> Locales and click Add locale:

Choose a locale and its options:

With the API

If you are writing scripts or applications, use the Content Management API to add a locale to a space use the following POST request with the name and ISO code contained within the body:

curl -X POST
  -H "Authorization: Bearer <CONTENT_MANAGEMENT_KEY>"
  -H "Content-Type: application/vnd.contentful.management.v1+json"
  -d '{
   "name":"English (British)",
   "code":"en-GB"
}'
"https://api.contentful.com/spaces/<SPACE_ID>/locales"

There are a couple of other options you can send with the API call, read our API documentation to find out more.

Locales and fields

After adding a locale to a space, you can define which fields in your content types you want localized. You can do this with the web app or the Content Management API.

With the Web App

To enable localization of a field in the web app, check the corresponding option in the field settings:

With the API

It's possible to use the Content Management API to update content types and localize fields.

The following PUT request enables localization for the fields productName and productDescription of the content type Product by setting their localized property to true:

curl -X PUT
  -H "Authorization: Bearer <CONTENT_MANAGEMENT_KEY>"
  -H "Content-Type: application/vnd.contentful.management.v1+json"
  -d '{
  "name": "Product",
  "displayField": "productName",
  "fields": [
    {
      "name": "Description",
      "id": "productDescription",
      "type": "Text",
      "localized": true,
      "validations": []
    },
    {
      "name": "Product name",
      "id": "productName",
      "type": "Text",
      "localized": true,
      "validations": []
    },
    // Other fields in content type
  ]
}'
"https://api.contentful.com/spaces/<SPACE_ID>/content_types/<CONTENT_TYPE_ID>"

Next, select which translations will be available for each entry:

After this step, entries will have different field values for each locale:

Retrieving entries without a specific locale / Fallback locales

When you request content via the CDA there can be situations where there is no content for the requested locale. In these cases the API will, by default, return content for the default locale in the space (provided there's content for it). You can override this behaviour by setting a custom fallbackCode in your locale. If there's no content for a locale but it exists for the fallback locale, then the CDA will return its content.

Considerations on fallback locales:

• If you don't want a locale to fallback to anything, set its fallbackCode property to null.
• You can create fallback chains. For example de-CH (Swiss German) fallbacks to de-AT (Austrian German) and de-AT fallbacks to de-DE (German German) is a valid setup. If a locale in the chain doesn't have content, the API will try the next one.
• Your fallback chain can't contain cycles, for example a fallback chain where de-CH fallbacks to de-AT and de-AT fallbacks to de-CH.
• Contentful will only use the content of the fallback locale when the requested one is not present in the entry or asset (i.e. you request 'en-US' but the entry has only content for 'de-DE'). This means that values like null or an empty string ("") will not cause the system to use the value of the fallback locale. This can only be set via the API, and not with the Web app or SDKs.
• If you don't specify a locale in your request, you will receive the entry from the default locale (en-US in this example):

curl -X GET "https://cdn.contentful.com/spaces/<SPACE_ID>/entries/<ENTRY_ID>?access_token=<CONTENT_DELIVERY_KEY>"

Retrieving entries with a specific locale

If you want to retrieve fields from a specific locale (e.g de-AT), use the locale=de-AT parameter in your request:

curl -X GET "https://cdn.contentful.com/spaces/<SPACE_ID>/entries/<ENTRY_ID>?access_token=<CONTENT_DELIVERY_KEY>&locale=de-AT"

Retrieving all translations for an entry

You can retrieve all localized versions of an entry by using the 'wildcard' locale=* parameter:

URL of request

curl -X GET "https://cdn.contentful.com/spaces/<SPACE_ID>/entries/<ENTRY_ID>?access_token=<CONTENT_DELIVERY_KEY>&locale=*"

Locales and the Sync API

No matter which locale you specify, the synchronization API always includes all localized content, using the same structure as the wildcard locale option above:

URL of request

curl -X GET "https://cdn.contentful.com/spaces/<SPACE_ID>/entries/<ENTRY_ID>sync?initial=true?access_token=<CONTENT_DELIVERY_KEY>&locale=de-AT"