SIGN IN SIGN UP
payloadcms / payload UNCLAIMED

Payload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.

0 0 119 TypeScript

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

## 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](https://github.com/payloadcms/payload/pull/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](https://github.com/payloadcms/payload/pull/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
A
Alessio Gravili committed
ebdb3a7fd3c935a202be03f4dda615517425dd4c
Parent: 92d3720
Committed by GitHub <noreply@github.com> on 5/21/2026, 11:08:32 AM