feat: adds experimental option localizeStatus and allows unpublish per-locale functionality (#14667)

## Localized Status (Experimental) 

This PR introduces a new **experimental** option that allows each locale
to track and manage its own publication status independently, for
collection docs and globals.

### Configuration
To enable this feature, you need **two** configurations:

1. Enable the experimental flag in your `payload.config`:

```ts
experimental: {
  localizeStatus: true, // default: `false`
}
```

2. Enable it on specific collections/globals:
```ts
export const Posts: CollectionConfig = {
  slug: 'posts',
  versions: {
    drafts: {
      localizeStatus: true, // default: false
    },
  },
  // ...
}
```

## Key Changes

When enabled:

- **Per-locale status tracking** - Each locale maintains its own
published/draft status
- **Independent publishing** - Publish or unpublish individual locales
without affecting others
- **Locale-aware UI** - Admin panel shows status for the currently
active locale
- **Localized version history** - Versions list reflects the current
locale's status

## Improved Behavior
- Creating a document in one locale sets that locale to the specified
status and other locales default to draft
- You can publish/unpublish specific locales independently
- Collection list views show status for the currently active locale
- Document edit view displays the current locale's status

## Migration Required (If you already have version data)

> If this is a new project then you only need to enable the flags. If
you have existing data you will want to continue with the migration
guide below.

⚠️ Breaking Change: When `localizeStatus` is enabled, existing `_status`
fields will need to be migrated from strings to locale objects.

### ➡️ Step 1
Before doing anything, **take a backup of your current database**.

### ➡️ Step 2
Stop your dev server if it is running

### ➡️  Step 3
**Create migration file**
```ts
// run the following to create a blank
// migration file named `localize_status`
payload migrate:create localize_status
```

**Add migration code**

🔵 **PostgreSQL / SQLite**:
```ts
import type { MigrateDownArgs, MigrateUpArgs } from '@payloadcms/db-postgres'
import { sql } from '@payloadcms/db-postgres'
import { localizeStatus } from 'payload/migrations'

export async function up({ db, payload }: MigrateUpArgs): Promise<void> {
  await localizeStatus.up({
    collectionSlug: 'posts', // 👈 Change to your collection
    db,
    payload,
    sql,
  })
}

export async function down({ db, payload }: MigrateDownArgs): Promise<void> {
  await localizeStatus.down({
    collectionSlug: 'posts', // 👈 Change to your collection  
    db,
    payload,
    sql,
  })
}
```

🟢  **MongoDB**:
```ts
import type { MigrateDownArgs, MigrateUpArgs } from '@payloadcms/db-mongodb'
import { localizeStatus } from 'payload/migrations'

export async function up({ payload }: MigrateUpArgs): Promise<void> {
  await localizeStatus.up({
    collectionSlug: 'posts', // 👈 Change to your collection
    payload,
  })
}

export async function down({ payload }: MigrateDownArgs): Promise<void> {
  await localizeStatus.down({
    collectionSlug: 'posts', // 👈 Change to your collection
    payload,
  })
}
```

### ➡️ Step 4
Run the migration
```ts
payload migrate
```

### ➡️ Step 5
Set `localizeStatus: true` 

**Payload Config**
```ts
// payload config file
experimental: {
  localizeStatus: true, // <-- add this
}
```

**Collection Config**
```ts
// collection you want to migrate
export const Posts: CollectionConfig = {
  slug: 'posts',
  versions: {
    drafts: {
      localizeStatus: true, // <-- add this
    },
  },
  // ...
}
```

### ➡️ Step 6
Run `pnpm dev` and test out the feature.
  
## Related PRs in this feature

- [feat: adds versions.drafts.localizeStatus and allows unpublish
per‑locale #14667](#14667)
- [feat(ui): experimental localize metadata UI
#14699](#14699)
- [chore: localize status migration work
#14862](#14862)

---------

Co-authored-by: Jessica Chowdhury <jessica@trbl.design>
Co-authored-by: Sasha <64744993+r1tsuu@users.noreply.github.com>
Co-authored-by: Jessica Rynkar <67977755+jessrynkar@users.noreply.github.com>

Author: 3 people

docs/configuration/localization.mdx

@@ -167,6 +167,69 @@ All field types with a `name` property support the `localized` property—even t
   strategy.
 </Banner>
 
+## Status Localization
+
+Payload allows you to localize the `status` field for **draft enabled** collections and globals. This lets you manage publication status independently for each locale, ensures the admin UI always shows the status for the selected locale, and unpublish content in a single locale.
+
+<Banner type="warning">
+  **Important:** This feature is **experimental** and currently in beta, you may
+  encounter some limitations or bugs. Please test thoroughly before using in
+  production.
+</Banner>
+
+**Two-Step Setup Required:** To enable localized status, you need to set **two** configuration options:
+
+1. Enable the experimental flag in your main config
+2. Enable it for specific collections or globals
+
+### Step 1: Enable Experimental Flag
+
+First, enable the experimental flag in your main Payload config:
+
+```ts
+import { buildConfig } from 'payload'
+
+export default buildConfig({
+  // highlight-start
+  experimental: {
+    localizeStatus: true, // Required to enable the feature globally
+  },
+  // highlight-end
+  // ... rest of your config
+})
+```
+
+### Step 2: Enable for Collections/Globals
+
+Then, enable it for specific collections or globals:
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const Posts: CollectionConfig = {
+  // ...
+  versions: {
+    drafts: {
+      // highlight-start
+      localizeStatus: true, // Enable for this specific collection
+      // highlight-end
+    },
+  },
+}
+```
+
+When enabled, the `status` field will be stored as an object keyed by locales:
+
+```ts
+status: {
+  en: 'published',
+  es: 'draft',
+  de: 'published',
+}
+```
+
+`localizeStatus` is disabled by default, in which case the `status` field returns a single string (`'draft'` or `'published'`) representing the latest document status across all locales.
+
 ## Retrieving Localized Docs
 
 When retrieving documents, you can specify which locale you'd like to receive as well as which fallback locale should be

docs/versions/drafts.mdx

@@ -24,6 +24,7 @@ Collections and Globals both support the same options for configuring drafts. Yo
 | Draft Option      | Description                                                                                                                                                      |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `autosave`        | Enable `autosave` to automatically save progress while documents are edited. To enable, set to `true` or pass an object with [options](/docs/versions/autosave). |
+| `localizeStatus`  | **Beta**. Localizes the `_status` field when using [Localization](/docs/configuration/localization). Default is `false`.                                         |
 | `schedulePublish` | Allow for editors to schedule publish / unpublish events in the future. [More](#scheduled-publish)                                                               |
 | `validate`        | Set `validate` to `true` to validate draft documents when saved. Default is `false`.                                                                             |
 

packages/drizzle/src/queries/getTableColumnFromPath.ts

@@ -117,6 +117,7 @@ export const getTableColumnFromPath = ({
     }
   }
 
+  let localizedPathQuery = false
   if (field) {
     const pathSegments = [...incomingSegments]
 
@@ -131,6 +132,7 @@ export const getTableColumnFromPath = ({
 
       if (matchedLocale) {
         locale = matchedLocale
+        localizedPathQuery = true
         pathSegments.splice(1, 1)
       }
     }
@@ -967,7 +969,13 @@ export const getTableColumnFromPath = ({
       const parentTable = aliasTable || adapter.tables[tableName]
       newTableName = `${tableName}${adapter.localesSuffix}`
 
-      newTable = adapter.tables[newTableName]
+      // use an alias because the same query may contain constraints with different locale value
+      if (localizedPathQuery) {
+        const { newAliasTable } = getTableAlias({ adapter, tableName: newTableName })
+        newTable = newAliasTable
+      } else {
+        newTable = adapter.tables[newTableName]
+      }
 
       let condition = eq(parentTable.id, newTable._parentID)
 

packages/next/src/elements/DocumentHeader/Tabs/tabs/VersionsPill/index.scss

@@ -5,5 +5,6 @@
     text-align: center;
     background-color: var(--theme-elevation-100);
     border-radius: var(--style-radius-s);
+    padding: 2px 4px;
   }
 }

packages/next/src/views/Document/getVersions.ts

@@ -1,4 +1,4 @@
-import { sanitizeID } from '@payloadcms/ui/shared'
+import { sanitizeID, traverseForLocalizedFields } from '@payloadcms/ui/shared'
 import {
   combineQueries,
   extractAccessFromPermission,
@@ -56,12 +56,19 @@ export const getVersions = async ({
 
   const entityConfig = collectionConfig || globalConfig
   const versionsConfig = entityConfig?.versions
+  const hasLocalizedFields = traverseForLocalizedFields(entityConfig.fields)
+  const localizedDraftsEnabled =
+    hasDraftsEnabled(entityConfig) &&
+    typeof payload.config.localization === 'object' &&
+    hasLocalizedFields
 
   const shouldFetchVersions = Boolean(versionsConfig && docPermissions?.readVersions)
 
   if (!shouldFetchVersions) {
     // Without readVersions permission, determine published status from the _status field
-    const hasPublishedDoc = doc?._status !== 'draft'
+    const hasPublishedDoc = localizedDraftsEnabled
+      ? doc?._status === 'published'
+      : doc?._status !== 'draft'
 
     return {
       hasPublishedDoc,
@@ -100,18 +107,9 @@ export const getVersions = async ({
             where: {
               and: [
                 {
-                  or: [
-                    {
-                      _status: {
-                        equals: 'published',
-                      },
-                    },
-                    {
-                      _status: {
-                        exists: false,
-                      },
-                    },
-                  ],
+                  _status: {
+                    equals: 'published',
+                  },
                 },
                 {
                   id: {
@@ -129,26 +127,34 @@ export const getVersions = async ({
       }
 
       if (hasAutosaveEnabled(collectionConfig)) {
+        const where: Record<string, any> = {
+          and: [
+            {
+              parent: {
+                equals: id,
+              },
+            },
+          ],
+        }
+
+        if (localizedDraftsEnabled) {
+          where.and.push({
+            snapshot: {
+              not_equals: true,
+            },
+          })
+        }
+
         const mostRecentVersion = await payload.findVersions({
           collection: collectionConfig.slug,
           depth: 0,
           limit: 1,
+          locale,
           select: {
             autosave: true,
           },
           user,
-          where: combineQueries(
-            {
-              and: [
-                {
-                  parent: {
-                    equals: id,
-                  },
-                },
-              ],
-            },
-            extractAccessFromPermission(docPermissions.readVersions),
-          ),
+          where: combineQueries(where, extractAccessFromPermission(docPermissions.readVersions)),
         })
 
         if (
@@ -163,6 +169,7 @@ export const getVersions = async ({
       if (publishedDoc?.updatedAt) {
         ;({ totalDocs: unpublishedVersionCount } = await payload.countVersions({
           collection: collectionConfig.slug,
+          locale,
           user,
           where: combineQueries(
             {
@@ -190,20 +197,31 @@ export const getVersions = async ({
       }
     }
 
+    const countVersionsWhere: Record<string, any> = {
+      and: [
+        {
+          parent: {
+            equals: id,
+          },
+        },
+      ],
+    }
+
+    if (localizedDraftsEnabled) {
+      countVersionsWhere.and.push({
+        snapshot: {
+          not_equals: true,
+        },
+      })
+    }
+
     ;({ totalDocs: versionCount } = await payload.countVersions({
       collection: collectionConfig.slug,
       depth: 0,
+      locale,
       user,
       where: combineQueries(
-        {
-          and: [
-            {
-              parent: {
-                equals: id,
-              },
-            },
-          ],
-        },
+        countVersionsWhere,
         extractAccessFromPermission(docPermissions.readVersions),
       ),
     }))
@@ -234,6 +252,7 @@ export const getVersions = async ({
         const mostRecentVersion = await payload.findGlobalVersions({
           slug: globalConfig.slug,
           limit: 1,
+          locale,
           select: {
             autosave: true,
           },
@@ -253,6 +272,7 @@ export const getVersions = async ({
         ;({ totalDocs: unpublishedVersionCount } = await payload.countGlobalVersions({
           depth: 0,
           global: globalConfig.slug,
+          locale,
           user,
           where: combineQueries(
             {
@@ -278,7 +298,15 @@ export const getVersions = async ({
     ;({ totalDocs: versionCount } = await payload.countGlobalVersions({
       depth: 0,
       global: globalConfig.slug,
+      locale,
       user,
+      where: localizedDraftsEnabled
+        ? {
+            snapshot: {
+              not_equals: true,
+            },
+          }
+        : undefined,
     }))
   }
 

packages/next/src/views/Version/VersionPillLabel/VersionPillLabel.tsx

@@ -1,5 +1,7 @@
 'use client'
 
+import type { TypeWithVersion } from 'payload'
+
 import { Pill, useConfig, useTranslation } from '@payloadcms/ui'
 import { formatDate } from '@payloadcms/ui/shared'
 import React from 'react'
@@ -18,10 +20,7 @@ const renderPill = (label: React.ReactNode, pillStyle: Parameters<typeof Pill>[0
 }
 
 export const VersionPillLabel: React.FC<{
-  currentlyPublishedVersion?: {
-    id: number | string
-    updatedAt: string
-  }
+  currentlyPublishedVersion?: TypeWithVersion<any>
   disableDate?: boolean
 
   doc: {
@@ -31,7 +30,8 @@ export const VersionPillLabel: React.FC<{
     updatedAt?: string
     version: {
       [key: string]: unknown
-      _status: string
+      _status: 'draft' | 'published'
+      updatedAt: string
     }
   }
   /**
@@ -45,10 +45,7 @@ export const VersionPillLabel: React.FC<{
    */
   labelStyle?: 'pill' | 'text'
   labelSuffix?: React.ReactNode
-  latestDraftVersion?: {
-    id: number | string
-    updatedAt: string
-  }
+  latestDraftVersion?: TypeWithVersion<any>
 }> = ({
   currentlyPublishedVersion,
   disableDate = false,