payload/docs/configuration/localization.mdx

---
title: Localization
label: Localization
order: 50
desc: Add and maintain as many locales as you need by adding Localization to your Payload config, set options for default locale, fallbacks, fields and more.
keywords: localization, internationalization, i18n, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
---

Payload features deep field-based localization support. Maintaining as many locales as you need is easy. All
localization support is opt-in by default. To do so, follow the two steps below.

### Enabling in the Payload config

Add the `localization` property to your Payload config to enable localization project-wide. You'll need to provide a
list of all locales that you'd like to support as well as set a few other options.

**Example Payload config set up for localization:**

```ts
import { buildConfig } from 'payload/config'

export default buildConfig({
  collections: [
    // collections go here
  ],
  localization: {
    locales: ['en', 'es', 'de'],
    defaultLocale: 'en',
    fallback: true,
  },
})
```

**Example Payload config set up for localization with full locales objects:**

```ts
import { buildConfig } from 'payload/config'

export default buildConfig({
  collections: [
    // collections go here
  ],
  localization: {
    locales: [
      {
        label: 'English',
        code: 'en',
      },
      {
        label: 'Arabic',
        code: 'ar',
        // opt-in to setting default text-alignment on Input fields to rtl (right-to-left) when current locale is rtl
        rtl: true,
      },
    ],
    defaultLocale: 'en',
    fallback: true,
  },
})
```

**Example Payload config set up for localization with full locales objects (
including [internationalization](/docs/configuration/i18n) support):**

```ts
import { buildConfig } from 'payload/config'

export default buildConfig({
  collections: [
    // collections go here
  ],
  localization: {
    locales: [
      {
        label: {
          en: 'English', // English label
          nb: 'Engelsk', // Norwegian label
        },
        code: 'en',
      },
      {
        label: {
          en: 'Norwegian', // English label
          nb: 'Norsk', // Norwegian label
        },
        code: 'nb',
      },
    ],
    defaultLocale: 'en',
    fallback: true,
  },
})
```

**Here is a brief explanation of each of the options available within the `localization` property:**

**`locales`**

Array-based list of all the languages that you would like to support. This can be an array containing strings for each
language code you want your project to store and serve or objects with a `label`, a locale `code`, `rtl` (
right-to-left), and `fallbackLocale` property. The locale codes do not need to be in any specific format. It's up to you
to define how to represent your locales. Common patterns are to use two-letter ISO 639 language codes or four-letter
language and country codes (ISO 3166‑1) such as `en-US`, `en-UK`, `es-MX`, etc.

### Locale Properties:

| Option               | Description                                                                                                                    |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------|
| **`code`** \*        | Unique code to identify the language throughout the APIs for `locale` and `fallbackLocale`                                     |
| **`label`**          | A string to use for the selector when choosing a language, or an object keyed on the i18n keys for different languages in use. |
| **`rtl`**            | A boolean that when true will make the admin UI display in Right-To-Left.                                                      |
| **`fallbackLocale`** | The code for this language to fallback to when properties of a document are not present.                                       |

_\* An asterisk denotes that a property is required._

**`defaultLocale`**

Required string that matches one of the locale codes from the array provided. By default, if no locale is specified,
documents will be returned in this locale.

**`fallback`**

Boolean enabling "fallback" locale functionality. If a document is requested in a locale, but a field does not have a
localized value corresponding to the requested locale, then if this property is enabled, the document will automatically
fall back to the fallback locale value. If this property is not enabled, the value will not be populated.

### Field by field localization

Payload localization works on a **field** level—not a document level. In addition to configuring the base Payload config
to support localization, you need to specify each field that you would like to localize.

**Here is an example of how to enable localization for a field:**

```js
{
  name: 'title',
    type
:
  'text',
    // highlight-start
    localized
:
  true,
  // highlight-end
}
```

With the above configuration, the `title` field will now be saved in the database as an object of all locales instead of
a single string.

All field types with a `name` property support the `localized` property—even the more complex field types like `array`s
and `block`s.

<Banner>
  <strong>Note:</strong>
  <br />
  Enabling localization for field types that support nested fields will automatically create
  localized "sets" of all fields contained within the field. For example, if you have a page layout
  using a blocks field type, you have the choice of either localizing the full layout, by enabling
  localization on the top-level blocks field, or only certain fields within the layout.
</Banner>

<Banner type="warning">
  <strong>Important:</strong>
  <br />
  When converting an existing field to or from `localized: true` the data structure in the document
  will change for this field and so existing data for this field will be lost. Before changing the
  localization setting on fields with existing data, you may need to consider a field migration
  strategy.
</Banner>

### Retrieving localized docs

When retrieving documents, you can specify which locale you'd like to receive as well as which fallback locale should be
used.

##### REST API

REST API locale functionality relies on URL query parameters.

**`?locale=`**

Specify your desired locale by providing the `locale` query parameter directly in the endpoint URL.

**`?fallback-locale=`**

Specify fallback locale to be used by providing the `fallback-locale` query parameter. This can be provided as either a
valid locale as provided to your base Payload config, or `'null'`, `'false'`, or `'none'` to disable falling back.

**Example:**

```
fetch('https://localhost:3000/api/pages?locale=es&fallback-locale=none');
```

##### GraphQL API

In the GraphQL API, you can specify `locale` and `fallbackLocale` args to all relevant queries and mutations.

The `locale` arg will only accept valid locales, but locales will be formatted automatically as valid GraphQL enum
values (dashes or special characters will be converted to underscores, spaces will be removed, etc.). If you are curious
to see how locales are auto-formatted, you can use the [GraphQL playground](/docs/graphql/overview#graphql-playground).

The `fallbackLocale` arg will accept valid locales as well as `none` to disable falling back.

**Example:**

```graphql
query {
    Posts(locale: de, fallbackLocale: none) {
        docs {
            title
        }
    }
}
```

<Banner>
  In GraphQL, specifying the locale at the top level of a query will automatically apply it
  throughout all nested relationship fields. You can override this behavior by re-specifying locale
  arguments in nested related document queries.
</Banner>

##### Local API

You can specify `locale` as well as `fallbackLocale` within the Local API as well as properties on the `options`
argument. The `locale` property will accept any valid locale, and the `fallbackLocale` property will accept any valid
locale as well as `'null'`, `'false'`, `false`, and `'none'`.

**Example:**

```js
const posts = await payload.find({
  collection: 'posts',
  locale: 'es',
  fallbackLocale: false,
})
```

<Banner type="alert">
  <strong>Tip:</strong>
  <br />
  The REST and Local APIs can return all localization data in one request by passing 'all' or '*' as
  the <strong>locale</strong> parameter. The response will be structured so that field values come
  back as the full objects keyed for each locale instead of the single, translated value.
</Banner>