# Using the locale parameter with the Document Service API

> Source: https://docs.strapi.io/cms/api/document-service/locale

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](/cms/api/document-service) 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](/cms/features/internationalization)). 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}

#### GET strapi.documents().findOne() — Get a locale version with findOne()

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

**JavaScript:**
```
await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
```

**Response 200 OK:**
```json
{
  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}

#### GET strapi.documents().findFirst() — Get a locale version with findFirst()

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

**JavaScript:**
```
const document = await strapi.documents('api::article.article').findFirst({
  locale: 'fr',
});
```

**Response 200 OK:**
```json
{
  "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.

#### GET strapi.documents().findMany() — Get locale versions with findMany()

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

**JavaScript:**
```
// Defaults to status: draft
await strapi.documents('api::restaurant.restaurant').findMany({ locale: 'fr' });
```

**Response 200 OK:**
```json
[
  {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: 'Restaurant Biscotte',
    publishedAt: null,
    locale: 'fr',
    // …
  },
  // …
]
```

<details>
<summary>Explanation:</summary>

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.

</details>

## `create()` a document for a locale {#create}

#### GET strapi.documents().create() — Create a document for a locale

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

**JavaScript:**
```
await strapi.documents('api::restaurant.restaurant').create({
  locale: 'es' // if not passed, the draft is created for the default locale
  data: { name: 'Restaurante B' }
})
```

**Response 200 OK:**
```json
{
  documentId: "pw2s0nh5ub1zmnk0d80vgqrh",
  name: "Restaurante B",
  publishedAt: null,
  locale: "es"
  // …
}
```

## `update()` a locale version {#update}

#### GET strapi.documents().update() — Update a locale version

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

**JavaScript:**
```
await strapi.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'es',
  data: { name: 'Nuevo nombre del restaurante' },
});
```

**Response 200 OK:**
```json
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Nuevo nombre del restaurante",
  locale: "es",
  publishedAt: null,
  // …
}
```

## `delete()` locale versions {#delete}

Use the `locale` parameter with the [`delete()` method](/cms/api/document-service#delete) 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

#### GET strapi.documents().delete() — Delete a locale version

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

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

### Delete all locale versions

#### GET strapi.documents().delete() — Delete all locale versions

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

**JavaScript:**
```
await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
  locale: '*',
}); // for all existing locales
```

**Response 200 OK:**
```json
{
  "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](/cms/api/document-service#publish) of the Document Service API, pass `locale` as a parameter:

### Publish a locale version

#### GET strapi.documents().publish() — Publish a locale version

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

**JavaScript:**
```
await strapi.documents('api::restaurant.restaurant').publish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
```

**Response 200 OK:**
```json
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: '2024-03-14T18:38:05.674Z',
      locale: 'fr',
      // …
    },
  ]
}
```

### Publish all locale versions

#### GET strapi.documents().publish() — Publish all locale versions

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

**JavaScript:**
```
await strapi
  .documents('api::restaurant.restaurant')
  .publish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
```

**Response 200 OK:**
```json
{
  "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](/cms/api/document-service#unpublish) of the Document Service API, pass `locale` as a parameter:

### Unpublish a locale version

#### GET strapi.documents().unpublish() — Unpublish a locale version

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

**JavaScript:**
```
await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
```

**Response 200 OK:**
```json
{
  versions: 1
}
```

### Unpublish all locale versions

#### GET strapi.documents().unpublish() — Unpublish all locale versions

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

**JavaScript:**
```
await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
```

**Response 200 OK:**
```json
{
  versions: 3
}
```

#### GET strapi.documents().unpublish() — Unpublish with fields selection

Unpublish a document while selecting specific fields to return.

**JavaScript:**
```
const document = await strapi.documents('api::article.article').unpublish({
  documentId: 'cjld2cjxh0000qzrmn831i7rn',
  fields: ['title'],
});
```

**Response 200 OK:**
```json
{
  "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](/cms/api/document-service#discarddraft) of the Document Service API, pass `locale` as a parameter:

### Discard draft for a locale version

#### GET strapi.documents().discardDraft() — Discard draft for a locale version

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

**JavaScript:**
```
await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
```

**Response 200 OK:**
```json
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
  ]
}
```

### Discard drafts for all locale versions

#### GET 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.

**JavaScript:**
```
await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
```

**Response 200 OK:**
```json
{
  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](/cms/api/document-service#count) 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):

```js
// Count number of published documents in French
strapi.documents('api::restaurant.restaurant').count({ locale: 'fr' });
```