REST API：locale

页面摘要： REST API 的 locale 参数用于获取并管理特定语言的文档，默认使用应用程序的默认区域（locale）。可用它来获取、创建、更新和删除集合类型（collection types）与单类型（single types）中特定区域的文档版本。

国际化（i18n）功能 为 REST API 新增了以下能力。

WARNING

要使用某个区域的 API 内容，请确保该区域已在 管理面板（admin panel）中添加到 Strapi。

可以使用 locale API 参数 仅针对指定区域处理文档。locale 以区域代码作为值（请参阅 可用区域的完整列表）。

TIP

如果未定义 locale 参数，则会被设为默认区域。新建 Strapi 项目时，en 为默认区域，但也可以在管理面板中将其他区域 设为默认区域。例如，默认情况下，向 /api/restaurants 发起的 GET 请求将返回与向 /api/restaurants?locale=en 发起请求相同的响应。

下表列出了 i18n 为 REST API 新增的可能用例，并给出语法示例（你可点击请求跳转到对应小节查看更多详情）：

对于集合类型

| 用例 | 语法示例 及更多信息链接 | |---------|-------| | 获取特定区域中的所有文档 | GET /api/restaurants?locale=fr | | 获取文档的特定区域版本 | GET /api/restaurants/abcdefghijklmno456?locale=fr | | 为默认区域创建新文档 | POST /api/restaurants

对于单类型

| 用例 | 语法示例 及更多信息链接 | |----------------------------------------------|--------------------------------------------------| | 获取文档的特定区域版本 | GET /api/homepage?locale=fr | | 为已有文档创建新的区域版本，或更新已有的区域版本 | PUT /api/homepage?locale=fr

GET 获取特定区域中的所有文档 {#rest-get-all}

返回给定区域的所有文档。

curl 'http://localhost:1337/api/restaurants?locale=fr' \
  -H 'Authorization: Bearer <token>'

响应

{
  "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 获取特定区域中的某个文档 {#rest-get}

要获取给定区域中的特定文档，请在查询中添加 locale 参数：

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

集合类型 {#get-one-collection-type}

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

返回集合类型中给定区域的特定文档。

curl 'http://localhost:1337/api/restaurants/lr5wju2og49bf820kj9kz8c3?locale=fr' \
  -H 'Authorization: Bearer <token>'

响应

{
  "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."
          }
        ]
      }
    ],
    "createdAt": "2024-03-06T22:08:59.643Z",
    "updatedAt": "2024-03-06T22:10:21.127Z",
    "publishedAt": "2024-03-06T22:10:21.130Z",
    "locale": "fr"
  },
  "meta": {}
}

单类型 {#get-one-single-type}

要在给定区域中获取特定的单类型（single type）文档，请在单类型名称之后于查询中添加 locale 参数：

返回给定区域的特定单类型文档。

curl 'http://localhost:1337/api/homepage?locale=fr' \
  -H 'Authorization: Bearer <token>'

响应

{
  "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 为集合类型创建新的本地化文档 {#rest-create}

要从头创建一个本地化文档，请向 Content API 发送 POST 请求。根据你是想为默认区域还是为其他区域创建，你可能需要在查询中传入 locale 参数。

用例语法格式及更多信息链接
为默认区域创建POST /api/content-type-plural-name
为特定区域创建POST /api/content-type-plural-name?locale=fr
草稿与发布

启用草稿与发布后，不带 status 参数的 POST 请求会创建文档并立即发布。传入 ?status=draft 则将其创建为草稿（参见 REST API：status）。

对于默认区域 {#rest-create-default-locale}

如果请求体中未传入区域（locale），则使用该应用程序的默认区域创建文档：

使用默认区域创建新文档。

curl -X POST \
  'http://localhost:1337/api/restaurants' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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": {}
}

对于特定区域 {#rest-create-specific-locale}

要为不同于默认区域的某个区域创建本地化条目，请在 POST 请求的查询 URL 中添加 locale 参数：

为指定的区域创建新文档。

curl -X POST \
  'http://localhost:1337/api/restaurants?locale=fr' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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 为已有文档创建新的区域版本或更新已有的区域版本 {#rest-update}

向已有文档发送 PUT 请求，你可以：

  • 为文档创建另一个区域版本，
  • 或更新文档已有的区域版本。

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

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

为已有的本地化条目创建本地化时，请求体只能接受本地化字段。

TIP

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

NOTE

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

草稿与发布

启用草稿与发布后，不带 status 参数的 PUT 请求会立即发布更改。传入 ?status=draft 仅更新草稿（参见 REST API：status）。这同样适用于单一类型，其中 PUT 单一类型路径 会发布更改，除非你传入 ?status=draft。

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

要为集合类型中已有的文档创建新的区域，请在 documentId 之后于查询中添加 locale 参数，并向请求体传入数据：

为已有的餐馆创建法语区域，若其已存在则更新。

curl -X PUT \
  'http://localhost:1337/api/restaurants/lr5wju2og49bf820kj9kz8c3?locale=fr' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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": {}
}

在单类型中 {#rest-put-single-type}

要为已有的单类型文档创建新的区域，请在单类型名称之后于查询中添加 locale 参数，并向请求体传入数据：

为已有的 Homepage 单类型创建法语区域，若其已存在则更新。

curl -X PUT \
  'http://localhost:1337/api/homepage?locale=fr' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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 删除文档的某个区域版本 {#rest-delete}

要删除文档的某个区域版本，请发送带有相应 locale 参数的 DELETE 请求。

DELETE 请求在成功时仅返回 204 HTTP 状态码，且响应体中不返回任何数据。

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

要仅删除集合类型中某个文档的特定区域版本，请在 documentId 之后于查询中添加 locale 参数：

删除集合类型中某个文档的特定区域版本。

curl -X DELETE \
  'http://localhost:1337/api/restaurants/abcdefghijklmno456?locale=fr' \
  -H 'Authorization: Bearer <token>'

响应

在单类型中 {#rest-delete-single-type}

要仅删除单类型文档的某个特定区域版本，请在单类型名称之后于查询中添加 locale 参数：

删除单类型文档的某个特定区域版本。

curl -X DELETE \
  'http://localhost:1337/api/homepage?locale=fr' \
  -H 'Authorization: Bearer <token>'

响应