Review main Work in progress

91354[WIP][TASK] Synchronize localized fields from any language

Matthias Vogel CR 0 V -1 Expert +1042 −751 updated 11/15/26, 11:19

Commit message

This is a work-in-progress concept patch. It is pushed for discussion
of the approach and is not meant to be merged in its current state.

Problem
=======

A field with "behaviour.allowLanguageSynchronization" can currently
be in one of three states, stored per field in "l10n_state":

* "custom": the localization keeps its own value
* "parent": the value is taken from the default language record
* "source": the value is taken from the translation source record

The synchronization source is therefore fixed by how a record was
translated. A localization can only follow the default language or
the record it was translated from, never any other localization of
the same record. Installations with language fallback chains (for
example de-CH falling back to de, which falls back to the default
language) cannot express "this field follows de" for a record that
was translated from the default language directly.

The DataMapProcessor implements the three states with a multi-pass
item pipeline (collect, sanitize, enrich, populate, finish) that
resolves parent and source dependencies one IRRE nesting level at a
time. The pipeline knows only those two directions, which makes it
hard to extend.

Intent
======

The state of a synchronized field becomes the uid of the language
the value is taken from:

* the record's own language uid means "custom value"
* 0 means "synchronized from the default language"
* any other language uid means "synchronized from that localization"

A localization can then follow any other localization of the same
record, and chains such as 0 -> de -> de-CH are resolved in order.

Approach
========

New building blocks in EXT:core DataHandling/Localization:

* Localisation: one record of a localisation group, holding the
  persisted row, the row with the data map applied, its language
  and its uid (an integer or a NEW placeholder).
* LocalisationGroup: the localisation origin and all localizations
  of it, keyed by language uid.
* LocalisationGroupService: builds groups for a list of uids,
  through a LocalisationGroupLoader:
  - LocalisationGroupDBLoader reads persisted rows, respecting
    deleted records and the current workspace.
  - LocalisationGroupDataMapLoader lays the submitted data map over
    the persisted rows, including records that are new in the same
    data map, and merges submitted "l10n_state" values.
* LocalisationWorkOrder: builds a graph of "language A synchronizes
  from language B" per field and walks it depth first. Localizations
  depending on the origin are handled first; cycles and orphaned
  chains are processed in a deterministic order. Sources that are
  not part of the group are ignored.

DataMapProcessor::process() is rewritten on top of these: for every
table and every synchronized field it builds the localisation groups
of the submitted records, asks the work order for the processing
sequence and copies the value from the source localization into the
data map ("sync()"). Values that equal the persisted value of the
source are not written.

State holds integer language uids instead of the string states.
Unknown or missing values currently fall back to 0, the default
language.

In FormEngine, the LocalizationStateSelector field wizard renders a
select box with "custom value" plus one entry per existing
localization of the record, instead of the radio buttons for
custom/parent/source. The JavaScript modules disable the field when
another language than the record's own is selected, and swap the
displayed value to the one of the selected language.

Rebased onto main
=================

The rebase keeps everything that main changed in the meantime and
replaces only the item pipeline:

* DataMapProcessor stays an injected, non-shared service with
  process(array $dataMap, $backendUser, $referenceIndexUpdater,
  $correlationId). The relation helpers (synchronizeReferences(),
  synchronizeDirectRelations() and the workspace live-id handling)
  are kept unchanged from main, but not called yet.
* DataMapItem stays as on main and only builds its State through
  the new State::create() signature.
* DataHandler::isParentPointerOfTranslationSynchronized() now
  checks whether the parent pointer field synchronizes from another
  language than the child's own, instead of "is not custom".

Known gaps
==========

This patch is not complete. Before it can leave WIP, at least the
following has to be addressed:

* Existing "l10n_state" values ("custom", "parent", "source") are
  read as 0. Stored custom values would be overwritten with the
  value of the default language on the next save. An upgrade
  wizard converting the stored states is required.
* Relation fields (select, group, MM) and references (inline, file)
  are skipped by sync(). Synchronization of inline children and
  file references does not happen at all at the moment.
* l10n_mode=exclude is not handled by the new flow.
* process() builds localisation groups for every table in the data
  map, including tables without language support, which fails for
  those tables.
* Records with language -1 (all languages) throw in
  LocalisationGroupService.
* State is a public class; removing fromJSON(), isCustomState(),
  isParentState(), isSourceState(), isModified(), isUndefined() and
  changing the signatures to TcaSchema and int is breaking and
  needs either a deprecation path or marking the class internal
  beforehand.
* The default for undefined states should follow the fallback
  chain of the site language instead of always using 0.
* The DataHandler functional tests for language synchronization
  (DataScenarios) are not adapted; only LocalisationWorkOrder has
  unit test coverage. The StateTest unit test still covers the
  string states and fails against the integer based State.
* Debug output and TODO markers are still in place, and labels in
  the field wizard still use the "LLL:EXT:" syntax.

A possible split for a mergeable series: introduce the localisation
group and work order next to the existing processor first, then
switch "l10n_state" to language uids together with an upgrade
wizard, generalize relation synchronization, and adapt FormEngine
last.

Test this change

Run a command in your clone of the TYPO3 Core. Then try what the change does and vote on Verified in Gerrit. How to review a patch

Check out patch set 2
git fetch https://review.typo3.org/Packages/TYPO3.CMS refs/changes/54/91354/2 && git checkout FETCH_HEAD
Cherry-pick onto main
git fetch https://review.typo3.org/Packages/TYPO3.CMS refs/changes/54/91354/2 && git cherry-pick FETCH_HEAD

Review

  • Code review CR 0 Needs a vote
  • Verified V -1 Blocked
    • core-ci -1 CI

Merge conflicts 43

Files 17

Review log 46

  1. Matthias Vogel uploaded patch set 1 10/30/25, 07:43

  2. Matthias Vogel marked it work in progress 10/30/25, 07:44

  3. core-ci voted on patch set 1 V -1 10/30/25, 08:01 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/88084

  4. Benni Mack wrote 10/15/26, 22:33

    Topic set to DataHandler
  5. Benni Mack uploaded patch set 2 V -1 11/15/26, 10:17

  6. core-ci voted on patch set 2 V -1 11/15/26, 11:19 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/114521