REST API：locale

🌐 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 API 参数 可用于仅处理特定语言环境的文档。locale 以语言环境代码作为值（见 full list of available locales）。

Tip

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

🌐 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?locale=fr
+ 在请求正文中传递属性 || 为现有文档创建新的或更新现有的语言环境版本 | 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 query. | 使用案例 | 语法格式及更多信息链接 || --- | --- || 为默认语言创建 | POST /api/content-type-plural-name || 为特定语言创建 | POST /api/content-type-plural-name?locale=fr |

对于默认区域设置

🌐 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

要为与默认语言不同的语言环境创建本地化条目，请在 POST 请求的查询 URL 中添加 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:

Example request

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

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

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

• 创建文档的另一个语言环境版本，
• 或更新文档的现有语言环境版本。

将 PUT 请求发送到相应的 URL，在查询 URL 中添加 locale=your-locale-code 参数，并在请求的主体中通过 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 |

Caution

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

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

Tip

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

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

Note

无法更改现有本地化条目的区域设置。更新本地化条目时，如果在请求正文中设置 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.

在集合类型 {#rest-put-collection-type} 中

🌐 In a collection type

要为集合类型中的现有文档创建新区域，本地化，请在 documentId 之后将 locale 参数添加到查询中，并将数据传递到请求的主体中：

🌐 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"
  }
}

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:

示例：为现有的首页单一类型创建一个法语本地化版本

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 状态码，并且不会在响应体中返回任何数据。

在集合类型 {#rest-delete-collection-type} 中

🌐 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