refactor!: remove allowLocalizedWithinLocalized compat flag and PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY env var by AlessioGr · Pull Request #16693 · payloadcms/payload

AlessioGr · 2026-05-20T03:10:14Z

BREAKING

Removes config.compatibility.allowLocalizedWithinLocalized and the PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY env var. Sanitize no longer strips localized: true from fields nested under a localized parent - fieldShouldBeLocalized decides this at runtime instead.

Who is affected:

Users of compatibility: { allowLocalizedWithinLocalized: true }
Anyone with localized: true nested under a localized parent - end behavior is unchanged (Payload's own code already uses fieldShouldBeLocalized), but field.localized is no longer being deleted. Custom plugin/hook code that reads field.localized directly will now see true where it previously saw undefined.

How to migrate:

Remove the compatibility block from your config. If your Mongo data still has the redundant nested-localized shape, flatten the config and run a data migration
Replace any direct field.localized reads in custom code with fieldShouldBeLocalized({ field, parentIsLocalized }) from payload/shared.

Why these existed

allowLocalizedWithinLocalized (#7933) was an opt-out for the new auto-stripping behavior, aimed at pre-3.0 Mongo users with data already written under nested-localized configs. Always marked for removal in 4.0.

PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY existed because of block references. Blocks defined at the top of the config can be referenced from both localized and non-localized parents, but sanitize visits each block only once (_sanitized = true), so whichever parent it sees first locks in the wrong answer for the other. #11207 fixed this by moving the check to runtime via fieldShouldBeLocalized({ field, parentIsLocalized }).

Whether we sanitize the localized properties away or not does not have an impact on this functionality. However, we had to set PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY in our monorepo to test against sanitization disabled, in order to guarantee correct runtime handling through our tests.

Removing PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY and making it the default behavior ensures that the behavior users will encounter matches what we have and test for in the payload monorepo.

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1214980013153702

github-actions · 2026-05-20T03:18:37Z

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖

Meta File	Out File	Size (raw)	Note
packages/next/meta_index.json	esbuild/index.js	989.31 KB	✅ No change
packages/payload/meta_index.json	esbuild/index.js	1.41 MB	✅ -393 B (-0.0%)
packages/payload/meta_shared.json	esbuild/exports/shared.js	192.51 KB	✅ -88 B (-0.0%)
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	304.12 KB	✅ No change
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.24 MB	✅ No change
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	16.11 KB	✅ No change

Largest paths

These visualization shows top 20 largest paths in the bundle.

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████▌ }}}$ 82.0%, 807.52 KB
dist/views/Version	${{\color{Goldenrod}{ █▎ }}}$ 5.2%, 51.48 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 21.71 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 16.66 KB
dist/views/List	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 15.39 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 10.24 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 9.90 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.17 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.13 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.06 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.71 KB
dist/views/Login	${{\color{Goldenrod}{ }}}$ 0.4%, 4.40 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.4%, 3.53 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 3.13 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 2.81 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.2%, 2.40 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.2%, 2.02 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.2%, 1.94 KB
dist/views/Verify	${{\color{Goldenrod}{ }}}$ 0.1%, 1.29 KB
dist/views/NotFound	${{\color{Goldenrod}{ }}}$ 0.1%, 1.21 KB
(other)	${{\color{Goldenrod}{ ████▌ }}}$ 18.0%, 177.11 KB

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████ }}}$ 68.4%, 959.38 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 44.07 KB
dist/collections/operations	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 40.23 KB
dist/versions/migrations	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 18.50 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 15.63 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.41 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.40 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 13.13 KB
dist/queues/operations	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 12.63 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.57 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.53 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.44 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.92 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.80 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.77 KB
dist/hierarchy/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.65 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.54 KB
dist/collections/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 6.23 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.43 KB
dist/queues/config	${{\color{Goldenrod}{ }}}$ 0.4%, 5.31 KB
(other)	${{\color{Goldenrod}{ ███████▉ }}}$ 31.6%, 443.02 KB

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▉ }}}$ 79.5%, 150.12 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▍ }}}$ 5.6%, 10.57 KB
dist/config/orderable	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 3.13 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 2.54 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 1.29 KB
dist/utilities/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 1.04 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 943 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ }}}$ 0.4%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.3%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.3%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 525 B
dist/fields/getFieldPaths.js	${{\color{Goldenrod}{ }}}$ 0.3%, 485 B
dist/utilities/appendDateTimezoneSelectFields.js	${{\color{Goldenrod}{ }}}$ 0.2%, 451 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.2%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.2%, 413 B
(other)	${{\color{Goldenrod}{ █████▏ }}}$ 20.5%, 38.61 KB

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/features/blocks	${{\color{Goldenrod}{ ███ }}}$ 12.4%, 37.36 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▊ }}}$ 11.4%, 34.16 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▋ }}}$ 10.9%, 32.88 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▎ }}}$ 9.0%, 27.16 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▌ }}}$ 6.3%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▌ }}}$ 6.3%, 18.81 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 16.58 KB
dist/features/upload	${{\color{Goldenrod}{ █▏ }}}$ 4.7%, 14.09 KB
dist/features/textState	${{\color{Goldenrod}{ ▉ }}}$ 3.7%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 9.39 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 8.79 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 8.36 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.40 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 7.29 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 5.08 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 5.00 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.23 KB
dist/features/horizontalRule	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.18 KB
dist/field/Field.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.84 KB
(other)	${{\color{Goldenrod}{ █████████████████████▉ }}}$ 87.6%, 263.53 KB

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████▊ }}}$ 47.0%, 579.80 KB
dist/elements/Hierarchy	${{\color{Goldenrod}{ ▉ }}}$ 3.5%, 43.71 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.3%, 28.05 KB
dist/elements/Table	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 19.18 KB
dist/views/HierarchyList	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 18.70 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 17.38 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 17.24 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.92 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.48 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.11 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 14.39 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.25 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.00 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.99 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.84 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.75 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.04 KB
dist/elements/RelationshipTable	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.88 KB
dist/elements/Upload	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.62 KB
(other)	${{\color{Goldenrod}{ █████████████▎ }}}$ 53.0%, 653.48 KB

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████ }}}$ 20.2%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▎ }}}$ 17.1%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▍ }}}$ 9.8%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▏ }}}$ 8.6%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▍ }}}$ 5.6%, 866 B
dist/utilities/getGlobalData.js	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 762 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 756 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▏ }}}$ 4.7%, 734 B
dist/elements/Translation	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 440 B
dist/utilities/traverseForLocalizedFields.js	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 399 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 339 B
dist/utilities/getNavGroups.js	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 338 B
dist/utilities/getVisibleEntities.js	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 329 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 180 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 159 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 152 B
dist/forms/Form	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 146 B
(other)	${{\color{Goldenrod}{ ███████████████████▉ }}}$ 79.8%, 12.36 KB

