feat!: auto-removes localized property from localized fields within other localized fields #7933
Merged
Conversation
This was referenced Feb 11, 2025
Merged
AlessioGr
added a commit
that referenced
this pull request
May 21, 2026
…AD_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](#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](#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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Payload localization works on a field-by-field basis. As you can nest fields within other fields, you could potentially nest a localized field within a localized field—but this would be redundant and unnecessary. There would be no reason to define a localized field within a localized parent field, given that the entire data structure from the parent field onward would be localized.
Up until this point, Payload would allow you to nest a localized field within another localized field, and this might have worked in MongoDB but it will throw errors in Postgres.
Now, Payload will automatically remove the
localized: trueproperty from sub-fields withinsanitizeFieldsif a parent field is localized.This could potentially be a breaking change if you have a configuration with MongoDB that nests localized fields within localized fields.
Migrating
You probably only need to migrate if you are using MongoDB, as there, you may not have noticed any problems. But in Postgres or SQLite, this would have caused issues so it's unlikely that you've made it too far without experiencing issues due to a nested localized fields config.
In the event you would like to keep existing data in this fashion, we have added a
compatibility.allowLocalizedWithinLocalizedflag to the Payload config, which you can set totrue, and Payload will then disable this new sanitization step.Set this compatibility flag to
trueonly if you have an existing Payload MongoDB database from pre-3.0, and you have nested localized fields that you would like to maintain without migrating.