Document Service API: Using the locale parameter#
The locale parameter in the Document Service API lets you query, create, update, delete, publish, and unpublish documents for specific language versions using methods like findOne(), findMany(), update(), and delete().
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() {#find-one}#
await strapi.documents('api::restaurant.restaurant').findOne({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
locale: 'fr',
});
{
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() {#find-first}#
const document = await strapi.documents('api::article.article').findFirst({
locale: 'fr',
});
{
"documentId": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article"
// …
}
If no status parameter is passed, the draft version is returned by default.
Get locale versions with findMany() {#find-many}#
If no status parameter is passed, the draft versions are returned by default.
// Defaults to status: draft
await strapi.documents('api::restaurant.restaurant').findMany({ locale: 'fr' });
[
{
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 {#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' }
})
{
documentId: "pw2s0nh5ub1zmnk0d80vgqrh",
name: "Restaurante B",
publishedAt: null,
locale: "es"
// …
}
update() a locale version {#update}#
await strapi.documents('api::restaurant.restaurant').update({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
locale: 'es',
data: { name: 'Nuevo nombre del restaurante' },
});
{
documentId: "a1b2c3d4e5f6g7h8i9j0klm",
name: "Nuevo nombre del restaurante",
locale: "es",
publishedAt: null,
// …
}
delete() locale versions {#delete}#
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#
await strapi.documents('api::restaurant.restaurant').delete({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
locale: 'es',
});
Delete all locale versions#
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() locale versions {#publish}#
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#
await strapi.documents('api::restaurant.restaurant').publish({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
locale: 'fr',
});
{
versions: [
{
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
name: 'Restaurant Biscotte',
publishedAt: '2024-03-14T18:38:05.674Z',
locale: 'fr',
// …
},
]
}
Publish all locale versions#
await strapi
.documents('api::restaurant.restaurant')
.publish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
{
"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 {#unpublish}#
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#
await strapi
.documents('api::restaurant.restaurant')
.unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
{
versions: 1
}
Unpublish all locale versions#
await strapi
.documents('api::restaurant.restaurant')
.unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
{
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() for locale versions {#discard-draft}#
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#
await strapi
.documents('api::restaurant.restaurant')
.discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
{
versions: [
{
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
name: 'Restaurant Biscotte',
publishedAt: null,
locale: 'fr',
// …
},
]
}
Discard drafts for all locale versions#
await strapi
.documents('api::restaurant.restaurant')
.discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
{
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 {#count}#
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' });