🌍 国际化（i18n）

¥🌍 Internationalization (i18n)

国际化 (i18n) 功能允许 Strapi 用户创建、管理和分发不同语言的本地化内容，称为 "locales"。有关国际化概念的更多信息，请参阅 W3C 定义。

¥The Internationalization (i18n) feature allows Strapi users to create, manage and distribute localized content in different languages, called "locales". For more information about the concept of internationalization, please refer to the W3C definition.

i18n 功能：

¥The i18n feature:

允许管理面板用户创建其内容的多个本地化版本（参见用户指南）

¥allows admin panel users to create several localized versions of their content (see User Guide)
允许开发者根据受众的国家/语言获取和使用正确的内容来构建本地化项目。

¥allows developers to build localized projects by fetching and consuming the right content depending on the country/language of the audience.

信息

i18n 功能不会自动翻译用户的内容，也不会使管理界面适应语言特性（例如，以从右到左的格式显示管理面板）。

¥The i18n feature does not automatically translate the users' content nor adapt the admin interface to languages specificities (e.g., displaying the admin panel in Right To Left format).

注意

在 Strapi 5 中，i18n 不再是一个插件，默认情况下已安装。你仍然可以在启用 i18n 的内容类型中决定在内容类型上启用/禁用它和在字段级别启用/禁用它。

¥In Strapi 5, i18n is no longer a plugin and is installed by default. You can still decide to enable/disable it on a content-type, and enable/disable it at the field-level in an i18n-enabled content-type.
由于 i18n 是 Strapi 核心的一部分，这可能会影响某些参数发送到内容管理器的方式（参见相关的重大变更条目）。

¥Since i18n is part of the Strapi core, this might affect how some parameters are sent to the Content Manager (see the related breaking change entry).

默认区域设置的配置

¥Configuration of the default locale

可以配置 STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE 环境变量来设置你的环境的默认区域设置。用于此变量的值应为 ISO 国家/地区代码（请参阅可用语言环境的完整列表）。

¥A STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE environment variable can be configured to set the default locale for your environment. The value used for this variable should be an ISO country code (see full list of available locales).

当 Strapi 应用部署到生产环境中，并且首次为你的内容类型安装并启用 i18n 功能时，这很有用。在全新 i18n 安装中，en 被设置为默认语言环境。如果数据库不包含任何语言环境，并且环境未设置 STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE，则所有启用了本地化的内容类型的文档将自动迁移到 en 语言环境。

¥This is useful when a Strapi application is deployed in production, with the i18n feature installed and enabled for your content types the first time. On a fresh i18n installation, en is set as default locale. If the database does not contain any locale, and no STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE is set for the environment, all documents of content types that have localization enabled will be automatically migrated to the en locale.

将 `locale` 与 REST API 一起使用

¥Use locale with the REST API

