tabshift/payload
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update localization.enableStatusLocalization to experimental.localizeStatus

Browse Source
This commit is contained in:
Jessica Chowdhury
2025-08-14 11:23:46 +01:00
parent 8a9caef82c
commit b2becb8715
9 changed files with 122 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/configuration/localization.mdx
View File

@@ -78,13 +78,12 @@ export default buildConfig({
The following options are available:
| Option | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`locales`** | Array of all the languages that you would like to support. [More details](#locales) |
| **`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. |
| **`enableStatusLocalization`** | **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`. |
| **`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. |
| **`filterAvailableLocales`** | A function that is called with the array of `locales` and the `req`, it should return locales to show in admin UI selector. [See more](#filter-available-options). |
| Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`locales`** | Array of all the languages that you would like to support. [More details](#locales) |
| **`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. |
| **`filterAvailableLocales`** | A function that is called with the array of `locales` and the `req`, it should return locales to show in admin UI selector. [See more](#filter-available-options). |
### Locales
@@ -132,6 +131,29 @@ localization: {
Since the filtering happens at the root level of the application and its result is not calculated every time you navigate to a new page, you may want to call `router.refresh` in a custom component that watches when values that affect the result change. In the example above, you would want to do this when `supportedLocales` changes on the tenant document.
## Experimental Options
Experimental options are features that may not be fully stable and may change or be removed in future releases.
These options can be enabled in your Payload Config under the `experimental` key. You can set them like this:
```ts
import { buildConfig } from 'payload'
export default buildConfig({
// ...
experimental: {
statusLocalization: true, // enable experimental status localization
},
})
```
The following experimental options are available related to localization:
| Option | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`statusLocalization`** | **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`. |
## 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.

1
docs/configuration/overview.mdx
View File

@@ -70,6 +70,7 @@ The following options are available:
| **`admin`** | The configuration options for the Admin Panel, including Custom Components, Live Preview, etc. [More details](../admin/overview#admin-options). |
| **`bin`** | Register custom bin scripts for Payload to execute. [More Details](#custom-bin-scripts). |
| **`editor`** | The Rich Text Editor which will be used by `richText` fields. [More details](../rich-text/overview). |
| **`experimental`** | Configure experimental features for Payload. These may be unstable and may change or be removed in future releases. [More details](../experimental). |
| **`db`** \* | The Database Adapter which will be used by Payload. [More details](../database/overview). |
| **`serverURL`** | A string used to define the absolute URL of your app. This includes the protocol, for example `https://example.com`. No paths allowed, only protocol, domain and (optionally) port. |
| **`collections`** | An array of Collections for Payload to manage. [More details](./collections). |

66
docs/experimental/overview.mdx Normal file
View File

@@ -0,0 +1,66 @@
---
title: Experimental Features
label: Overview
order: 10
desc: Enable and configure experimental functionality within Payload. These featuresmay be unstable and may change or be removed without notice.
keywords: experimental, unstable, beta, preview, features, configuration, Payload, cms, headless, javascript, node, react, nextjs
---
Experimental features allow you to try out new functionality before it becomes a stable part of Payload. These features may still be in active development, may have incomplete functionality, and can change or be removed in future releases without warning.
## How It Works
Experimental features are configured via the root-level `experimental` property in your [Payload Config](../configuration/overview). This property contains individual feature flags, each flag can be configured independently, allowing you to selectively opt into specific functionality.
```ts
import { buildConfig } from 'payload'
const config = buildConfig({
// ...
experimental: {
localizeStatus: true, // highlight-line
},
})
```
## Experimental Options
The following options are available:
| Option | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`statusLocalization`** | **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`. |
This list may change without notice.
## When to Use Experimental Features
You might enable an experimental feature when:
- You want early access to new capabilities before their stable release.
- You can accept the risks of using potentially unstable functionality.
- You are testing new features in a development or staging environment.
- You wish to provide feedback to the Payload team on new functionality.
If you are working on a production application, carefully evaluate whether the benefits outweigh the risks. For most stable applications, it is recommended to wait until the feature is officially released.
<Banner type="success">
<strong>Tip:</strong> To stay up to date on experimental features or share
your feedback, visit the{' '}
<a
href="https://github.com/payloadcms/payload/discussions"
target="_blank"
rel="noopener noreferrer"
>
Payload GitHub Discussions
</a>{' '}
or{' '}
<a
href="https://github.com/payloadcms/payload/issues"
target="_blank"
rel="noopener noreferrer"
>
open an issue
</a>
.
</Banner>

8
packages/payload/src/config/client.ts
View File

@@ -193,9 +193,11 @@ export const createClientConfig = ({
config.localization.defaultLocalePublishOption
}
if (config.localization.enableStatusLocalization) {
clientConfig.localization.enableStatusLocalization =
config.localization.enableStatusLocalization
if (config.experimental?.localizeStatus) {
if (!clientConfig.experimental) {
clientConfig.experimental = {}
}
clientConfig.experimental.localizeStatus = config.experimental.localizeStatus
}
if (config.localization.fallback) {

21
packages/payload/src/config/types.ts
View File

@@ -486,12 +486,6 @@ export type BaseLocalizationConfig = {
* @default 'all'
*/
defaultLocalePublishOption?: 'active' | 'all'
/**
* Enable localization of the status of the document.
* If enabled, the status will reflect the current locale throughout the Admin UI.
* @default false
*/
enableStatusLocalization?: boolean
/** Set to `true` to let missing values in localised fields fall back to the values in `defaultLocale`
*
* If false, then no requests will fallback unless a fallbackLocale is specified in the request.
@@ -726,6 +720,14 @@ export type ImportMapGenerators = Array<
}) => void
>
/**
* Experimental features.
* These may be unstable and may change or be removed in future releases.
*/
export type ExperimentalConfig = {
localizeStatus?: boolean
}
export type AfterErrorHook = (
args: AfterErrorHookArgs,
) => AfterErrorResult | Promise<AfterErrorResult>
@@ -1023,6 +1025,12 @@ export type Config = {
email?: EmailAdapter | Promise<EmailAdapter>
/** Custom REST endpoints */
endpoints?: Endpoint[]
/**
* Configure experimental features for Payload.
*
* These features may be unstable and may change or be removed in future releases.
*/
experimental?: ExperimentalConfig
/**
* Options for folder view within the admin panel
* @experimental this feature may change in minor versions until it is fully stable
@@ -1291,6 +1299,7 @@ export type SanitizedConfig = {
/** Default richtext editor to use for richText fields */
editor?: RichTextAdapter<any, any, any>
endpoints: Endpoint[]
experimental?: ExperimentalConfig
globals: SanitizedGlobalConfig[]
i18n: Required<I18nOptions>
jobs: SanitizedJobsConfig

2
packages/payload/src/versions/buildCollectionFields.ts
View File

@@ -63,7 +63,7 @@ export const buildVersionCollectionFields = <T extends boolean = false>(
}),
})
if (config.localization.enableStatusLocalization) {
if (config.experimental?.localizeStatus) {
const localeStatusFields = buildLocaleStatusField(config)
fields.push({

2
packages/payload/src/versions/buildGlobalFields.ts
View File

@@ -57,7 +57,7 @@ export const buildVersionGlobalFields = <T extends boolean = false>(
}),
})
if (config.localization.enableStatusLocalization) {
if (config.experimental.localizeStatus) {
const localeStatusFields = buildLocaleStatusField(config)
fields.push({

2
packages/payload/src/versions/saveVersion.ts
View File

@@ -137,7 +137,7 @@ export const saveVersion = async ({
if (
localizationEnabled &&
payload.config.localization !== false &&
payload.config.localization.enableStatusLocalization
payload.config.experimental?.localizeStatus
) {
const allLocales = (
(payload.config.localization && payload.config.localization?.locales) ||

4
test/localization/config.ts
View File

@@ -428,13 +428,15 @@ export default buildConfigWithDefaults({
slug: 'global-text',
},
],
experimental: {
localizeStatus: true,
},
localization: {
filterAvailableLocales: ({ locales }) => {
return locales.filter((locale) => locale.code !== 'xx')
},
defaultLocale,
fallback: true,
enableStatusLocalization: true,
locales: [
{
code: 'xx',