Review main Merged

92810[FEATURE] Provide language labels as virtual JavaScript modules

Benjamin Franzke CR +2 V +2 Hard +532 −32 updated 02/17/26, 18:11

Commit message

JavaScript modules can now import language labels as code.
The labels are exposed as a object that offers a `get()` method
and allows to substitute placeholders.
(similar to `lll` from `@typo3/core/lit-helpers`)

This avoids the need for controllers to inject arbitrary labels into
global `TYPO3.lang` configuration, which impeded writing generic
web components. (Often hindered simple adopting by a plain import)

Several hacks like pushing labels to the top frame,
loading labels globally or adding labels to component attributes
have been used previously and will be replaced by this infrastructure.

Virtual JavaScript modules (schema `~label/{language.domain}`)
are created that resolve the labels for the specified language domain,
that is provided after the prefix `~label/`. Technically this mapping is
implemented using an importmap path prefix, which instructs to the
JavaScript engine to append the specified suffix to the mapped prefix.

The labels are allowed to be cached client side with a far future
cache timeout, similar to static resources. We therefore generate
version and locale-specific URLs, to ensure labels can be cached by
the user agent, without requiring explicit cache invalidation.

This also replaces #108627 (which is to be deprecated once usages
have been migrated to this API).

Review

  • Code review CR +2 Done
    • Benjamin Franzke +2
    • Andreas Nedbal +1
    • Benjamin Kott +1
  • Verified V +2 Done
    • Benjamin Franzke +2
    • Andreas Nedbal +1
    • Benjamin Kott +1
    • core-ci +1 CI

Issues 2

Files 24

Show 4 more files

Review log 3848