国际化 (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 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
For single 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`

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

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

¥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 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": {}
}

为集合类型创建新的本地化文档

¥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": {}
}

为现有文档创建新的或更新现有的语言环境版本

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

将 `locale` 与 GraphQL API 一起使用

¥Use locale with the GraphQL API

i18n 功能为 GraphQL API 添加了新功能：

¥The i18n feature adds new features to the GraphQL API:

locale 字段已添加到 GraphQL 模式中。

¥The locale field is added to the GraphQL schema.
GraphQL 可用于：

¥GraphQL can be used:
- 使用 locale 参数查询特定语言环境的文档
  
  ¥to query documents for a specific locale with the locale argument
- 针对特定语言环境的 create、update 和 delete 文档的修改
  
  ¥for mutations to create, update, and delete documents for a specific locale

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

¥Fetch all documents in a specific locale

要获取特定语言环境的所有文档，请将 locale 参数传递给查询：

¥To fetch all documents for a specific locale, pass the locale argument to the query:

Example request

query {
  restaurants(locale: "fr") {
    documentId
    name
    locale
  }
}

Example response

{
  "data": {
    "restaurants": [
      {
        "documentId": "a1b2c3d4e5d6f7g8h9i0jkl",
        "name": "Restaurant Biscotte",
        "locale": "fr"
      },
      {
        "documentId": "m9n8o7p6q5r4s3t2u1v0wxyz",
        "name": "Pizzeria Arrivederci",
        "locale": "fr"
      },
    ]
  }
}

在特定语言环境中获取文档

¥Fetch a document in a specific locale

要获取特定语言环境的文档，请将 documentId 和 locale 参数传递给查询：

¥To fetch a documents for a specific locale, pass the documentId and the locale arguments to the query:

Example query

query Restaurant($documentId: ID!, $locale: I18NLocaleCode) {
  restaurant(documentId: "a1b2c3d4e5d6f7g8h9i0jkl", locale: "fr") {
    documentId
    name
    description
    locale
  }
}

Example response

{
  "data": {
    "restaurant": {
      "documentId": "lviw819d5htwvga8s3kovdij",
      "name": "Restaurant Biscotte",
      "description": "Bienvenue au restaurant Biscotte!",
      "locale": "fr"
    }
  }
}

创建新的本地化文档

¥Create a new localized document

可以传递 locale 字段来为特定语言环境创建本地化文档（有关使用 GraphQL 进行修改的更多信息，请参阅 GraphQL API 文档）。

¥The locale field can be passed to create a localized document for a specific locale (for more information about mutations with GraphQL, see the GraphQL API documentation).

Example: Create a new restaurant for the French locale
mutation CreateRestaurant($data: RestaurantInput!, $locale: I18NLocaleCode) {
  createRestaurant(
    data: {
      name: "Brasserie Bonjour",
      description: "Description in French goes here"
    },
    locale: "fr"
  ) {
  documentId
  name
  description
  locale
}

更新特定语言环境的文档

¥Update a document for a specific locale

可以在突变中传递 locale 参数以更新给定语言环境的文档（有关使用 GraphQL 进行突变的更多信息，请参阅 GraphQL API 文档）。

¥A locale argument can be passed in the mutation to update a document for a given locale (for more information about mutations with GraphQL, see the GraphQL API documentation).

Example: Update the description field of restaurant for the French locale
mutation UpdateRestaurant($documentId: ID!, $data: RestaurantInput!, $locale: I18NLocaleCode) {
  updateRestaurant(
    documentId: "a1b2c3d4e5d6f7g8h9i0jkl"
    data: {
      description: "New description in French"
    },
    locale: "fr"
  ) {
  documentId
  name
  description
  locale
}

删除文档的语言环境

¥Delete a locale for a document

在修改中传递 locale 参数以删除文档的特定本地化：

¥Pass the locale argument in the mutation to delete a specific localization for a document :

mutation DeleteRestaurant($documentId: ID!, $locale: I18NLocaleCode) {
  deleteRestaurant(documentId: "xzmzdo4k0z73t9i68a7yx2kk", locale: "fr") {
    documentId
  }
}

默认区域设置的配置​

将 locale 与 REST API 一起使用​

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

获取特定语言环境中的文档​

集合类型​

单一类型​

为集合类型创建新的本地化文档​

针对默认语言环境​

针对特定语言环境​

为现有文档创建新的或更新现有的语言环境版本​

在集合类型中​

在单一类型中​

删除文档的语言环境版本​

在集合类型中​

在单一类型中​

将 locale 与 GraphQL API 一起使用​

在特定语言环境中获取所有文档​

在特定语言环境中获取文档​

创建新的本地化文档​

更新特定语言环境的文档​

删除文档的语言环境​

默认区域设置的配置

将 `locale` 与 REST API 一起使用

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

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

集合类型

单一类型

为集合类型创建新的本地化文档

针对默认语言环境

针对特定语言环境

为现有文档创建新的或更新现有的语言环境版本

在集合类型中

在单一类型中

删除文档的语言环境版本

在集合类型中

在单一类型中

将 `locale` 与 GraphQL API 一起使用

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

在特定语言环境中获取文档

创建新的本地化文档

更新特定语言环境的文档

删除文档的语言环境