Skip to main content

Document Service API: Using the locale parameter

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.

Get a locale version with 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
  // …
}

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

Get a locale version with findFirst()​

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"
  // …
}

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

Get locale versions with 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.

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:

Given the following 4 documents that have various locales:

  • Document A:
    • en
    • fr
    • it
  • Document B:
    • en
    • it
  • Document C:
    • fr
  • Document D:
    • fr
    • it

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() a document for a locale​

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() a locale version​

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() locale versions​

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​

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() locale versions​

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​

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() locale versions​

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​

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​

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() for locale versions​

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​

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​

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() documents for a locale​

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

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' });