国际化 i18n

有关如何使用 Strapi Content API 和国际化 (i18n) 可选插件的说明

国际化 (i18n) 插件允许 Strapi 用户创建、管理和分发不同语言的本地化内容，这些语言称为“语言环境”。有关国际化概念的更多信息，请参阅 W3C 定义。

i18n 插件：

允许管理面板用户创建其内容的多个本地化版本（请参阅用户指南)
允许开发人员通过根据受众的国家/语言获取和使用正确的内容来构建本地化项目。

i18n 插件不会自动翻译用户的内容，也不会根据语言特性调整管理界面（例如以从右到左的格式显示管理面板）。

安装

国际化插件默认安装在所有运行 3.6.0 或更高版本的 Strapi 应用程序上。对于较低版本，需要迁移（参见更新 Strapi 版本），以及手动安装插件。

插件可以这样安装：

从 Marketplace，
或使用终端，运行以下命令之一：

bash

yarn

bash

yarn strapi install i18n

默认语言环境的配置

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

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

与 REST API 结合使用

i18n 插件为 REST API 添加了新功能：

新的 locale 参数，用于仅为指定语言环境获取内容
能够创建本地化条目，无论是从头开始还是为现有本地化条目

使用 `locale` 参数获取本地化条目

locale API 参数可用于仅为指定语言环境获取条目。它以语言环境代码作为值（请参阅可用语言环境的完整列表)。

要获取语言环境的内容，请确保它已添加到管理面板中的 Strapi。

GET 请求的格式如下：

GET /api/{content-type}?locale={locale-code}

使用 all 作为区域代码的值，例如 http://localhost:1337/api/restaurants?locale=all，以获取已在管理面板中配置的所有区域设置的条目。

如果未定义 locale 参数，它将被设置为默认区域设置。安装 i18n 插件时，en 是默认区域设置，因此默认情况下，对 http://localhost:1337/api/restaurants 的 GET 请求将返回与对 http://localhost:1337/api/restaurants?locale=en 的请求相同的响应。

可以在管理面板中将另一个区域设置设置为默认区域设置。

安装 i18n 插件后，对请求的响应可以包含特定于国际化的字段：

locale（字符串）字段始终包含在内，它是内容条目的语言环境代码。
如果有特别要求，可以通过将 ?populate=localizations 附加到 URL 来包含 localizations（对象）（请参阅关系人口文档。它包括一个带有对象列表的 data 数组，每个对象都包括本地化的 id 和 attributes。

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

json

