REST API:locale

国际化 (i18n) 功能 为 REST API 添加了新功能。

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

Prerequisites

要使用针对某个语言环境的 API 内容，请确保该语言环境已经是 添加到管理面板中的 Strapi。

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

locale 接口参数 可用于处理仅针对指定语言环境的文档。locale 将语言环境代码作为值（参见 可用语言环境的完整列表）。

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

提示

如果未定义 locale 参数，它将被设置为默认语言环境。en 是创建新 Strapi 项目时的默认语言环境，但管理面板中的另一个语言环境可以是 设置为默认区域设置。

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

例如，默认情况下，对 /api/restaurants 的 GET 请求将返回与对 /api/restaurants?locale=en 的请求相同的响应。

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

下表列出了 i18n 添加到 REST API 的新可能用例并给出了语法示例（你可以单击请求跳转到包含更多详细信息的相应部分）：

¥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

使用案例	语法示例 和更多信息的链接
获取特定语言环境中的所有文档	GET /api/restaurants?locale=fr
获取文档的特定语言环境版本	GET /api/restaurants/abcdefghijklmno456?locale=fr
为默认语言环境创建新文档	POST /api/restaurants + 在请求正文中传递属性
为特定语言环境创建新文档	POST /api/restaurants + 在请求正文中传递属性和语言环境
为现有文档创建新的或更新现有的语言环境版本	PUT /api/restaurants/abcdefghijklmno456?locale=fr + 在请求正文中传递属性
删除文档的特定语言环境版本	DELETE /api/restaurants/abcdefghijklmno456?locale=fr

For single types

使用案例	语法示例 和更多信息的链接
获取文档的特定语言环境版本	GET /api/homepage?locale=fr
为现有文档创建新的或更新现有的语言环境版本	PUT /api/homepage?locale=fr + 在请求正文中传递属性
删除文档的特定语言环境版本	DELETE /api/homepage?locale=fr

GET 获取特定语言环境中的所有文档

¥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 Get a document in a specific locale

要获取给定语言环境中的特定文档，请在查询的 locale 参数之后添加：

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

使用案例	语法格式和更多信息的链接
在集合类型中	GET /api/content-type-plural-name/document-id?locale=locale-code
在单一类型中	GET /api/content-type-singular-name?locale=locale-code

集合类型

¥Collection types

要获取给定语言环境中集合类型中的特定文档，请在查询的 documentId 之后添加 locale 参数：

¥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

要获取给定语言环境中的特定单一类型文档，请在查询的 locale 参数之后添加单一类型名称：

¥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 为集合类型创建新的本地化文档

¥POST Create a new localized document for a collection type

若要从头开始创建本地化文档，请向内容 API 发送 POST 请求。根据你是要为默认语言环境还是其他语言环境创建它，你可能需要在请求的正文中传递 locale 参数

¥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

使用案例	语法格式和更多信息的链接
为默认语言环境创建	POST /api/content-type-plural-name
为特定语言环境创建	POST /api/content-type-plural-name + 在请求正文中传递语言环境

针对默认语言环境

¥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

要为不同于默认区域设置的区域设置创建本地化条目，请将 locale 属性添加到 POST 请求的正文中：

¥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 为现有文档创建新的或更新现有的语言环境版本

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

将 PUT 请求发送到现有文档后，你可以：

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

将 PUT 请求发送到相应的 URL，将 locale=your-locale-code 参数添加到查询 URL 并在请求正文中的 data 对象中传递属性：

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

使用案例	语法格式和更多信息的链接
在集合类型中	PUT /api/content-type-plural-name/document-id?locale=locale-code
在单一类型中	PUT /api/content-type-singular-name?locale=locale-code

提醒

为现有本地化条目创建本地化时，请求正文只能接受本地化字段。

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

提示

Content-Type 应该启用 createLocalization 权限，否则请求将返回 403: Forbidden 状态。

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

注意

无法更改现有本地化条目的区域设置。更新本地化条目时，如果你在请求正文中设置 locale 属性，它将被忽略。

¥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

要为集合类型中的现有文档创建新语言环境，请在查询中添加 locale 参数（位于 documentId 之后），并将数据传递到请求的正文：

¥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

要为现有单一类型文档创建新语言环境，请在查询中添加 locale 参数（位于单一类型名称之后），并将数据传递到请求的正文：

¥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 Delete a locale version of a document

要删除文档的语言环境版本，请发送带有适当 locale 参数的 DELETE 请求。

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

DELETE 请求仅在成功时发送 204 HTTP 状态代码，并且不会在响应正文中返回任何数据。

¥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

要仅删除集合类型中文档的特定语言环境版本，请在 documentId 后的查询中添加 locale 参数：

¥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

要仅删除单一类型文档的特定语言环境版本，请在单一类型名称后的查询中添加 locale 参数：

¥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