Skip to main content

文档服务 API：使用 locale 参数

🌐 Document Service API: Using the locale parameter

默认情况下，Document Service API 返回文档的默认语言版本（默认为'en'，即英语版本，除非应用已设置了其他默认语言，详见国际化（i18n）功能）。本页面描述了如何使用 locale 参数仅获取或操作特定语言的数据。

🌐 By default the Document Service API returns the default locale version of documents (which is 'en', i.e. the English version, unless another default locale has been set for the application, see Internationalization (i18n) feature). This page describes how to use the locale parameter to get or manipulate data only for specific locales.

获取带有 findOne() 的本地化版本​

🌐 Get a locale version with findOne()

如果传入 locale，文档服务 API 的 findOne() 方法 将返回该语言环境的文档版本：

🌐 If a locale is passed, the findOne() method of the Document Service API returns the version of the document for this locale:

Example request
await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // draft version (default)
  locale: "fr", // as asked from the parameters
  // …
}

如果没有传递 status 参数，则默认返回 draft 版本。

🌐 If no status parameter is passed, the draft version is returned by default.

获取带有 findFirst() 的本地化版本​

🌐 Get a locale version with findFirst()

要在使用文档服务 API 查找第一个 与参数匹配的文档时返回特定区域设置：

🌐 To return a specific locale while finding the first document matching the parameters with the Document Service API:

示例请求
const document = await strapi.documents('api::article.article').findFirst({
  locale: 'fr',
});
示例响应
{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article"
  // …
}

如果没有传递 status 参数，则默认返回 draft 版本。

🌐 If no status parameter is passed, the draft version is returned by default.

使用 findMany() 获取本地化版本​

🌐 Get locale versions with findMany()

当将 locale 传递给文档服务 API 的 findMany() 方法 时，响应将返回所有具有此语言环境的文档。

🌐 When a locale is passed to the findMany() method of the Document Service API, the response will return all documents that have this locale available.

如果没有传递 status 参数，则默认返回 draft 版本。

🌐 If no status parameter is passed, the draft versions are returned by default.

Example request
// Defaults to status: draft
await strapi.documents('api::restaurant.restaurant').findMany({ locale: 'fr' });
Example response
[
  {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: 'Restaurant Biscotte',
    publishedAt: null,
    locale: 'fr',
    // …
  },
  // …
];
解释:

给定以下 4 个具有不同语言环境的文档：

🌐 Given the following 4 documents that have various locales:

  • 文件A：
    • en
    • fr
    • it
  • 文件 B：
    • en
    • it
  • 文件 C：
    • fr
  • 文件 D：
    • fr
    • it

findMany({ locale: 'fr' }) 只会返回那些有 ‘fr’ 语言版本的文档的草稿版本，即文档 A、C 和 D。

create() 为一个区域创建文档​

🌐 create() a document for a locale

要为特定区域创建文档，请将 locale 作为参数传递给文档服务 API 的 create 方法:

🌐 To create a document for specific locale, pass the locale as a parameter to the create method of the Document Service API:

创建文档的西班牙语草稿版本
await strapi.documents('api::restaurant.restaurant').create({
  locale: 'es' // if not passed, the draft is created for the default locale
  data: { name: 'Restaurante B' }
})
Example response
{
  documentId: "pw2s0nh5ub1zmnk0d80vgqrh",
  name: "Restaurante B",
  publishedAt: null,
  locale: "es"
  // …
}

update() 本地化版本​

🌐 update() a locale version

要仅更新文档的特定语言版本，请将 locale 参数传递给文档服务 API 的 update() 方法:

🌐 To update only a specific locale version of a document, pass the locale parameter to the update() method of the Document Service API:

更新文档的西班牙语区域设置
await strapi.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'es',
  data: { name: 'Nuevo nombre del restaurante' },
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Nuevo nombre del restaurante",
  locale: "es",
  publishedAt: null,
  // …
}

delete() 语言区域版本​

🌐 delete() locale versions

使用 Document Service API 的 delete() 方法 的 locale 参数仅删除某些语言版本。除非传入特定的 status 参数，否则这将删除草稿和已发布版本。

🌐 Use the locale parameter with the delete() method of the Document Service API to delete only some locales. Unless a specific status parameter is passed, this deletes both the draft and published versions.

删除一个语言版本​

🌐 Delete a locale version

要删除文档的特定语言环境版本：

🌐 To delete a specific locale version of a document:

删除文档的西班牙语区域设置
await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
  locale: 'es',
});

删除所有语言版本​

🌐 Delete all locale versions

