Document Service API: Using the locale parameter

Page summary:

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

strapi.documents().findOne()

Get a locale version with findOne()

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

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

Get a locale version with findFirst()

strapi.documents().findFirst()

Get a locale version with findFirst()

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

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.

strapi.documents().findMany()

Get locale versions with findMany()

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

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

strapi.documents().create()

Create a document for a locale

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

update() a locale version

strapi.documents().update()

Update a locale version

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

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

strapi.documents().delete()

Delete a locale version

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

Delete all locale versions

strapi.documents().delete()

Delete all locale versions

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

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

strapi.documents().publish()

Publish a locale version

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

Publish all locale versions

strapi.documents().publish()

Publish all locale versions

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

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

strapi.documents().unpublish()

Unpublish a locale version

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

Unpublish all locale versions

strapi.documents().unpublish()

Unpublish all locale versions

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

strapi.documents().unpublish()

Unpublish with fields selection

Unpublish a document while selecting specific fields to return.

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

strapi.documents().discardDraft()

Discard draft for a locale version

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

Discard drafts for all locale versions

strapi.documents().discardDraft()

Discard drafts for all locale versions

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

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