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

GETstrapi.documents().findOne()

Pass a locale to findOne() to get the version of the document for that locale.

GETstrapi.documents().findOne()
await strapi.documents('api::restaurant.restaurant').findOne({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
locale: 'fr',
});
200 OK
{
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()​

GETstrapi.documents().findFirst()

Pass a locale to findFirst() to return documents matching that locale.

GETstrapi.documents().findFirst()
const document = await strapi.documents('api::article.article').findFirst({
locale: 'fr',
});
200 OK
{
"documentId": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article"
// …
}

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

Get locale versions with findMany()​

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

GETstrapi.documents().findMany()

Pass a locale to findMany() to return all documents that have this locale available.

GETstrapi.documents().findMany()
// Defaults to status: draft
await strapi.documents('api::restaurant.restaurant').findMany({ locale: 'fr' });
200 OK
[
{
  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​

POSTstrapi.documents().create()

Pass a locale to create() to create the document for that specific locale.

POSTstrapi.documents().create()
await strapi.documents('api::restaurant.restaurant').create({
locale: 'es' // if not passed, the draft is created for the default locale
data: { name: 'Restaurante B' }
})
200 OK
{
documentId: "pw2s0nh5ub1zmnk0d80vgqrh",
name: "Restaurante B",
publishedAt: null,
locale: "es"
// …
}

update() a locale version​

PUTstrapi.documents().update()

Pass a locale to update() to update only that specific locale version of a document.

PUTstrapi.documents().update()
await strapi.documents('api::restaurant.restaurant').update({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
locale: 'es',
data: { name: 'Nuevo nombre del restaurante' },
});
200 OK
{
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​

DELstrapi.documents().delete()

Pass a locale to delete() to delete only that specific locale version of a document.

DELstrapi.documents().delete()
await strapi.documents('api::restaurant.restaurant').delete({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
locale: 'es',
});

Delete all locale versions​

DELstrapi.documents().delete()

Use the * wildcard with the locale parameter to delete all locale versions of a document.

DELstrapi.documents().delete()
await strapi.documents('api::restaurant.restaurant').delete({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
locale: '*',
}); // for all existing locales
200 OK
{
"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​

POSTstrapi.documents().publish()

Pass a locale to publish() to publish only that specific locale version of a document.

POSTstrapi.documents().publish()
await strapi.documents('api::restaurant.restaurant').publish({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
locale: 'fr',
});
200 OK
{
versions: [
  {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: 'Restaurant Biscotte',
    publishedAt: '2024-03-14T18:38:05.674Z',
    locale: 'fr',
    // …
  },
]
}

Publish all locale versions​

POSTstrapi.documents().publish()

Use the * wildcard with the locale parameter to publish all locale versions of a document.

POSTstrapi.documents().publish()
await strapi
.documents('api::restaurant.restaurant')
.publish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
200 OK
{
"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​

DELstrapi.documents().unpublish()

Pass a locale to unpublish() to unpublish only that specific locale version of a document.

DELstrapi.documents().unpublish()
await strapi
.documents('api::restaurant.restaurant')
.unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
200 OK
{
versions: 1
}

Unpublish all locale versions​

DELstrapi.documents().unpublish()

Use the * wildcard with the locale parameter to unpublish all locale versions of a document.

DELstrapi.documents().unpublish()
await strapi
.documents('api::restaurant.restaurant')
.unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
200 OK
{
versions: 3
}
DELstrapi.documents().unpublish()

Unpublish a document while selecting specific fields to return.

DELstrapi.documents().unpublish()
const document = await strapi.documents('api::article.article').unpublish({
documentId: 'cjld2cjxh0000qzrmn831i7rn',
fields: ['title'],
});
200 OK
{
"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​

DELstrapi.documents().discardDraft()

Pass a locale to discardDraft() to discard draft data for that specific locale version.

DELstrapi.documents().discardDraft()
await strapi
.documents('api::restaurant.restaurant')
.discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
200 OK
{
versions: [
  {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: 'Restaurant Biscotte',
    publishedAt: null,
    locale: 'fr',
    // …
  },
]
}

Discard drafts for all locale versions​

DELstrapi.documents().discardDraft()

Use the * wildcard with the locale parameter to discard drafts for all locale versions of a document.

DELstrapi.documents().discardDraft()
await strapi
.documents('api::restaurant.restaurant')
.discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
200 OK
{
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' });
On this page
Contribute to this page