import QsIntroFull from '/docs/snippets/qs-intro-full.md'
import QsForQueryBody from '/docs/snippets/qs-for-query-body.md'
import QsForQueryTitle from '/docs/snippets/qs-for-query-title.md'

REST API: locale#

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

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 ).

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):

GET Get all documents in a specific locale {#rest-get-all}#

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

{
  "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 {#rest-get}#

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

Collection types {#get-one-collection-type}#

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

GET /api/restaurants/lr5wju2og49bf820kj9kz8c3?locale=fr

{
  "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 {#get-one-single-type}#

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

GET /api/homepage?locale=fr

{
  "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 {#rest-create}#

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 query.

For the default locale {#rest-create-default-locale}#

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

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

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

{
  "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 {#rest-create-specific-locale}#

To create a localized entry for a locale different from the default one, add the locale parameter to the query URL of the POST request:

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

{
  "data": {
    "Name": "She's Cake"
  }
}

{
  "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": "fr"
  },
  "meta": {}
}

PUT Create a new, or update an existing, locale version for an existing document {#rest-update}#

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:

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

In a collection type {#rest-put-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:

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

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

{
  "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 {#rest-put-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:

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

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

{
  "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 {#rest-delete}#

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 {#rest-delete-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:

DELETE /api/restaurants/abcdefghijklmno456?locale=fr

In a single type {#rest-delete-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:

DELETE /api/homepage?locale=fr