* 通配符由 locale 参数支持，可用于删除文档的所有语言版本：

🌐 The * wildcard is supported by the locale parameter and can be used to delete all locale versions of a document:

Example request
await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
  locale: '*',
}); // for all existing locales
示例响应
{
  "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
  // All of the deleted locale versions are returned
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

publish() 语言版本​

🌐 publish() locale versions

要使用文档服务 API 的 publish() 方法 仅发布文档的特定语言版本，请将 locale 作为参数传递：

🌐 To publish only specific locale versions of a document with the publish() method of the Document Service API, pass locale as a parameter:

发布本地化版本​

🌐 Publish a locale version

要发布文档的特定语言环境版本：

🌐 To publish a specific locale version of a document:

发布文件的法语版本
await strapi.documents('api::restaurant.restaurant').publish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: '2024-03-14T18:38:05.674Z',
      locale: 'fr',
      // …
    },
  ];
}

发布所有语言版本​

🌐 Publish all locale versions

* 通配符由 locale 参数支持，用于发布文档的所有语言版本：

🌐 The * wildcard is supported by the locale parameter to publish all locale versions of a document:

发布文档的所有语言版本
await strapi
  .documents('api::restaurant.restaurant')
  .publish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  "versions": [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "en"
      // …
    },
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "es"
      // …
    },
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "fr"
      // …
    }
  ]
}

unpublish() 语言版本​

🌐 unpublish() locale versions

要使用文档服务 API 的 unpublish() 方法 仅发布文档的特定语言版本，请将 locale 作为参数传递：

🌐 To publish only specific locale versions of a document with the unpublish() method of the Document Service API, pass locale as a parameter:

取消发布本地版本​

🌐 Unpublish a locale version

要取消发布文档的特定语言版本，请将 locale 作为参数传递给 unpublish()：

🌐 To unpublish a specific locale version of a document, pass the locale as a parameter to unpublish():

取消发布文档的法语版本
await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
Example response
{
  versions: 1;
}

取消发布所有语言版本​

🌐 Unpublish all locale versions

* 通配符由 locale 参数支持，用于取消发布文档的所有语言版本：

🌐 The * wildcard is supported by the locale parameter, to unpublish all locale versions of a document:

取消发布文档的所有本地化版本
await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  versions: 3;
}
示例请求
const document = await strapi.documents('api::article.article').unpublish({
  documentId: 'cjld2cjxh0000qzrmn831i7rn',
  fields: ['title'],
});
示例响应
{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  // All of the unpublished locale versions are returned
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

discardDraft() 用于本地化版本​

🌐 discardDraft() for locale versions

要仅丢弃某些语言版本文档的草稿数据，使用文档服务 API 的 discardDraft() 方法，传递 locale 作为参数：

🌐 To discard draft data only for some locales versions of a document with the discardDraft() method of the Document Service API, pass locale as a parameter:

丢弃本地化版本的草稿​

🌐 Discard draft for a locale version

要放弃文档特定语言版本的草稿数据，并用该语言版本的已发布数据覆盖它，请将 locale 作为参数传递给 discardDraft()：

🌐 To discard draft data for a specific locale version of a document and override it with data from the published version for this locale, pass the locale as a parameter to discardDraft():

放弃文档法语本地化版本的草稿
await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
  ];
}

丢弃所有语言版本的草稿​

🌐 Discard drafts for all locale versions

* 通配符由 locale 参数支持，用于丢弃文档的所有区域版本的草稿数据，并用已发布版本的数据替换它们：

🌐 The * wildcard is supported by the locale parameter, to discard draft data for all locale versions of a document and replace them with the data from the published versions:

丢弃文档的所有语言版本的草稿
await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Biscotte Restaurant',
      publishedAt: null,
      locale: 'en',
      // …
    },
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Biscotte Restaurante',
      publishedAt: null,
      locale: 'es',
      // …
    },
  ];
}

count() 个本地化文档​

🌐 count() documents for a locale

要统计特定语言环境的文档，请将 locale 与其他参数一起传递给文档服务 API 的 count() 方法。

🌐 To count documents for a specific locale, pass the locale along with other parameters to the count() method of the Document Service API.

如果没有传递 status 参数，则统计草稿文档（即该语言环境下可用文档的总数，因为即使已发布的文档也会被计为有草稿版本）：

🌐 If no status parameter is passed, draft documents are counted (which is the total of available documents for the locale since even published documents are counted as having a draft version):

// Count number of published documents in French
strapi.documents('api::restaurant.restaurant').count({ locale: 'fr' });