Skip to main content

文档服务 API：使用 locale 参数

¥Document Service API: Using the locale parameter

默认情况下，文档服务 API 返回文档的默认语言环境版本（即 'en'，即英语版本，除非为应用设置了其他默认语言环境，请参阅 用户指南）。本页介绍如何使用 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 User Guide). 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:

Example request


const document = await strapi.documents('api::article.article').findFirst({


  locale: 'fr',
});
Example response
{
  "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',
    // …
  },
  // …
];
Explanation:

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

¥Given the following 4 documents that have various locales:

  • 文档 A：

    ¥Document A:

    • en

    • fr

    • it

  • 文档 B：

    ¥Document B:

    • en

    • it

  • 文档 C：

    ¥Document C:

    • fr

  • 文档 D：

    ¥Document D:

    • fr

    • it

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

¥findMany({ locale: 'fr' }) would only return the draft version of the documents that have a ‘fr’ locale version, that is documents A, C, and 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:

Create the Spanish draft locale of a document
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:

Update the Spanish locale of a document
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

将 locale 参数与文档服务 API 的 delete() 方法 一起使用以仅删除某些语言环境。除非传递了特定的 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:

Delete the Spanish locale 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
Example response
{
  "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:

Publish the French locale of 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:

Publish all locales 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():

Unpublish the French locale version of document
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:

Unpublish all locale versions of a document
await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  versions: 3;
}
Example request


const document = await strapi.documents('api::article.article').unpublish({


  documentId: 'cjld2cjxh0000qzrmn831i7rn',
  fields: ['title'],
});
Example response
{
  "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():

Discard draft for the French locale version of document
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:

Discard drafts for all locale versions of a document
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' });