REST API: `locale`

The Internationalization (i18n) feature adds new abilities to the REST API.

Prerequisites

To work with API content for a locale, please ensure the locale has been already added to Strapi in the admin panel.

The locale API parameter can be used to work with documents only for a specified locale. locale takes a locale code as a value (see full list of available locales).

Tip

If the locale parameter is not defined, it will be set to the default locale. en is the default locale when a new Strapi project is created, but another locale can be set as the default locale in the admin panel.

For instance, by default, a GET request to /api/restaurants will return the same response as a request to /api/restaurants?locale=en.

The following table lists the new possible use cases added by i18n to the REST API and gives syntax examples (you can click on requests to jump to the corresponding section with more details):

For collection types
For single types

Use case	Syntax example and link for more information
Get all documents in a specific locale	`GET /api/restaurants?locale=fr`
Get a specific locale version for a document	`GET /api/restaurants/abcdefghijklmno456?locale=fr`
Create a new document for the default locale	`POST /api/restaurants` + pass attributes in the request body
Create a new document for a specific locale	`POST /api/restaurants` + pass attributes and locale in the request body
Create a new, or update an existing, locale version for an existing document	`PUT /api/restaurants/abcdefghijklmno456?locale=fr` + pass attributes in the request body
Delete a specific locale version of a document	`DELETE /api/restaurants/abcdefghijklmno456?locale=fr`

Use case	Syntax example and link for more information
Get a specific locale version for a document	`GET /api/homepage?locale=fr`
Create a new, or update an existing, locale version for an existing document	`PUT /api/homepage?locale=fr` + pass attributes in the request body
Delete a specific locale version of a document	`DELETE /api/homepage?locale=fr`

`GET` Get all documents in a specific locale

Example request

GET http://localhost:1337/api/restaurants?locale=fr

Example response

{
  "data": [
    {
      "id": 5,
      "documentId": "h90lgohlzfpjf3bvan72mzll",
      "Title": "Meilleures pizzas",
      "Body": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "On déguste les meilleures pizzas de la ville à la Pizzeria Arrivederci."
            }
          ]
        }
      ],
      "createdAt": "2024-03-06T22:08:59.643Z",
      "updatedAt": "2024-03-06T22:10:21.127Z",
      "publishedAt": "2024-03-06T22:10:21.130Z",
      "locale": "fr"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  }
}

`GET` Get a document in a specific locale

To get a specific document in a given locale, add the locale parameter to the query:

Use case	Syntax format and link for more information
In a collection type	`GET /api/content-type-plural-name/document-id?locale=locale-code`
In a single type	`GET /api/content-type-singular-name?locale=locale-code`

Collection types

To get a specific document in a collection type in a given locale, add the locale parameter to the query, after the documentId:

Example request

GET /api/restaurants/lr5wju2og49bf820kj9kz8c3?locale=fr

Example response

{
  "data": [
    {
      "id": 22,
      "documentId": "lr5wju2og49bf820kj9kz8c3",
      "Name": "Biscotte Restaurant",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "Bienvenue au restaurant Biscotte! Le Restaurant Biscotte propose une cuisine à base de produits frais et de qualité, souvent locaux, biologiques lorsque cela est possible, et toujours produits par des producteurs passionnés."
            }
          ]
        }
      ],
      // …
      "locale": "fr"
    },
    // …
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 3
    }
  }
}

Single types

To get a specific single type document in a given locale, add the locale parameter to the query, after the single type name:

Example request

GET /api/homepage?locale=fr

Example response

{
  "data": {
    "id": 10,
    "documentId": "ukbpbnu8kbutpn98rsanyi50",
    "Title": "Page d'accueil",
    "Body": null,
    "createdAt": "2024-03-07T13:28:26.349Z",
    "updatedAt": "2024-03-07T13:28:26.349Z",
    "publishedAt": "2024-03-07T13:28:26.353Z",
    "locale": "fr"
  },
  "meta": {}
}

`POST` Create a new localized document for a collection type

To create a localized document from scratch, send a POST request to the Content API. Depending on whether you want to create it for the default locale or for another locale, you might need to pass the locale parameter in the request's body

Use case	Syntax format and link for more information
Create for the default locale	`POST /api/content-type-plural-name`
Create for a specific locale	`POST /api/content-type-plural-name` + pass locale in request body

For the default locale

If no locale has been passed in the request body, the document is created using the default locale for the application:

Example request

POST http://localhost:1337/api/restaurants

{
  "data": {
    "Name": "Oplato",
  }
}

