Localization

Localization is one of the most important features of a modern CMS. It allows you to manage content in multiple languages, then serve it to your users based on their requested language. This is similar to I18n, but instead of managing translations for your application's interface, you are managing translations for the data itself.

With Localization, you can begin to serve personalized content to your users based on their specific language preferences, such as a multilingual website or multi-site application. There are no limits to the number of locales you can add to your Payload project.

To configure Localization, use the localization key in your Payload Config:

1import { buildConfig } from 'payload'
2
3export default buildConfig({
4  // ...
5  localization: { 
6    // ...
7  },
8})

Config Options

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.

To configure locales, use the localization.locales property in your Payload Config:

1import { buildConfig } from 'payload'
2
3export default buildConfig({
4  // ...
5  localization: {
6    locales: ['en', 'es', 'de'] // required
7    defaultLocale: 'en', // required
8  },
9})

You can also define locales using full configuration objects:

1import { buildConfig } from 'payload'
2
3export 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', // required
  fallback: true, // defaults to true
},
24})

The following options are available:

Option	Description
`locales`	Array of all the languages that you would like to support. More details
`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 unless a fallback is explicitly provided in the request. True by default.

Locales

The locales array is a list of all the languages that you would like to support. This can be strings for each language code, or full configuration objects for more advanced options.

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 Object

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.

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:

1{
2  name: 'title',
3  type: 'text',
4  localized: true,
5}

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 arrays and blocks.

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:

1fetch('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.

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

Example:

1query {
Posts(locale: de, fallbackLocale: none) {
  docs {
    title
  }
}
7}

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:

1const posts = await payload.find({
2  collection: 'posts',
3  locale: 'es',
4  fallbackLocale: false,
5})

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Localization

Config Options

Locales

Locale Object

Field Localization

Retrieving Localized Docs

REST API

GraphQL API

Local API

Environment Variables

Related Help Topics