106 lines
3.7 KiB
Plaintext
106 lines
3.7 KiB
Plaintext
---
|
||
title: Localization
|
||
label: Localization
|
||
order: 50
|
||
---
|
||
|
||
Payload features deep field-based localization support. Maintaining as many locales as you need is easy. All localization support is opt-in by default.
|
||
|
||
## Enabling localization
|
||
|
||
To opt-in, follow the two steps below.
|
||
|
||
#### Step 1 - 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:**
|
||
|
||
```js
|
||
{
|
||
serverURL: 'http://localhost:3000',
|
||
collections: [
|
||
... // collections go here
|
||
],
|
||
localization: {
|
||
locales: [
|
||
'en',
|
||
'es',
|
||
'de',
|
||
],
|
||
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 locales that you would like to support. These strings 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.
|
||
|
||
##### `defaultLocale`
|
||
|
||
Required string that matches one of the locales 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.
|
||
|
||
#### Step 2 - field by field localization settings
|
||
|
||
Payload localization works on a **field** level—not a doocument level. In addition to configuring the base Payload config to support localization, each field that you would like to localize needs to be configured appropriately.
|
||
|
||
All field types with a `name` property support the `localized` property—even the more complex field types like `array`s and `block`s.
|
||
|
||
**Here is an example of how to enable localization for a field:**
|
||
|
||
```js
|
||
{
|
||
name: 'title',
|
||
label: 'Page 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.
|
||
|
||
<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>
|
||
|
||
### 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 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:**
|
||
|
||
```
|
||
https://localhost:3000/api/pages?locale=es&fallback-locale=none
|
||
```
|
||
|
||
##### GraphQL API
|
||
|
||
Talk about how to retrieve localized docs in GraphQL.
|
||
|
||
##### Local API
|
||
|
||
Talk about how to retrieve localized docs in the local API.
|