[Translator] Refactor API to use string-based translation keys instead of generated constants #3208

Kocal · 2025-12-03T21:12:14Z

Q	A
Bug fix?	no
New feature?	yes
Deprecations?	no
Documentation?	yes
Issues	Fix #2619
License	MIT

This pull request introduces a breaking change to the UX Translator component, refactoring its API to use string-based translation keys instead of generated constants.

The main advantages are:

You can now use exactly the same translation keys as in your Symfony PHP code
Simpler and more readable code
No need to memorize generated constant names
No need to import translation constants: smaller files
And you can still get autocompletion and type-safety 🚀

Before:

import { trans } from '@symfony/ux-translator';
import { SYMFONY_GREAT } from '@app/translations';

trans(SYMFONY_GREAT);

After:

import { createTranslator } from '@symfony/ux-translator';
import { messages } from '../var/translations/index.js';

const { trans } = createTranslator({ messages });
trans('symfony.great');

Changing the import from @app/translations to ../var/translations/index.js allows IDEs and other tools to correctly interpret these files, which is required to make trans() type-safe.

It also make the configuration easier for AssetMapper users, they must now remove these entries from their importmap.php:

   '@app/translations' => [
        'path' => './var/translations/index.js',
    ],
    '@app/translations/configuration' => [
        'path' => './var/translations/configuration.js',
    ],

github-actions · 2025-12-03T21:12:39Z

📊 Packages dist files size difference

Thanks for the PR! Here is the difference in size of the packages dist files between the base branch and the PR.
Please review the changes and make sure they are expected.

File	Before (Size / Gzip)	After (Size / Gzip)
Translator
`translator_controller.d.ts`	`1.84 kB` / `615 B`	`2.01 kB`^{+10% 📈} / `696 B`^{+13% 📈}
`translator_controller.js`	`7.92 kB` / `2.27 kB`	`8.11 kB`^{+2% 📈} / `2.31 kB`^{+2% 📈}

Copilot

Pull request overview

This PR introduces a breaking change to the UX Translator component, refactoring the API from generated constants to string-based translation keys. This change aligns the JavaScript/TypeScript API more closely with Symfony's PHP translation API, allowing developers to use the exact same translation keys in both environments while maintaining type-safety and autocompletion.

Key changes:

Replaced global translation functions with a createTranslator() factory that returns a translator instance
Changed from importing translation constants to using string-based keys directly
Updated generated files to export a messages object and localeFallbacks instead of individual constants
Removed the need for @app/translations and @app/translations/configuration importmap entries

Reviewed changes

Copilot reviewed 29 out of 32 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
`src/Translator/src/TranslationsDumper.php`	Refactored to generate a single messages object instead of individual constants; removed constant name generation logic
`src/Translator/assets/src/translator_controller.ts`	Replaced global functions with `createTranslator()` factory function returning scoped translator instance
`src/Translator/assets/src/types.d.ts`	Extracted type definitions into separate file; added `Messages` and `MessageId` types
`src/Translator/assets/test/unit/translator_controller.test.ts`	Updated all tests to use new `createTranslator()` API pattern
`src/Translator/tests/TranslationsDumperTest.php`	Updated test assertions to match new output format with messages object
`src/Translator/doc/index.rst`	Updated documentation to reflect new API usage and removed AssetMapper warnings
`src/Translator/CHANGELOG.md`	Added comprehensive changelog entry explaining the breaking change
`ux.symfony.com/templates/ux_packages/translator.html.twig`	Updated demo to use lowercase snake_case translation keys instead of UPPER_CASE constants
`ux.symfony.com/assets/translator.js`	Refactored to use `createTranslator()` with direct import from var/translations
`ux.symfony.com/importmap.php`	Removed `@app/translations` entries as they're no longer needed
`apps/encore/assets/translator.js`	Updated to new API pattern with `createTranslator()`
`apps/e2e/assets/translator.js`	Updated to new API pattern and exports `trans` from main app file
`apps/e2e/templates/ux_translator/*.html.twig`	Converted all template examples from constants to string-based keys

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ux.symfony.com/templates/ux_packages/translator.html.twig

src/Translator/doc/index.rst

apps/e2e/assets/app.js

ux.symfony.com/templates/ux_packages/translator.html.twig

src/Translator/assets/test/unit/translator_controller.test.ts

apps/encore/assets/translator.js

apps/encore/assets/app.js

apps/e2e/assets/translator.js

…d of generated constants

Kocal · 2025-12-03T23:18:13Z

apps/e2e/importmap.php

-    '@app/translations' => [
-        'path' => './var/translations/index.js',
-    ],
-    '@app/translations/configuration' => [
-        'path' => './var/translations/configuration.js',
-    ],


No need for these lines anymore! 🚀

Kocal · 2025-12-03T23:21:59Z

src/Translator/assets/src/translator_controller.ts

+    return {
+        setLocale,
+        getLocale,
+        setThrowWhenNotFound,
+        trans,
+    };


Here I'm returning an object of methods instead of creating a Translator instance (implying this class exists), because:

I want users being able to use const { trans } = createTranslator(), with an instance it does not work because this context is lost

It looks like a bit to the React Hooks or Vue Use systems, which has been pretty common for years in the JS ecosystem

Kocal · 2025-12-03T23:23:02Z

src/Translator/doc/index.rst