Details

Next to the size is how much the size has increased or decreased compared with the base branch of this PR.

‼️: Size increased by 20% or more. Special attention should be given to this.
⚠️: Size increased in acceptable range (lower than 20%).
✅: No change or even downsized.
🗑️: The out file is deleted: not found in base branch.
🆕: The out file is newly found: will be added to base branch.

DanRibbens

This needs to be added to docs/migration-guide/v4.mdx

Adds all breaking changes docs from my own PRs to the v4 migration doc. | PR | Breaking change | Merged | In v4 migration doc | |----|-----------------|--------|---------------------| | [#16359](#16359) | `feat!` Deleted `@payloadcms/richtext-slate` — Lexical is now the only supported rich text editor | 2026-04-23 | ✅ Added (was missing) | | [#16414](#16414) | `feat!` Removed deprecated `jobs.depth` and `jobs.runHooks` config options | 2026-04-28 | ✅ Added (was missing) | | [#16416](#16416) | `feat!` Removed deprecated `state: 'failed'`/`'succeeded'` job task return shape | 2026-05-01 | ✅ Added (was missing) | | [#16537](#16537) | `feat!` Bumped minimum Next.js version to 16.2.6 | 2026-05-07 | ✅ Added (was missing) | | [#16540](#16540) | `feat!` Bumped minimum Node.js version to 24.15.0 | 2026-05-08 | ✅ Added (was missing) | | [#16546](#16546) | `feat!` Removed croner `sloppyRanges` compatibility setting (stricter cron parsing) | 2026-05-08 | ✅ Added (was missing) | | [#16547](#16547) | `feat!` Removed deprecated `min`/`max` from `relationship`/`upload` fields | 2026-05-08 | ✅ Added (was missing) | | [#16548](#16548) | `feat(richtext-lexical)!` Removed deprecated `HTMLConverterFeature` / `lexicalHTML` | 2026-05-11 | ✅ Added (was missing) | | [#16692](#16692) | `feat!` Bumped minimum TypeScript version to 6.0.3 | 2026-05-20 | ✅ Added (was missing) | | [#16693](#16693) | `refactor!` Removed `allowLocalizedWithinLocalized` compat flag + `PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY` env var | 2026-05-21 | ✅ Added (was missing) |

commit

833e4c2

github-actions Bot added the created-by: Payload team label May 20, 2026

AlessioGr enabled auto-merge (squash) May 20, 2026 23:15

paulpopus approved these changes May 21, 2026

View reviewed changes

AlessioGr merged commit ebdb3a7 into main May 21, 2026
335 of 337 checks passed

AlessioGr deleted the refactor/localized branch May 21, 2026 11:08

DanRibbens reviewed May 22, 2026

View reviewed changes

AlessioGr mentioned this pull request May 22, 2026

docs: add breaking changes docs to migration doc #16723

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor!: remove allowLocalizedWithinLocalized compat flag and PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY env var#16693

refactor!: remove allowLocalizedWithinLocalized compat flag and PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY env var#16693
AlessioGr merged 1 commit into
mainfrom
refactor/localized

AlessioGr commented May 20, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 20, 2026

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

Uh oh!

DanRibbens left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

AlessioGr commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

BREAKING

Why these existed

Uh oh!

github-actions Bot commented May 20, 2026

📦 esbuild Bundle Analysis for payload

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

Uh oh!

DanRibbens left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AlessioGr commented May 20, 2026 •

edited

Loading