Review main Merged

91066[FEATURE] Use translation domain mappings over LLL as simplified labels

Benni Mack CR +2 V +2 Expert +2091 −75 updated 10/22/25, 14:05

Commit message

This change introduces translation domains as a shorter,
more semantic alternative to verbose file paths for
referencing label resources (XLF files). Translation
domains provide file-independant syntax while maintaining
full backward compatibility with existing LLL: references.

Translation domains are distinct from content translation
(page/record translations) and focus specifically on UI
strings and system messages.

Terminology
-----------

- Translation Domain: Semantic identifier for label
  resources (e.g., "backend.toolbar")
- Label Resource: Physical XLF file containing labels
- Content Translation: Page/record translations (separate
  concept)

The terminology distinguishes UI label localization from
content translation, aligning with existing TYPO3
conventions (LabelFileResolver, LabelBag).

Translation Domain Format
-------------------------

Uses extension key format:
- Extension key plus subdomain: "backend.toolbar"
- Domain format: package[.subdomain...].resource

Examples:
  - backend.messages →
    EXT:backend/Resources/Private/Language/locallang.xlf
  - core.form.tabs →
    EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf
  - felogin.sets.felogin →
    EXT:felogin/Configuration/Sets/Felogin/labels.xlf

Domain names use snake_case (e.g., sudo_mode) instead of
dash-case. UpperCamelCase is internally converted to snake_case.

The LLL: prefix can (should) be omitted when using domains in
LanguageService->sL().

If the input contains a colon (:), it will be treated as a
label reference. Examples:
  - 'LLL:EXT:backend/.../locallang_toolbar.xlf:save'
    (traditional)
  - 'backend.toolbar:save' (new)
  - 'Save' (plain string, returned as-is)

Behavior:
- With LLL: prefix: Returns empty string if no colon found
  (invalid reference)
- Without LLL: prefix: Returns input as-is if no colon
  found (constant label)

Architecture
------------

TranslationDomainMapper:
  - Maps domains to/from label resource file references
  - Handles package resolution (extension keys, composer
    names)
  - Transforms paths (UpperCamelCase to snake_case,
    nesting)
  - Integrates BeforeLabelResourceResolvedEvent for custom
    mapping
  - Orchestrates caching of file locations on a
    per-package level
  - Provides findLabelResourcesInPackageGroupedByLocale()
    for discovering available translations

LabelFileResolver:
  - Discovers label resource files within packages
  - Scans Resources/Private/Language/ and
    Configuration/Sets/
  - Filters locale-specific variants
  - Used by CLI command for resource discovery
  - Handles locale-specific file resolution
  - Manages resource override detection

LocalizationFactory:
  - Enhanced to accept both translation domains and file
    references
  - Orchestrates label loading and caching
  - Used by CLI command for counting labels in resources

LanguageService:
  - sL() method now accepts label references with or
    without LLL: prefix
  - If input contains a colon, it's treated as a label
    reference
  - Otherwise, behavior depends on presence of LLL: prefix

CLI Command
-----------

New command: language:domain:list
  - Lists all translation domains and their file locations
  - Shows available translations for each resource
  - Displays label count for each resource
  - Supports filtering by extension
  - Options: --all (include inactive), --extension=<key>

Usage Examples:
  php bin/typo3 language:domain:list
  php bin/typo3 language:domain:list --extension=backend

Output columns:
  - Translation Domain: The domain identifier
  - Label Resource: The file path (EXT: syntax)
  - # Labels: Number of translatable labels in the resource

PSR-14 Event
------------

BeforeLabelResourceResolvedEvent:
  - Fired after translation domain resolution is done
  - Use cases: custom naming conventions, dynamic
    resolution

Integration
-----------

The translation domain mapper is wired into
LocalizationFactory::getParsedData() - resolves domains
before caching.

Backward Compatibility
----------------------

All existing code continues to work:
  $GLOBALS['LANG']->sL(
    'LLL:EXT:backend/.../locallang.xlf:save'
  );

New syntax is optional:
  $GLOBALS['LANG']->sL('backend.toolbar:menu.item');

It is now possible to keep the same "domain" while
moving or changing the file names, a
"TranslationDomainAliasTest" is added to show this example.