{
  "data": [
    {
      "id": 4,
      "attributes": {
        "name": "Can Alegria",
        "description": "description in French",
        "locale": "fr",
        "createdAt": "2021-10-28T15:24:42.129Z",
        "publishedAt": "2021-10-28T15:24:42.129Z"
      }
    },
    {
      "id": 8,
      "attributes": {
        "name": "She's Cake",
        "description": "description in French",
        "locale": "fr",
        "createdAt": "2021-10-28T16:17:42.129Z",
        "publishedAt": "2021-10-28T16:18:24.126Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 2,
      "total": 2
    }
  }
}

在上述示例响应中：

带有“id”：4 的餐厅是现有带有“id”：3 的餐厅的法语（“locale”："fr"`）本地化版本（为默认的“en”语言环境创建）。
带有“id”："8"` 的餐厅是使用 API 从头创建的，并在请求正文中传递了“locale：fr”（请参阅创建新的本地化条目）。

创建新的本地化条目

要从头创建本地化条目，请向 Content API 发送 POST 请求。

如果请求正文中未传递任何语言环境，则使用应用程序的默认语言环境创建条目：

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

Request

json

{
  "data": {
    "name": "Oplato",
    "description": "description in English"
  }
}

Response

json

{
  "data": {
    "id": 3,
    "attributes": {
      "name": "Oplato",
      "description": "description in English",
      "createdAt": "2021-10-28T16:57:26.352Z",
      "updatedAt": "2021-10-28T16:57:26.352Z",
      "publishedAt": "2021-10-28T16:57:26.345Z",
      "locale": "en"
    }
  },
  "meta": {}
}

要为不同于默认语言环境创建本地化条目，请将“locale”属性添加到 POST 请求的正文中：

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

Request

json

{
  "data": {
    "name": "She's Cake",
    "description": "description in French",
    "locale": "fr"
  }
}

Response

json

{
  "data": {
    "id": 8,
    "attributes": {
      "name": "She's Cake",
      "description": "description in French",
      "createdAt": "2021-10-28T17:01:47.089Z",
      "updatedAt": "2021-10-28T17:01:47.089Z",
      "publishedAt": "2021-10-28T17:01:47.082Z",
      "locale": "fr"
    }
  },
  "meta": {}
}

为现有条目创建本地化

要为现有本地化条目创建另一个本地化，请根据内容类型向相应的 URL 发送 POST 请求：

Content-Type	请求 URL 格式
集合类型	`POST /api/{content-type}/:id/localizations`
单一类型	`POST /api/{content-type}/localizations`

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

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

为集合类型创建本地化

向集合类型发送 POST 请求时，Strapi 将：

使用 id 作为非本地化字段的基本条目，并将其复制到新条目中
然后为给定的语言环境创建新条目并将其与基本条目链接。

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

Request

json

{
  "locale": "en",
  "name": "She's Cake",
  "description": "description in English"
}

此请求：

在“en”中创建一个新条目
将创建的条目与“restaurant:8”链接（它们将共享相同的“localizations”对象）
将“restaurant:8”中的每个非本地化字段复制到新条目中，并保留请求正文中的本地化字段

Response

json

{
  "id": 9,
  "name": "She's Cake",
  "description": "description in English",
  "createdAt": "2021-10-29T08:39:29.709Z",
  "updatedAt": "2021-10-29T08:39:29.709Z",
  "publishedAt": null,
  "locale": "en",
  "localizations": [
    {
      "id": 8,
      "name": "She's Cake",
      "description": "description in French",
      "createdAt": "2021-10-28T16:57:26.352Z",
      "updatedAt": "2021-10-29T08:38:04.106Z",
      "publishedAt": "2021-10-28T16:57:26.345Z",
      "locale": "fr"
    }
  ]
}

为单一类型创建本地化

POST http://localhost:1337/api/homepage/localizations

Request

json

{
  "title": "Bienvenue sur FoodAdvisor !",
  "locale": "fr"
}

Response

json

{
  "id": 2,
  "title": "Bienvenue sur FoodAdvisor!",
  "locale": "fr",
  // ...
  "localizations": [
    {
      "id": 1,
      "locale": "en"
      // ...
    }
  ]
}

更新条目

要更新现有的本地化条目，请根据内容类型向相应的 URL 发送 PUT 请求：

Content-Type	请求 URL 格式
集合类型	`PUT /api/{localized-content-type}/:id`
单一类型	`PUT /api/{localized-content-type}/?locale={locale}`

更新现有本地化条目的本地化时，PUT 请求的正文只能接受本地化字段。

无法更改现有本地化条目的语言环境。更新本地化条目时，如果您在请求正文中设置了 locale 属性，它将被忽略。

与 GraphQL 插件一起使用

i18n 插件为 GraphQL 插件添加了新功能：

locale 和 localizations 字段已添加到 GraphQL 架构中。
GraphQL 查询 API 可用于：
使用 locale 参数查询针对集合类型和单一类型
使用变异创建新的本地化针对集合类型和单一类型
更新和删除针对单一类型使用变异的本地化

使用 GraphQL 获取本地化条目

查询可以使用locale 参数仅用于获取指定语言环境的条目。

要获取所有语言环境的条目，请在查询中使用 locale: "all"。

获取集合类型

graphql

Request

graphql

query {
  restaurants(locale: "en") {
    data {
      id
      attributes {
        name
        locale
        localizations {
          data {
            id
            attributes {
              name
              description
            }
          }
        }
      }
    }
  }
}

获取单一类型

graphql

Example query

graphql

query {
  homepage(locale: "en") {
    data {
      id
      attributes {
        title
      }
    }
  }
}

使用 GraphQL 创建新的本地化条目

可以在突变的 data 对象中传递 locale 字段，以创建此特定语言环境的本地化条目（有关更多信息，请参阅使用 GraphQL 插件创建新条目）。

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

graphql

突变示例

graphql

mutation {
  createRestaurantLocalization(
    id: 8
    locale: "en"
    data: { name: "She's Cake", description: "description in english" }
  ) {
    data {
      id
      attributes {
        name
        description
        locale
        localizations {
          data {
            attributes {
              locale
              description
            }
          }
        }
      }
    }
  }
}

为单一类型创建新的本地化

graphql

突变示例

graphql

mutation {
  createHomepageLocalization(locale: "fr", data: { title: "Bienvenue sur FoodAdvisor !" }) {
    data {
      id
      attributes {
        locale
        title
      }
    }
  }
}

使用 GraphQL 更新本地化单一类型

可以在突变中传递 locale 参数来更新给定语言环境的内容（有关更多信息，请参阅使用 GraphQL 插件更新现有条目）。

目前，无法更改现有本地化条目的语言环境。如果您在突变的 data 对象中设置 locale 字段，它将被忽略。

graphql

突变示例

graphql

mutation {
  updateHomepage(locale: "fr", data: { title: "Bienvenue sur l'annuaire FoodAdvisor !" }) {
    data {
      id
      attributes {
        title
      }
    }
  }
}

使用 GraphQL 删除单一类型的本地化

在变更中传递“locale”参数以删除单一类型的特定本地化：

graphql

突变示例

graphql

mutation {
  deleteHomepage(locale: "fr") {
    data {
      id
      attributes {
        title
      }
    }
  }
}

响应返回刚刚被删除的条目。

安装

默认语言环境的配置

与 REST API 结合使用

使用 locale 参数获取本地化条目

创建新的本地化条目

为现有条目创建本地化

为集合类型创建本地化

为单一类型创建本地化

更新条目

与 GraphQL 插件一起使用

使用 GraphQL 获取本地化条目

获取集合类型

获取单一类型

使用 GraphQL 创建新的本地化条目

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

为单一类型创建新的本地化

使用 GraphQL 更新本地化单一类型

使用 GraphQL 删除单一类型的本地化

使用 `locale` 参数获取本地化条目