feat: accept multiple locales in fallbackLocale (#13822)

jessrynkar · JarrodMFlesch · web-flow · commit 623a1b82161a · 2025-10-16T12:02:59.000+01:00
### What? This change allows `fallbackLocale` to accept an **array of locales** in find queries and locale configuration. ```ts /** Local API **/ await payload.findByID({ id, collection, locale: 'en', fallbackLocale: ['fr', 'es'], }) /** REST API **/ await fetch(`${baseURL}/api/${collectionSlug}?locale=en&fallbackLocale[]=fr&fallbackLocale[]=es`) /** GraphQL **/ await restClient.GRAPHQL_POST({ body, query: { locale: 'en', fallbackLocale: ['fr', 'es']}, }) /** Locale Configs **/ locales: [ { code: 'en', label: 'English', fallbackLocale: ['fr', 'es'], }, ] ``` ### Why? This update is part of the planned [localization enhancements](#10705). Currently, only one fallback locale can be specified. If that locale doesn’t contain data, the query returns nothing. To work around this, users have to inspect the response themselves and then make additional queries for other locales. With this change, Payload handles that work automatically. Users only need to provide a list of fallback locales in their preferred order, and Payload will check each one until it finds a value. ### How? Updates query handling across the local API, REST API, and GraphQL so that `fallbackLocale` can accept either a **string** or an **array** of locales. When an array is passed, Payload will iterate through them in order and return the first found localized value. This behavior applies to both collections and globals. #### Feature request: #13443 --------- Co-authored-by: Jarrod Flesch <jarrodmflesch@gmail.com>
diff --git a/docs/configuration/localization.mdx b/docs/configuration/localization.mdx
@@ -93,12 +93,12 @@ The locale codes do not need to be in any specific format. It's up to you to def
 
 #### 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.                                       |
+| 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. This can be a single locale or array of locales. |
 
 _\* An asterisk denotes that a property is required._
 
@@ -199,7 +199,7 @@ The `locale` arg will only accept valid locales, but locales will be formatted a
 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.
+The `fallbackLocale` arg will accept valid locales, an array of locales, as well as `none` to disable falling back.
 
 **Example:**
 
@@ -224,7 +224,7 @@ query {
 
 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'`.
+locale, array of locales, as well as `'null'`, `'false'`, `false`, and `'none'`.
 
 **Example:**
 
diff --git a/docs/local-api/overview.mdx b/docs/local-api/overview.mdx
@@ -71,7 +71,7 @@ You can specify more options within the Local API vs. REST or GraphQL due to the
 | `locale`             | Specify [locale](/docs/configuration/localization) for any returned documents.                                                                                                                                                                                                                                                                                        |
 | `select`             | Specify [select](../queries/select) to control which fields to include to the result.                                                                                                                                                                                                                                                                                 |
 | `populate`           | Specify [populate](../queries/select#populate) to control which fields to include to the result from populated documents.                                                                                                                                                                                                                                             |
-| `fallbackLocale`     | Specify a [fallback locale](/docs/configuration/localization) to use for any returned documents.                                                                                                                                                                                                                                                                      |
+| `fallbackLocale`     | Specify a [fallback locale](/docs/configuration/localization) to use for any returned documents. This can be a single locale or array of locales.                                                                                                                                                                                                                     |
 | `overrideAccess`     | Skip access control. By default, this property is set to true within all Local API operations.                                                                                                                                                                                                                                                                        |
 | `overrideLock`       | By default, document locks are ignored (`true`). Set to `false` to enforce locks and prevent operations when a document is locked by another user. [More details](../admin/locked-documents).                                                                                                                                                                         |
 | `user`               | If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.                                                                                                                                                                                                                                                                 |
diff --git a/packages/payload/src/admin/RichText.ts b/packages/payload/src/admin/RichText.ts
@@ -31,7 +31,7 @@ export type AfterReadRichTextHookArgs<
 
   draft?: boolean
 
-  fallbackLocale?: string
+  fallbackLocale?: string | string[]
   fieldPromises?: Promise<void>[]
 
   /** Boolean to denote if this hook is running against finding one, or finding many within the afterRead hook. */
diff --git a/packages/payload/src/collections/dataloader.ts b/packages/payload/src/collections/dataloader.ts
@@ -225,8 +225,8 @@ type CreateCacheKeyArgs = {
   depth: number
   docID: number | string
   draft: boolean
-  fallbackLocale: string
-  locale: string
+  fallbackLocale: string | string[]
+  locale: string | string[]
   overrideAccess: boolean
   populate?: PopulateType
   select?: SelectType
diff --git a/packages/payload/src/collections/operations/local/find.ts b/packages/payload/src/collections/operations/local/find.ts
@@ -54,7 +54,7 @@ export type Options<TSlug extends CollectionSlug, TSelect extends SelectType> =
   /**
    * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
    */
-  fallbackLocale?: false | TypedLocale
+  fallbackLocale?: false | TypedLocale | TypedLocale[]
   /**
    * Include info about the lock status to the result into all documents with fields: `_isLocked` and `_userEditing`
    */
diff --git a/packages/payload/src/collections/operations/local/findByID.ts b/packages/payload/src/collections/operations/local/findByID.ts
@@ -62,7 +62,7 @@ export type Options<
   /**
    * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
    */
-  fallbackLocale?: false | TypedLocale
+  fallbackLocale?: false | TypedLocale | TypedLocale[]
   /**
    * The ID of the document to find.
    */
diff --git a/packages/payload/src/collections/operations/utilities/update.ts b/packages/payload/src/collections/operations/utilities/update.ts
@@ -43,7 +43,7 @@ export type SharedUpdateDocumentArgs<TSlug extends CollectionSlug> = {
   depth: number
   docWithLocales: any
   draftArg: boolean
-  fallbackLocale: string
+  fallbackLocale: string | string[]
   filesToUpload: FileToSave[]
   id: number | string
   locale: string
diff --git a/packages/payload/src/config/types.ts b/packages/payload/src/config/types.ts
@@ -470,7 +470,7 @@ export type Locale = {
   /**
    * Code of another locale to use when reading documents with fallback, if not specified defaultLocale is used
    */
-  fallbackLocale?: string
+  fallbackLocale?: string | string[]
   /**
    * label of supported locale
    * @example "English"
diff --git a/packages/payload/src/fields/hooks/afterRead/index.ts b/packages/payload/src/fields/hooks/afterRead/index.ts
@@ -13,7 +13,7 @@ export type AfterReadArgs<T extends JsonObject> = {
   depth: number
   doc: T
   draft: boolean
-  fallbackLocale: null | string
+  fallbackLocale: null | string | string[]
   findMany?: boolean
   /**
    * Controls whether locales should be flattened into the requested locale.
diff --git a/packages/payload/src/fields/hooks/afterRead/promise.ts b/packages/payload/src/fields/hooks/afterRead/promise.ts
@@ -33,7 +33,7 @@ type Args = {
   depth: number
   doc: JsonObject
   draft: boolean
-  fallbackLocale: null | string
+  fallbackLocale: null | string | string[]
   field: Field | TabAsField
   fieldIndex: number
   /**
@@ -158,9 +158,21 @@ export const promise = async ({
     let hoistedValue = value
 
     if (fallbackLocale && fallbackLocale !== locale) {
-      const fallbackValue = siblingDoc[field.name!][fallbackLocale]
+      let fallbackValue
       const isNullOrUndefined = typeof value === 'undefined' || value === null
 
+      if (Array.isArray(fallbackLocale)) {
+        for (const locale of fallbackLocale) {
+          const val = siblingDoc[field.name!]?.[locale]
+          if (val !== undefined && val !== null && val !== '') {
+            fallbackValue = val
+            break
+          }
+        }
+      } else {
+        fallbackValue = siblingDoc[field.name!][fallbackLocale]
+      }
+
       if (fallbackValue) {
         switch (field.type) {
           case 'text':
diff --git a/packages/payload/src/fields/hooks/afterRead/relationshipPopulationPromise.ts b/packages/payload/src/fields/hooks/afterRead/relationshipPopulationPromise.ts
@@ -10,7 +10,7 @@ type PopulateArgs = {
   dataReference: Record<string, any>
   depth: number
   draft: boolean
-  fallbackLocale: null | string
+  fallbackLocale: null | string | string[]
   field: JoinField | RelationshipField | UploadField
   index?: number
   key?: string
@@ -135,7 +135,7 @@ type PromiseArgs = {
   currentDepth: number
   depth: number
   draft: boolean
-  fallbackLocale: null | string
+  fallbackLocale: null | string | string[]
   field: JoinField | RelationshipField | UploadField
   locale: null | string
   overrideAccess: boolean
diff --git a/packages/payload/src/fields/hooks/afterRead/traverseFields.ts b/packages/payload/src/fields/hooks/afterRead/traverseFields.ts
@@ -23,7 +23,7 @@ type Args = {
   depth: number
   doc: JsonObject
   draft: boolean
-  fallbackLocale: null | string
+  fallbackLocale: null | string | string[]
   /**
    * fieldPromises are used for things like field hooks. They should be awaited before awaiting populationPromises
    */
diff --git a/packages/payload/src/fields/hooks/afterRead/virtualFieldPopulationPromise.ts b/packages/payload/src/fields/hooks/afterRead/virtualFieldPopulationPromise.ts
@@ -18,7 +18,7 @@ export const virtualFieldPopulationPromise = async ({
   siblingDoc,
 }: {
   draft: boolean
-  fallbackLocale: string
+  fallbackLocale: string | string[]
   fields: FlattenedField[]
   hasMany?: boolean
   locale: string
diff --git a/packages/payload/src/globals/operations/local/findOne.ts b/packages/payload/src/globals/operations/local/findOne.ts
@@ -37,7 +37,7 @@ export type Options<TSlug extends GlobalSlug, TSelect extends SelectType> = {
   /**
    * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
    */
-  fallbackLocale?: false | TypedLocale
+  fallbackLocale?: false | TypedLocale | TypedLocale[]
   /**
    * Include info about the lock status to the result with fields: `_isLocked` and `_userEditing`
    */
diff --git a/packages/payload/src/types/index.ts b/packages/payload/src/types/index.ts
@@ -26,7 +26,7 @@ export type { Payload } from '../index.js'
 export type CustomPayloadRequestProperties = {
   context: RequestContext
   /** The locale that should be used for a field when it is not translated to the requested locale */
-  fallbackLocale?: string
+  fallbackLocale?: string | string[]
   i18n: I18n
   /**
    * The requested locale if specified
diff --git a/packages/payload/src/utilities/addLocalesToRequest.ts b/packages/payload/src/utilities/addLocalesToRequest.ts
@@ -16,7 +16,7 @@ export function addLocalesToRequestFromData(req: PayloadRequest): void {
     const localeOnReq = req.locale
     const fallbackLocaleOnReq = req.fallbackLocale
     let localeFromData!: string
-    let fallbackLocaleFromData!: string
+    let fallbackLocaleFromData!: string | string[]
 
     if (!localeOnReq && data?.locale && typeof data.locale === 'string') {
       localeFromData = data.locale
@@ -51,12 +51,12 @@ export function addLocalesToRequestFromData(req: PayloadRequest): void {
 }
 
 type SanitizeLocalesArgs = {
-  fallbackLocale: string
+  fallbackLocale: string | string[]
   locale: string
   localization: SanitizedConfig['localization']
 }
 type SanitizeLocalesReturn = {
-  fallbackLocale?: string
+  fallbackLocale?: string | string[]
   locale?: string
 }
 export const sanitizeLocales = ({
diff --git a/packages/payload/src/utilities/createPayloadRequest.ts b/packages/payload/src/utilities/createPayloadRequest.ts
@@ -50,10 +50,7 @@ export const createPayloadRequest = async ({
     language,
   })
 
-  const fallbackFromRequest =
-    searchParams.get('fallback-locale') || searchParams.get('fallbackLocale')
   let locale = searchParams.get('locale')
-  let fallbackLocale = fallbackFromRequest
 
   const { search: queryToParse } = urlProperties
 
@@ -65,6 +62,13 @@ export const createPayloadRequest = async ({
       })
     : {}
 
+  const fallbackFromRequest =
+    (query.fallbackLocale as string | string[]) ||
+    searchParams.get('fallback-locale') ||
+    searchParams.get('fallbackLocale')
+
+  let fallbackLocale = fallbackFromRequest
+
   if (localization) {
     const locales = sanitizeLocales({
       fallbackLocale: fallbackLocale!,
diff --git a/packages/payload/src/utilities/sanitizeFallbackLocale.ts b/packages/payload/src/utilities/sanitizeFallbackLocale.ts
@@ -2,7 +2,7 @@ import type { SanitizedLocalizationConfig } from '../config/types.js'
 import type { TypedLocale } from '../index.js'
 
 interface Args {
-  fallbackLocale: false | TypedLocale
+  fallbackLocale: false | TypedLocale | TypedLocale[]
   locale: string
   localization: SanitizedLocalizationConfig
 }
@@ -26,7 +26,10 @@ export const sanitizeFallbackLocale = ({
     hasFallbackLocale = Boolean(localization && localization.fallback)
   }
 
-  if (fallbackLocale && !['false', 'none', 'null'].includes(fallbackLocale)) {
+  if (
+    fallbackLocale &&
+    (Array.isArray(fallbackLocale) || !['false', 'none', 'null'].includes(fallbackLocale))
+  ) {
     hasFallbackLocale = true
   }
 
diff --git a/packages/richtext-lexical/src/features/typesServer.ts b/packages/richtext-lexical/src/features/typesServer.ts
@@ -121,7 +121,7 @@ export type AfterReadNodeHookArgs<T extends SerializedLexicalNode> = {
    */
   depth: number
   draft: boolean
-  fallbackLocale: string
+  fallbackLocale: string | string[]
   /**
    *  Only available in `afterRead` field hooks.
    */
diff --git a/test/helpers/NextRESTClient.ts b/test/helpers/NextRESTClient.ts
@@ -19,7 +19,7 @@ type RequestOptions = {
   auth?: boolean
   query?: { [key: string]: unknown } & {
     depth?: number
-    fallbackLocale?: string
+    fallbackLocale?: string | string[]
     joins?: JoinQuery
     limit?: number
     locale?: string
diff --git a/test/localization/int.spec.ts b/test/localization/int.spec.ts