Show 1723 earlier messages
  1. Benjamin Franzke uploaded patch set 1 02/12/26, 07:11

  2. Andreas Kienast commented on patch set 1 02/12/26, 07:18

    JavaScriptLanguageDomainController.php:60

    What about special UTF-8 characters like umlauts – do we need `mb_strlen` or is `strlen` still fine?
  3. core-ci voted on patch set 1 V -1 02/12/26, 07:23 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95688

  4. Benjamin Franzke commented on patch set 1 02/12/26, 07:33

    JavaScriptLanguageDomainController.php:60 Reply

    content length is about bytes, not (virtual) "character length", therefore `strlen` is correct here.
  5. Andreas Kienast commented on patch set 1 02/12/26, 07:37

    JavaScriptLanguageDomainController.php:60 Reply

    Acknowledged
  6. Benjamin Franzke uploaded patch set 2 V -1 02/12/26, 08:10

  7. core-ci voted on patch set 2 V +1 02/12/26, 08:22 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95691

  8. Tobias Wojtylak commented on patch set 2 02/12/26, 08:52

    language-domain-factory.ts:21

    is `get` really a good/verbose function name. How about using `translate`. The function does more then just return the value for a key

    JavaScriptLanguageDomainController.php:60

    do we really need to set this manually?

    JavaScriptLanguageDomainController.php:62

    Don't we need conditional handling here? something like: `$etag = '"' . md5($javaScriptModuleContents) . '"'; if ($request->getHeaderLine('If-None-Match') === $etag) { return $this->responseFactory->createResponse(304) ->withHeader('ETag', $etag); } `
  9. Tobias Wojtylak commented on patch set 2 V +1 02/12/26, 09:19

    The proposed solution is definitely better than anything that is currently implemented 👍. What I don’t like is that JavaScript code is being constructed and returned in the JavaScriptLanguageDomainController. But that may be a personal preference I checked out and tested the code during the from-wizard rewrite. It worked perfectly.
  10. Benjamin Franzke uploaded patch set 3 V +1 02/12/26, 12:37

  11. Benjamin Franzke uploaded patch set 4 02/12/26, 12:41

  12. Benjamin Franzke uploaded patch set 5 02/12/26, 12:54

  13. core-ci voted on patch set 4 V +1 02/12/26, 12:59 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95717

  14. core-ci voted on patch set 5 V +1 02/12/26, 13:38 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95721

  15. core-ci voted on patch set 3 V -1 02/12/26, 13:44 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95713

  16. Benjamin Franzke uploaded patch set 6 V +1 02/12/26, 13:48

  17. Benjamin Franzke commented on patch set 6 02/12/26, 13:48

    language-domain-factory.ts:21 Reply

    The translation already happened, we do only retrieve the translation. Therefore `get` fits better than an imperative `translate`. (We should not imply an action, when it is *always* a lookup).

    JavaScriptLanguageDomainController.php:60 Reply

    Yes, we do not have a helper for that, We can add that in here later on: > 91599: [FEATURE] Add convenience ResponseFactory methods | https://review.typo3.org/c/Packages/TYPO3.CMS/+/91599

    JavaScriptLanguageDomainController.php:62 Reply

    Thanks, I dropped this. ETag is not relevant, since we use far future caching anyway.
  18. Benjamin Franzke commented on patch set 6 02/12/26, 13:51

    Reply

    I made sure to * only generate the bare minimum, and only via JSON (to avoid writing own clever logic for escaping things) * all functionality is provided via the separate `@typo3/core/language-domain-factory.js` Therefore I think is ok/fine here.
  19. Benni Mack commented on patch set 6 02/12/26, 13:59

    RequestHandler.php:83

    Any reason we need a dynamic listener registered?

    RequestHandler.php:120

    can't we move this out of the request handler?

    JavaScriptModules.php:60

    When introducing a new prefix (such as APP, PKG) I think we should document this for outsiders to understand that this is a special case.
  20. Tobias Wojtylak commented on patch set 6 02/12/26, 14:06

    language-domain-factory.ts:21 Reply

    I disagree placeholders are also being replaced here, if I understand the code correctly. That`s more than just a simple get....

    JavaScriptLanguageDomainController.php:63

    ```suggestion ->withHeader('Cache-Control', 'public, max-age=' . $lifetime) ``` Is there any reason for using private?
  21. Benjamin Franzke commented on patch set 6 02/12/26, 14:32

    language-domain-factory.ts:21 Reply

    It is still a lookup, I think `get()` is fine.

    JavaScriptLanguageDomainController.php:63 Reply

    Private is used to prevent Information disclosure (regarding installed extensions) in shared caches.

    RequestHandler.php:83 Reply

    This should only be evaluated in backend context. For example frontend usage would require a different route. This is very similar to the `prefixWithSitePath` usecase, therefore I've added it here.

    RequestHandler.php:120 Reply

    It is meant for backend requests only. We can, but I do not see a benefit, do you?

    JavaScriptModules.php:60 Reply

    This is meant to be internal (the event is internal).
  22. core-ci voted on patch set 6 V +1 02/12/26, 14:41 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95739

  23. Tobias Wojtylak commented on patch set 6 02/12/26, 14:56

    I think we still have a problem with caching and language switching. When I change the language in the backend to de (it was previously en), I see the cached labels (en).
  1. Benjamin Franzke commented on patch set 6 02/12/26, 15:04

    Reply

    yes, we need to trigger a reload in such (and other) cases. This topic is currently being worked on in the following patch, which is why I wanted to leave this out for now: > 92793: [BUGFIX] Reload backend after extension state changes | https://review.typo3.org/c/Packages/TYPO3.CMS/+/92793 But we can block this patch until that's implemented, fine by me.
  2. Benjamin Franzke commented on patch set 6 02/12/26, 15:28

    Reply

    Pushed in a separate patch for now: > 92823: [WIP][TASK] Refresh backend when language is changed | https://review.typo3.org/c/Packages/TYPO3.CMS/+/92823 but as mentioned, maybe it will be implemented via Oli's patch anyway.
  3. Benjamin Franzke commented on patch set 6 02/12/26, 15:33

    RequestHandler.php:120 Reply

    I can move this and the dynamic listener to a middleware (I do not care), as written above, I've added it here for consistency with `prefixWithSitePath`.
  4. Benjamin Kott commented on patch set 6 CR +1 V +1 02/12/26, 23:14

    i have no hard opinion on the request handler topic. the patch feels good and does what it should.
  5. Benjamin Kott commented on patch set 6 02/12/26, 23:16

    language-domain-factory.ts:22

    yeah, maybe a @todo refactor would also be sufficient
  6. Benjamin Kott commented on patch set 6 02/12/26, 23:33

    generate-label-types.js:43

    it could just generate workspaces.module.d.ts instead of putting it into folders
  7. Benjamin Franzke commented on patch set 6 CR -1 02/12/26, 23:34

    language-domain-factory.ts:22 Reply

    ack, I wanted to remove it (was only for me), but forgot about it. I changed the bullshit part (used `any` before), so I'll remove it.

    generate-label-types.js:27

    @benjamin.kott@outlook.com suggested to use a `.d.ts` file instead of a folder here, which is indeed better, as we do not refer to a package, but a single module here. Will adapt.

    RequestHandler.php:120 Reply

    will move into a middleware
  8. Benjamin Franzke uploaded patch set 7 CR +1 V +1 02/13/26, 09:35

  9. Benjamin Franzke commented on patch set 7 02/13/26, 09:35

    Reply

    Discussed with Benji to include it in here.

    language-domain-factory.ts:22 Reply

    Done

    language-domain-factory.ts:21 Reply

    Hope it is ok for you to keep get here, the reason is basically that we want something real short, as it is used often in templates… Terms like `translate` and `resolve` would be a bit too verbose.

    generate-label-types.js:27 Reply

    Done

    JavaScriptLanguageDomainController.php:63 Reply

    Hope it is ok to mark this as resolved. Feel free to untick, if you have further remarks.

    RequestHandler.php:83 Reply

    Kept (at least for now), since I want to expose this only in backend requests for now (Information Disclosure).

    RequestHandler.php:120 Reply

    Done.

    JavaScriptModules.php:60 Reply

    Added a note in here.
  10. Benjamin Franzke uploaded patch set 8 02/13/26, 09:36

  11. core-ci voted on patch set 8 V +1 02/13/26, 09:51 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95813

  12. Benjamin Kott uploaded patch set 9 V +1 02/13/26, 10:09

  13. core-ci voted on patch set 7 V +1 02/13/26, 10:10 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95812

  14. core-ci voted on patch set 9 V +1 02/13/26, 10:46 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95818

  15. Tobias Wojtylak commented on patch set 8 02/13/26, 12:24

    JavaScriptLanguageDomainController.php:63 Reply

    The specification says: The "private" directive indicates that parts of the response message are intended for a **single user** [...] https://www.w3.org/Protocols/HTTP/Issues/cache-private.html In my opinion translation files that are the same for everyone like (other) assets. But I don’t really mind either, if you think private is the right choice, I’m fine with that..
  16. Tobias Wojtylak commented on patch set 9 02/13/26, 12:36

    label-provider.ts:21

    Is it a good idea to throw an error? JS might crash on missing label How about logging this error via console.error(`Missing label for key: ${key}`); and returning the key (or empty string) as fallback
  17. Benjamin Franzke commented on patch set 9 02/16/26, 07:10

    label-provider.ts:21 Reply

    I think we made this mistake for too long, e.g. to resolve fallbacks when a label was missing. This often resulted in situations that labels could not be translated, because it always used the english fallback. A key-fallback would be even less-useful, since it would only show a label (which is rarely readable at all). Let's be strict for now, we can always get laxer if really needed (the other way around is always harder).

    JavaScriptLanguageDomainController.php:63 Reply

    yup, from a user perspective it could be shared across all logged in users, but as this endpoint is currently *only* accessible for logged-in users, we do not want the data to be visible/retrievable for everyone from a shared cache. I basically want to prevent to introduce the following issue again: https://typo3.org/security/advisory/typo3-core-sa-2019-001
  18. Benjamin Franzke uploaded patch set 10 V +1 02/16/26, 09:09

  19. Tobias Wojtylak commented on patch set 9 02/16/26, 09:12

    label-provider.ts:21 Reply

    Strictness is of course a good thing. However, if an error — for example in a lit template due to a missing string — results in the page no longer rendering properly and the user is left with a broken UI while only seeing an error in the console, then in my opinion we have a serious problem and a really bad user experience. This is my final comment on the matter. If this is indeed the intended behavior, then so be it.
  20. core-ci voted on patch set 10 V +1 02/16/26, 09:20 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95959

  21. Andreas Nedbal voted on patch set 10 CR +1 V +1 02/16/26, 10:45

  22. Benjamin Kott voted on patch set 10 CR +1 V +1 02/16/26, 13:45

  23. Benjamin Franzke voted on patch set 10 CR +2 V +2 02/16/26, 13:53

  24. Benjamin Franzke merged patch set 11 02/16/26, 13:53

  25. Benjamin Franzke wrote 02/17/26, 18:11

    Hashtag added: labels