Review

  • Code review CR +2 Done
    • Benjamin Kott +2
    • Georg Ringer +1
    • Garvin Hicking +1
  • Verified V +2 Done
    • Benjamin Kott +2
    • Georg Ringer +1
    • Garvin Hicking +1
    • core-ci +1 CI

Issues 1

Files 42

Show 22 more files

Review log 6087

Show 4662 earlier messages
  1. Benni Mack uploaded patch set 1 10/14/25, 22:58

  2. core-ci voted on patch set 1 V -1 10/14/25, 23:17 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86662

  3. Garvin Hicking uploaded patch set 2 V -1 10/15/25, 06:29

  4. Garvin Hicking uploaded patch set 3 10/15/25, 06:31

  5. Garvin Hicking commented on patch set 3 V -1 10/15/25, 06:40

    My backend no longer works with this, I get an exception like this when calling "Web > List" or "Web > Page": ``` (1/1) #1729000001 InvalidArgumentException File path must start with "EXT:" at TYPO3\CMS\Core\Localization\LabelDomainMapper->extractExtensionKey('vendor/typo3/cms-backend/Resources/Private/Language/SudoMode.xlf') ``` Somehow a `vendor/` lands up in my resolved file name? I am using monorepo with composer wrapper (Jochen Roths TDK), that must surely affect this and would need addressing. Stacktrace: https://gist.github.com/garvinhicking/64a75a9ae63184df7a9aa45eea4042ea
  6. core-ci voted on patch set 3 V -1 10/15/25, 06:43 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86678

  7. Mathias Brodala commented on patch set 3 10/15/25, 06:46

    Services.yaml:58

    IMO this should be "l10n:domain:list" or "l10n:domains" or "translation:domains". The term "label" is too generic to be easily understood without context.
  8. core-ci voted on patch set 2 V -1 10/15/25, 06:49 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86677

  9. Benni Mack commented on patch set 3 10/15/25, 06:57

    Services.yaml:58 Reply

    I thought about this as well... I had translations in the first run, but people misunderstand translations with content translation (translations with connected and copy mode)
  10. Garvin Hicking commented on patch set 3 10/15/25, 07:02

    Similar happens on CLI `label:domain:list`: ``` Label domains in active extensions ================================== In LabelDomainMapper.php line 295: File path must start with "EXT:" ```

    Reply

    In `LabelDomainMaper->findLabelResourcesInPackage()` I can partially patch this fore core extensions with a very ugly hack: ``` if (str_starts_with($file, Environment::getExtensionsPath() . '/')) { $file = 'EXT:' . substr($file, strlen(Environment::getExtensionsPath()) + 1); } elseif (str_starts_with($file, Environment::getFrameworkBasePath() . '/')) { $file = 'EXT:' . substr($file, strlen(Environment::getFrameworkBasePath()) + 1); } elseif (str_starts_with($file, Environment::getProjectPath() . '/vendor/')) { // @todo - wrapped composer installations like https://github.com/ochorocho/tdk do this $file = 'EXT:' . substr($file, strlen(Environment::getProjectPath() . '/vendor') + 1); // Yes, it gets even more hacky than that: $file = str_replace('typo3/cms-', '', $file); // I can top this: $fileParts = explode('/', $file); // ... turns 'typo3/cms-fluid-styled-content' into 'fluid_styled_content' $fileParts[0] = str_replace('-', '_', $fileParts[0]); $file = implode('/', $fileParts); } elseif (str_starts_with($file, Environment::getProjectPath() . '/')) { $file = substr($file, strlen(Environment::getProjectPath()) + 1); } ``` However this chokes on third-party extensions like `bk2k/bootstrap-package` which gets detected as `bk2k`. And theoreticcaly a TYPO3 extension key could be 'bar' while the directory name be `anything/foo` so no straight mapping might be possible on a filesystem basis, without evaluating all the composer JSONs?
  11. Garvin Hicking commented on patch set 3 10/15/25, 07:47

    BeforeLabelResourceResolvedEvent.php:21

    ```suggestion * Event that is fired after a file name has been mapped to a label domain for all files ```

    LabelDomainMapper.php:63

    These can be readonly I guess?

    Feature-93334-LabelDomainMapping.rst:66

    Did I read this right that the file could also be called just "toolbar.xlf"? In case we want to phase out "locallang..." totally, should we already reference the shorter filenames here already?

    Feature-93334-LabelDomainMapping.rst:117

    "Ignored" might be read as "not supported". Maybe better say "Locale prefixes are irrelevant for the resource identifier resolving. These prefixes will internally be properly evaluated for locale-based translations" (something along these words, it's not great yet I admit)

    Feature-93334-LabelDomainMapping.rst:133

    Using the FQCN here would allow API linking in the docs

    Feature-93334-LabelDomainMapping.rst:153

    This is so helpful. In the past I wrote several CI tests that validate used message files. It would be great if the output of that command could also be available as JSON, so that the CI could read that dynamically and not need to evaluate some CLI table output.
  12. Benni Mack uploaded patch set 4 V -1 10/15/25, 08:40

  13. core-ci voted on patch set 4 V -1 10/15/25, 08:53 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86698

  14. Benjamin Kott commented on patch set 4 10/15/25, 09:41

    Services.yaml:58 Reply

    i agree here, i think we already have "language" with "language:update" assigned. we should find a general place, but i also feel that labels is too generic,and does not reflect the context really "language.domains.list" or move it into translations. i would prefer a longer key, but that really tells me what i am looking at. if we extend this here we should also talk about the catalogue at some point so i could enable new languages via cli. we are really managing the system here, so i guess the confusion comes from spoken context - while you are using it including the descriptions it think it´s safe that there are no confusions, as we are not managing content via cli except from imports and exports.
  15. Benjamin Kott commented on patch set 4 10/15/25, 09:46

    Feature-93334-LabelDomainMapping.rst:65

    i am not sure about this one, i´ve also noticed this using the cli that atleast for core puts out "typo3/cms-backend" instead of "backend" it feels overly complex, while i think we can maybe support it we should prefer the shorten output and also display this to the users and only fall back to the full composer package name when there is no extension key set.
  16. Benjamin Kott commented on patch set 4 10/15/25, 10:13

    RecordListController.php:628

    usage of composer namespace, other places use extension
  17. Benni Mack uploaded patch set 5 V -1 10/15/25, 12:07

  18. Benni Mack commented on patch set 5 10/15/25, 12:09

    Reply

    I think we should avoid this logic, and go back to just use extension keys.

    RecordListController.php:628 Reply

    Done

    BeforeLabelResourceResolvedEvent.php:21 Reply

    Done

    LabelDomainMapper.php:63 Reply

    Done

    Feature-93334-LabelDomainMapping.rst:65 Reply

    Done

    Feature-93334-LabelDomainMapping.rst:117 Reply

    Done

    Feature-93334-LabelDomainMapping.rst:133 Reply

    Done
  19. core-ci voted on patch set 5 V -1 10/15/25, 12:27 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86717

  20. Garvin Hicking commented on patch set 5 10/15/25, 12:39

    Reply

    This feels a bit connected to the PKG System Resource API resolve, but the other way round. There requiring composer keys would be beneficial, and here having composer keys is an issue. I feel like we should align this... Fixating this on extension keys would block retiring extension keys in the future if we might make a `composer.json` mandatory. Maybe we should even combine this and also use "PKG:..." here already?! @typo3@helhum.io ?
  21. Benni Mack uploaded patch set 6 V -1 10/15/25, 12:45

  22. core-ci voted on patch set 6 V -1 10/15/25, 13:10 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86722

  23. Benni Mack commented on patch set 6 10/15/25, 13:18

    Reply

    The point of this is to easy to syntax for integrators and people writing label references. I asked myself this question (also see @benjamin.kott@outlook.com comment here from today): What's better in terms of understanding and readability? - backend.toolbar:button.save - typo3/cms-backend.toolbar:button.save - PKG:typo3/cms-backend.toolbar:button.save - EXT:backend/Resources/Private/Language/locallang_toolbar.xlf:button.save The point here is not the reference to a specific "file", as it is with system resources API.the first one is VERY VERY similar to what Symfony/Contao/Sulu developers are used to already.
  24. Benni Mack uploaded patch set 7 V -1 10/15/25, 13:23

  25. Benni Mack uploaded patch set 8 10/15/25, 13:36

  26. core-ci voted on patch set 7 V -1 10/15/25, 13:42 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86729

  27. core-ci voted on patch set 8 V -1 10/15/25, 13:55 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86730

  28. Garvin Hicking commented on patch set 8 10/15/25, 14:03

    Reply

    Ack. Yeah I understand and see why the extension key would be the lean choice.
  29. Benni Mack uploaded patch set 9 V -1 10/15/25, 14:03

  30. Benni Mack commented on patch set 9 10/15/25, 14:04

    Services.yaml:58 Reply

    Hey @mbrodala@pagemachine.de - I changed it to language:domain:list - wdyt?
  31. Garvin Hicking commented on patch set 9 10/15/25, 14:06

    Reply

    Unresolving this to keep in mind that composer mode has issues with the resolving yet
  32. core-ci voted on patch set 9 V -1 10/15/25, 14:14 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86731

  33. Benni Mack uploaded patch set 10 V -1 10/15/25, 14:26

  34. core-ci voted on patch set 10 V -1 10/15/25, 14:36 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86733

  35. Georg Ringer uploaded patch set 11 V -1 10/15/25, 14:37

  36. core-ci voted on patch set 11 V -1 10/15/25, 14:46 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86734

  37. Benni Mack uploaded patch set 12 V -1 10/15/25, 15:28

  38. core-ci voted on patch set 12 V -1 10/15/25, 15:39 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86743

  39. Mathias Brodala commented on patch set 12 10/16/25, 06:34

    Services.yaml:58 Reply

    Way better, thanks!
  40. Benni Mack uploaded patch set 13 V -1 10/16/25, 09:56

  41. Benni Mack commented on patch set 13 10/16/25, 10:05

    Feature-93334-LabelDomainMapping.rst:66 Reply

    I kept it here because it helps people to understand the previous file structure. I've documented this in other places now that toolbar.xlf takes precedences over locallang_toolbar.xlf etc.
  42. Garvin Hicking commented on patch set 13 V +1 10/16/25, 10:06

    Reply

    works now.

    Feature-93334-LabelDomainMapping.rst:66 Reply

    Done

    Feature-93334-LabelDomainMapping.rst:153 Reply

    I'll provide this as a follow-up.
  43. core-ci voted on patch set 13 V +1 10/16/25, 10:08 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86799

  44. Garvin Hicking commented on patch set 13 V 0 10/16/25, 10:26

    LanguageDomainListCommand.php:134

    ```suggestion ]); // Make the "Translations" column only emit three 2-letter languages per row $table->setColumnMaxWidth(2, 11); ```
  45. Benjamin Kott commented on patch set 13 CR -1 10/16/25, 10:30

    LanguageDomainListCommand.php:113

    i think we should drop the locales here for now, it clutters the view. and makes it more or less unreadable. i think it´s better when this command only lists the essential mapping information and the label count in the base file. we should provide more commands around that in a dedicated patch, where we can debug a single domain and their overwrite resources, that should also consider overrides and installed language packs.
  46. Garvin Hicking commented on patch set 13 10/16/25, 10:32

    The CLI output lists: ``` | core.iso.countries | EXT:core/Resources/Private/Language/Iso/zh-HK.countries.xlf | en, af, ar, ... | 1143 | ``` So the "zh-HK" (last file alphabetically) file is used here. I wonder if it should list only "countries.xlf" here? I have third party extensions with translations (da, de) but fr these the proper "locallang.xlf" is shown... probably because alphabetically "en" comes last and this resets something? Not sure if this is of importance or just a CLI output matter.
  47. Garvin Hicking commented on patch set 13 10/16/25, 10:33

    LanguageDomainListCommand.php:113 Reply

    Please check out the suggested patch I made for exactly this output reason. With that it's IMO bearable and has a benefit to be listed...
  48. Benjamin Kott commented on patch set 13 10/16/25, 10:45

    Feature-93334-LabelDomainMapping.rst:33

    drop LLL:

    Feature-93334-LabelDomainMapping.rst:54

    drop LLL:

    Feature-93334-LabelDomainMapping.rst:137

    drop LLL:

    Feature-93334-LabelDomainMapping.rst:140

    drop LLL:
  49. Benjamin Kott commented on patch set 13 10/16/25, 10:47

    LanguageDomainListCommand.php:113 Reply

    i´ve seen the comment - i think it should be completely removed for now, i see a lot of benefit in more data being available but maybe we need a different command / usecase for this. the main use case here is to get basic information so we should also restrict it to what we actually need here. i think domain to resource mapping and count should be fine here.
  50. Benni Mack uploaded patch set 14 CR -1 V +1 10/16/25, 10:52

  51. Benjamin Kott commented on patch set 13 CR -1 10/16/25, 10:53

    LocalizationUtility.php:51

    i think we should also support full domain names here like core.something even without adding LLL: or adding an extension key.
  52. core-ci voted on patch set 14 V +1 10/16/25, 11:03 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86805

  53. Benni Mack uploaded patch set 15 V +1 10/16/25, 12:16

  54. Benni Mack commented on patch set 15 10/16/25, 12:17

    Reply

    Done

    LanguageDomainListCommand.php:113 Reply

    agree. removed this for the time being

    LanguageDomainListCommand.php:134 Reply

    Done

    Feature-93334-LabelDomainMapping.rst:33 Reply

    Done

    Feature-93334-LabelDomainMapping.rst:54 Reply

    Done

    Feature-93334-LabelDomainMapping.rst:137 Reply

    Done

    Feature-93334-LabelDomainMapping.rst:140 Reply

    Done

    LocalizationUtility.php:51 Reply

    This can be done in a separate change, as we then would need to extract and validate the domain name at this very point.
  55. core-ci voted on patch set 15 V +1 10/16/25, 12:26 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86808

  56. Benjamin Kott voted on patch set 15 CR +1 V +1 10/16/25, 12:40

  57. Christian Kuhn commented on patch set 15 10/16/25, 12:43

    i've partially read through this and would like to give testing a shot soon.
  58. Benjamin Kott commented on patch set 15 V 0 CR -1 10/16/25, 12:49

    the count of labels is off, and need to be checked again, it reports above 3k labels for a file with 4 labels.
  59. Benni Mack uploaded patch set 16 CR -1 V +1 10/16/25, 13:42

  60. Benni Mack commented on patch set 17 10/16/25, 14:03

    Published edit on patch set 16.
  61. core-ci voted on patch set 16 V -1 10/16/25, 14:08 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86817

  62. Benni Mack uploaded patch set 18 10/16/25, 14:22

  1. core-ci voted on patch set 17 V -1 10/16/25, 14:31 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86819

  2. core-ci voted on patch set 18 V -1 10/16/25, 14:47 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86822

  3. Benni Mack uploaded patch set 19 V -1 10/16/25, 15:12

  4. core-ci voted on patch set 19 V -1 10/16/25, 15:32 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86824

  5. Benni Mack uploaded patch set 20 V -1 10/16/25, 15:35

  6. Benni Mack uploaded patch set 21 10/16/25, 15:41

  7. Benni Mack commented on patch set 22 10/16/25, 15:43

    Published edit on patch set 21.
  8. core-ci voted on patch set 20 V -1 10/16/25, 16:00 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86826

  9. core-ci voted on patch set 21 V -1 10/16/25, 16:04 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86827

  10. core-ci voted on patch set 22 V -1 10/16/25, 16:08 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86828

  11. Benni Mack uploaded patch set 23 V -1 10/16/25, 16:10

  12. core-ci voted on patch set 23 V -1 10/16/25, 16:27 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86833

  13. Benni Mack uploaded patch set 24 V -1 10/16/25, 16:54

  14. core-ci voted on patch set 24 V +1 10/16/25, 17:04 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86834

  15. Garvin Hicking uploaded patch set 25 V +1 10/16/25, 19:52

  16. Garvin Hicking uploaded patch set 26 10/16/25, 19:54

  17. Garvin Hicking uploaded patch set 27 10/16/25, 19:56

  18. core-ci voted on patch set 25 V -1 10/16/25, 20:07 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86843

  19. core-ci voted on patch set 26 V -1 10/16/25, 20:08 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86844

  20. core-ci voted on patch set 27 V +1 10/16/25, 20:09 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/86845

  21. Garvin Hicking commented on patch set 27 CR +1 V +1 10/16/25, 20:23

    💪
  22. Georg Ringer voted on patch set 27 CR +1 V +1 10/17/25, 05:56

  23. Benjamin Kott voted on patch set 27 CR +2 V +2 10/17/25, 07:31

  24. Benjamin Kott merged patch set 28 10/17/25, 07:31

  25. Lina Wolf commented on patch set 28 10/22/25, 14:05

    Unresolved

    We should adjust the changelog example: https://review.typo3.org/c/Packages/TYPO3.CMS/+/91162