-If you're using WebpackEncore, install your assets and restart Encore (not
-needed if you're using AssetMapper):
-
-.. code-block:: terminal
-
-    $ npm install --force
-    $ npm run watch
-
-.. note::
-
-    For more complex installation scenarios, you can install the JavaScript assets through the `@symfony/ux-translator npm package`_
-


I moved this part, into a dedicated section below

Kocal · 2025-12-03T23:23:47Z

src/Translator/doc/index.rst

-    import { trans, getLocale, setLocale, setLocaleFallbacks } from '@symfony/ux-translator';
-    import { localeFallbacks } from '../var/translations/configuration';
+    import { createTranslator } from '@symfony/ux-translator';
+    import { messages, localeFallbacks } from '../var/translations/index.js';


Btw, the index.js here is important, that's for the AssetMapper

Kocal · 2025-12-03T23:24:52Z

src/Translator/doc/index.rst

+Q&A
+---

-When installing with AssetMapper, Flex will add a few new items to your ``importmap.php``
-file. 2 of the new items are::
+What about bundle size?
+~~~~~~~~~~~~~~~~~~~~~~~

-    '@app/translations' => [
-        'path' => 'var/translations/index.js',
-    ],
-    '@app/translations/configuration' => [
-        'path' => 'var/translations/configuration.js',
-    ],
+All your translations (extracted from the configured domains) are included in the generated ``var/translations/index.js`` file,
+which means they will be included in your final JavaScript bundle).

-These are then imported in your ``assets/translator.js`` file. This setup is
-very similar to working with WebpackEncore. However, the ``var/translations/index.js``
-file contains *every* translation in your app, which is not ideal for production
-and may even leak translations only meant for admin areas. Encore solves this via
-tree-shaking, but the AssetMapper component does not. There is not, yet, a way to
-solve this properly with the AssetMapper component.
+However, modern build tools, caching strategies, and compression techniques (Brotli, gzip)
+make this negligible in 2025. Additionally, a future feature will allow filtering dumped
+translations by pattern for those who need to further reduce bundle size.


I thought this part was important, since one of my primary concern when creating UX Translator, was about tree-shaking etc.

Kocal · 2025-12-03T23:26:06Z

src/Translator/src/TranslationsDumper.php

-    private function generateConstantName(string $translationId): string
-    {
-        $translationId = s($translationId)->ascii()->snake()->upper()->replaceMatches('/^(\d)/', '_$1')->toString();
-        $prefix = 0;
-        do {
-            $constantName = $translationId.($prefix > 0 ? '_'.$prefix : '');
-            ++$prefix;
-        } while ($this->alreadyGeneratedConstants[$constantName] ?? false);
-
-        $this->alreadyGeneratedConstants[$constantName] = true;
-
-        return $constantName;
-    }


I didn't make Blackfire profiles, but removing this code will surely help to improve performances when dealing with a ton of translations.

Kocal · 2025-12-03T23:27:08Z

ux.symfony.com/config/packages/asset_mapper.yaml

+        missing_import_mode: strict
+
+when@prod:
+    framework:
+        asset_mapper:
+            missing_import_mode: warn


Applied symfony/recipes#1347

Kocal · 2025-12-03T23:29:19Z

src/Translator/tests/bootstrap.php

Backported changes from 3.x: c96987f

Configuring the Application to not auto-exit anymore fixed an issue where PHPUnit exited. Thus, no tests were run.

smnandre · 2025-12-04T00:58:48Z

I’m speechless. Thank you 🙇

Kocal self-assigned this Dec 3, 2025

carsonbot added Documentation Improvements or additions to documentation Feature New Feature Status: Needs Review Needs to be reviewed labels Dec 3, 2025

Kocal mentioned this pull request Dec 3, 2025

[Translator] Message key syntax and object const for javascript UX Translator #2619

Closed

Kocal force-pushed the translator-strings-as-keys branch 2 times, most recently from 8c34c38 to afcb2d9 Compare December 3, 2025 22:18

Kocal added the Translator label Dec 3, 2025

Kocal requested a review from Copilot December 3, 2025 22:23

Copilot started reviewing on behalf of Kocal December 3, 2025 22:24 View session

Copilot finished reviewing on behalf of Kocal December 3, 2025 22:25

Copilot AI reviewed Dec 3, 2025

View reviewed changes

Kocal added 4 commits December 3, 2025 23:35

[Translator] Refactor API to use string-based translation keys instea…

2519033

…d of generated constants

Update E2E app

fc0ccfa

Update ux.symfony.com app

d77ffc0

Update Encore app

a8de99d

Kocal force-pushed the translator-strings-as-keys branch from afcb2d9 to a8de99d Compare December 3, 2025 22:35

Kocal requested review from WebMamba and smnandre December 3, 2025 22:36

Kocal commented Dec 3, 2025

View reviewed changes

Kocal mentioned this pull request Dec 3, 2025

[UXTranslator] Add recipe for 2.32 symfony/recipes#1498

Merged

Kocal merged commit aaa5c9d into symfony:2.x Dec 5, 2025
49 of 59 checks passed

Uh oh!

[Translator] Refactor API to use string-based translation keys instead of generated constants #3208

[Translator] Refactor API to use string-based translation keys instead of generated constants #3208

Uh oh!

Conversation

Kocal commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Packages dist files size difference

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Kocal Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smnandre commented Dec 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Kocal commented Dec 3, 2025 •

edited

Loading

github-actions bot commented Dec 3, 2025 •

edited

Loading

Kocal Dec 3, 2025 •

edited

Loading

Kocal Dec 3, 2025 •

edited

Loading