chore: updates multipleFallbackLocales to an experimental feature

Author: jessrynkar

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. This can be a single locale or array of locales. |
+| 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. You can enable `experimental.multipleFallbackLocales` to allow an array of locales. |
 
 _\* An asterisk denotes that a property is required._
 
@@ -150,9 +150,10 @@ export default buildConfig({
 
 The following experimental options are available related to localization:
 
-| Option               | Description                                                                                                                                                                                 |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`localizeStatus`** | **Boolean.** When `true`, shows document status per locale in the admin panel instead of always showing the latest overall status. Opt-in for backwards compatibility. Defaults to `false`. |
+| Option                        | Description                                                                                                                                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`localizeStatus`**          | **Boolean.** When `true`, shows document status per locale in the admin panel instead of always showing the latest overall status. Opt-in for backwards compatibility. Defaults to `false`. |
+| **`multipleFallbackLocales`** | **Boolean.** When `true`, allows `fallbackLocale` to accept an array of locales in find queries and locale configuration. Defaults to `false`.                                              |
 
 ## Field Localization
 
@@ -222,7 +223,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, an array of locales, as well as `none` to disable falling back.
+The `fallbackLocale` arg will accept valid locales as well as `none` to disable falling back.
 
 **Example:**
 
@@ -247,7 +248,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, array of locales, as well as `'null'`, `'false'`, `false`, and `'none'`.
+locale as well as `'null'`, `'false'`, `false`, and `'none'`.
 
 **Example:**
 

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. This can be a single locale or array of locales.                                                                                                                                                                                                                     |
+| `fallbackLocale`     | Specify a [fallback locale](/docs/configuration/localization) to use for any returned documents.                                                                                                                                                                                                                                                                      |
 | `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.                                                                                                                                                                                                                                                                 |

packages/payload/src/config/client.ts

@@ -229,6 +229,10 @@ export const createClientConfig = ({
           if (config.experimental?.localizeStatus) {
             clientConfig.experimental.localizeStatus = config.experimental.localizeStatus
           }
+          if (config.experimental?.multipleFallbackLocales) {
+            clientConfig.experimental.multipleFallbackLocales =
+              config.experimental.multipleFallbackLocales
+          }
         }
 
         break

packages/payload/src/config/types.ts

@@ -732,6 +732,10 @@ export type ImportMapGenerators = Array<
  */
 export type ExperimentalConfig = {
   localizeStatus?: boolean
+  /**
+   * When true, fallbackLocale accepts an array of locales in find queries and locale configuration.
+   */
+  multipleFallbackLocales?: boolean
 }
 
 export type AfterErrorHook = (

packages/payload/src/fields/hooks/afterRead/index.ts

@@ -81,6 +81,7 @@ export async function afterRead<T extends JsonObject>(args: AfterReadArgs<T>): P
     depth,
     doc: incomingDoc,
     draft,
+    experimental: req.payload.config.experimental,
     fallbackLocale,
     fieldPromises,
     fields: (collection?.fields || global?.fields)!,

packages/payload/src/fields/hooks/afterRead/promise.ts

@@ -1,6 +1,7 @@
 import type { RichTextAdapter } from '../../../admin/RichText.js'
 import type { SanitizedCollectionConfig } from '../../../collections/config/types.js'
 import type { SanitizedGlobalConfig } from '../../../globals/config/types.js'
+import type { ExperimentalConfig, RequestContext } from '../../../index.js'
 import type {
   JsonObject,
   PayloadRequest,
@@ -12,7 +13,6 @@ import type { Block, Field, TabAsField } from '../../config/types.js'
 import type { AfterReadArgs } from './index.js'
 
 import { MissingEditorProp } from '../../../errors/index.js'
-import { type RequestContext } from '../../../index.js'
 import { getBlockSelect } from '../../../utilities/getBlockSelect.js'
 import { stripUnselectedFields } from '../../../utilities/stripUnselectedFields.js'
 import { fieldAffectsData, fieldShouldBeLocalized, tabHasName } from '../../config/types.js'
@@ -33,6 +33,7 @@ type Args = {
   depth: number
   doc: JsonObject
   draft: boolean
+  experimental?: ExperimentalConfig
   fallbackLocale: null | string
   field: Field | TabAsField
   fieldIndex: number
@@ -79,6 +80,7 @@ export const promise = async ({
   depth,
   doc,
   draft,
+  experimental,
   fallbackLocale,
   field,
   fieldIndex,
@@ -160,8 +162,8 @@ export const promise = async ({
     if (fallbackLocale && fallbackLocale !== locale) {
       let fallbackValue
       const isNullOrUndefined = typeof value === 'undefined' || value === null
-
-      if (Array.isArray(fallbackLocale)) {
+      console.log(experimental?.multipleFallbackLocales)
+      if (experimental?.multipleFallbackLocales && Array.isArray(fallbackLocale)) {
         for (const locale of fallbackLocale) {
           const val = siblingDoc[field.name!]?.[locale]
 

packages/payload/src/fields/hooks/afterRead/traverseFields.ts

@@ -1,6 +1,6 @@
 import type { SanitizedCollectionConfig } from '../../../collections/config/types.js'
 import type { SanitizedGlobalConfig } from '../../../globals/config/types.js'
-import type { RequestContext } from '../../../index.js'
+import type { ExperimentalConfig, RequestContext } from '../../../index.js'
 import type {
   JsonObject,
   PayloadRequest,
@@ -23,6 +23,7 @@ type Args = {
   depth: number
   doc: JsonObject
   draft: boolean
+  experimental?: ExperimentalConfig
   fallbackLocale: null | string
   /**
    * fieldPromises are used for things like field hooks. They should be awaited before awaiting populationPromises
@@ -60,6 +61,7 @@ export const traverseFields = ({
   depth,
   doc,
   draft,
+  experimental,
   fallbackLocale,
   fieldPromises,
   fields,
@@ -92,6 +94,7 @@ export const traverseFields = ({
         depth,
         doc,
         draft,
+        experimental,
         fallbackLocale,
         field,
         fieldIndex,

test/localization/config.ts

@@ -430,6 +430,7 @@ export default buildConfigWithDefaults({
   ],
   experimental: {
     localizeStatus: true,
+    multipleFallbackLocales: true,
   },
   localization: {
     filterAvailableLocales: ({ locales }) => {