Example response

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Oplato",
    "Description": null,
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:19:54.646Z",
    "publishedAt": "2024-03-06T22:19:54.649Z",
    "locale": "en"
  },
  "meta": {}
}

For a specific locale

To create a localized entry for a locale different from the default one, add the locale attribute to the body of the POST request:

Example request

POST http://localhost:1337/api/restaurants

{
  "data": {
    "Name": "She's Cake",
    "locale": "fr"
  }
}

Example response

{
  "data": {
    "id": 15,
    "documentId": "ldcmn698iams5nuaehj69j5o",
    "Name": "She's Cake",
    "Description": null,
    "createdAt": "2024-03-06T22:21:18.373Z",
    "updatedAt": "2024-03-06T22:21:18.373Z",
    "publishedAt": "2024-03-06T22:21:18.378Z",
    "locale": "en"
  },
  "meta": {}
}

`PUT` Create a new, or update an existing, locale version for an existing document

With PUT requests sent to an existing document, you can:

create another locale version of the document,
or update an existing locale version of the document.

Send the PUT request to the appropriate URL, adding the locale=your-locale-code parameter to the query URL and passing attributes in a data object in the request's body:

Use case	Syntax format and link for more information
In a collection type	`PUT /api/content-type-plural-name/document-id?locale=locale-code`
In a single type	`PUT /api/content-type-singular-name?locale=locale-code`

Caution

When creating a localization for existing localized entries, the body of the request can only accept localized fields.

Tip

The Content-Type should have the createLocalization permission enabled, otherwise the request will return a 403: Forbidden status.

Note

It is not possible to change the locale of an existing localized entry. When updating a localized entry, if you set a locale attribute in the request body it will be ignored.

In a collection type

To create a new locale for an existing document in a collection type, add the locale parameter to the query, after the documentId, and pass data to the request's body:

Example request: Creating a French locale for an existing restaurant

PUT http://localhost:1337/api/restaurants/lr5wju2og49bf820kj9kz8c3?locale=fr

{
  data: {
    "Name": "She's Cake in French",
  }
}

Example response

{
  "data": {
    "id": 19,
    "documentId": "lr5wju2og49bf820kj9kz8c3",
    "Name": "She's Cake in French",
    "Description": null,
    "createdAt": "2024-03-07T12:13:09.551Z",
    "updatedAt": "2024-03-07T12:13:09.551Z",
    "publishedAt": "2024-03-07T12:13:09.554Z",
    "locale": "fr"
  },
  "meta": {}
}

In a single type

To create a new locale for an existing single type document, add the locale parameter to the query, after the single type name, and pass data to the request's body:

Example: Create a FR locale for an existing Homepage single type

PUT http://localhost:1337/api/homepage?locale=fr

{
  "data": {
    "Title": "Page d'accueil"
  }
}

Example response

{
  "data": {
    "id": 10,
    "documentId": "ukbpbnu8kbutpn98rsanyi50",
    "Title": "Page d'accueil",
    "Body": null,
    "createdAt": "2024-03-07T13:28:26.349Z",
    "updatedAt": "2024-03-07T13:28:26.349Z",
    "publishedAt": "2024-03-07T13:28:26.353Z",
    "locale": "fr"
  },
  "meta": {}
}

`DELETE` Delete a locale version of a document

To delete a locale version of a document, send a DELETE request with the appropriate locale parameter.

DELETE requests only send a 204 HTTP status code on success and do not return any data in the response body.

In a collection type

To delete only a specific locale version of a document in a collection type, add the locale parameter to the query after the documentId:

Example request

DELETE /api/restaurants/abcdefghijklmno456?locale=fr

In a single type

To delete only a specific locale version of a single type document, add the locale parameter to the query after the single type name:

Example request

DELETE /api/homepage?locale=fr

GET Get all documents in a specific locale​

GET Get a document in a specific locale​

Collection types​

Single types​

POST Create a new localized document for a collection type​

For the default locale​

For a specific locale​

PUT Create a new, or update an existing, locale version for an existing document​

In a collection type​

In a single type​

DELETE Delete a locale version of a document​

In a collection type​

In a single type​

`GET` Get all documents in a specific locale

`GET` Get a document in a specific locale

Collection types

Single types

`POST` Create a new localized document for a collection type

For the default locale

For a specific locale

`PUT` Create a new, or update an existing, locale version for an existing document

In a collection type

In a single type

`DELETE` Delete a locale version of a document

In a collection type

In a single type