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

Author: Kocal

src/Translator/CHANGELOG.md

@@ -1,5 +1,54 @@
 # CHANGELOG
 
+## 2.32
+
+-   **[BC BREAK]** Refactor API to use string-based translation keys instead of generated constants.
+
+    Translation keys are now simple strings instead of TypeScript 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 :rocket:
+
+    **Before:**
+    ```typescript
+    import { trans } from '@symfony/ux-translator';
+    import { SYMFONY_GREAT } from '@app/translations';
+
+    trans(SYMFONY_GREAT);
+    ```
+
+    **After:**
+    ```typescript
+    import { createTranslator } from '@symfony/ux-translator';
+    import { messages } from '../var/translations/index.js';
+
+    const { trans } = createTranslator({ messages });
+    trans('symfony.great');
+    ```
+
+    The global functions (`setLocale`, `getLocale`, `setLocaleFallbacks`, `getLocaleFallbacks`, `throwWhenNotFound`)
+    have been replaced by a new `createTranslator()` factory function that returns an object with these methods.
+
+    **Tree-shaking:** While tree-shaking of individual translation keys is no longer possible, modern build tools,
+    caching strategies, and compression techniques (Brotli, gzip) make this negligible in 2025.
+    A future feature will allow filtering dumped translations by pattern for those who need it,
+    further reducing bundle size.
+
+    **For AssetMapper users:** You can remove the following entries from your `importmap.php`:
+    ```php
+    '@app/translations' => [
+        'path' => './var/translations/index.js',
+    ],
+    '@app/translations/configuration' => [
+        'path' => './var/translations/configuration.js',
+    ],
+    ```
+
+    **Note:** This is a breaking change, but the UX Translator component is still experimental.
+
 ## 2.30
 
 -  Ensure compatibility with PHP 8.5

src/Translator/assets/dist/translator_controller.d.ts

@@ -1,29 +1,41 @@
+type MessageId = string;
 type DomainType = string;
 type LocaleType = string;
-type TranslationsType = Record<DomainType, {
-    parameters: ParametersType;
-}>;
+
+type TranslationsType = Record<DomainType, { parameters: ParametersType }>;
 type NoParametersType = Record<string, never>;
 type ParametersType = Record<string, string | number | Date> | NoParametersType;
+
 type RemoveIntlIcuSuffix<T> = T extends `${infer U}+intl-icu` ? U : T;
 type DomainsOf<M> = M extends Message<infer Translations, LocaleType> ? keyof Translations : never;
 type LocaleOf<M> = M extends Message<TranslationsType, infer Locale> ? Locale : never;
-type ParametersOf<M, D extends DomainType> = M extends Message<infer Translations, LocaleType> ? Translations[D] extends {
-    parameters: infer Parameters;
-} ? Parameters : never : never;
+type ParametersOf<M, D extends DomainType> = M extends Message<infer Translations, LocaleType>
+    ? Translations[D] extends { parameters: infer Parameters }
+        ? Parameters
+        : never
+    : never;
+
 interface Message<Translations extends TranslationsType, Locale extends LocaleType> {
-    id: string;
     translations: {
         [domain in DomainType]: {
             [locale in Locale]: string;
         };
     };
 }
-declare function setLocale(locale: LocaleType | null): void;
-declare function getLocale(): LocaleType;
-declare function throwWhenNotFound(enabled: boolean): void;
-declare function setLocaleFallbacks(localeFallbacks: Record<LocaleType, LocaleType>): void;
-declare function getLocaleFallbacks(): Record<LocaleType, LocaleType>;
-declare function trans<M extends Message<TranslationsType, LocaleType>, D extends DomainsOf<M>, P extends ParametersOf<M, D>>(...args: P extends NoParametersType ? [message: M, parameters?: P, domain?: RemoveIntlIcuSuffix<D>, locale?: LocaleOf<M>] : [message: M, parameters: P, domain?: RemoveIntlIcuSuffix<D>, locale?: LocaleOf<M>]): string;
 
-export { type DomainType, type DomainsOf, type LocaleOf, type LocaleType, type Message, type NoParametersType, type ParametersOf, type ParametersType, type RemoveIntlIcuSuffix, type TranslationsType, getLocale, getLocaleFallbacks, setLocale, setLocaleFallbacks, throwWhenNotFound, trans };
+type Messages = Record<MessageId, Message<TranslationsType, LocaleType>>;
+
+declare function getDefaultLocale(): LocaleType;
+declare function createTranslator<TMessages extends Messages>({ messages, locale, localeFallbacks, throwWhenNotFound, }: {
+    messages: TMessages;
+    locale?: LocaleType;
+    localeFallbacks?: Record<LocaleType, LocaleType>;
+    throwWhenNotFound?: boolean;
+}): {
+    setLocale(locale: LocaleType): void;
+    getLocale(): LocaleType;
+    setThrowWhenNotFound(throwWhenNotFound: boolean): void;
+    trans<TMessageId extends keyof TMessages & MessageId, TMessage extends TMessages[TMessageId], TDomain extends DomainsOf<TMessage>, TParameters extends ParametersOf<TMessage, TDomain>>(id: TMessageId, parameters?: TParameters, domain?: RemoveIntlIcuSuffix<TDomain> | undefined, locale?: LocaleOf<TMessage>): string;
+};
+
+export { type DomainType, type DomainsOf, type LocaleOf, type LocaleType, type Message, type MessageId, type Messages, type NoParametersType, type ParametersOf, type ParametersType, type RemoveIntlIcuSuffix, type TranslationsType, createTranslator, getDefaultLocale };

src/Translator/assets/dist/translator_controller.js

@@ -62,12 +62,12 @@ function format(id, parameters, locale) {
 }
 function getPluralizationRule(number, locale) {
   number = Math.abs(number);
-  let _locale2 = locale;
+  let _locale = locale;
   if (locale === "pt_BR" || locale === "en_US_POSIX") {
     return 0;
   }
-  _locale2 = _locale2.length > 3 ? _locale2.substring(0, _locale2.indexOf("_")) : _locale2;
-  switch (_locale2) {
+  _locale = _locale.length > 3 ? _locale.substring(0, _locale.indexOf("_")) : _locale;
+  switch (_locale) {
     case "af":
     case "bn":
     case "bg":
@@ -189,71 +189,78 @@ function formatIntl(id, parameters, locale) {
 }
 
 // src/translator_controller.ts
-var _locale = null;
-var _localeFallbacks = {};
-var _throwWhenNotFound = false;
-function setLocale(locale) {
-  _locale = locale;
-}
-function getLocale() {
-  return _locale || document.documentElement.getAttribute("data-symfony-ux-translator-locale") || // <html data-symfony-ux-translator-locale="en_US">
+function getDefaultLocale() {
+  return document.documentElement.getAttribute("data-symfony-ux-translator-locale") || // <html data-symfony-ux-translator-locale="en_US">
   (document.documentElement.lang ? document.documentElement.lang.replace("-", "_") : null) || // <html lang="en-US">
   "en";
 }
-function throwWhenNotFound(enabled) {
-  _throwWhenNotFound = enabled;
-}
-function setLocaleFallbacks(localeFallbacks) {
-  _localeFallbacks = localeFallbacks;
-}
-function getLocaleFallbacks() {
-  return _localeFallbacks;
-}
-function trans(message, parameters = {}, domain = "messages", locale = null) {
-  if (typeof domain === "undefined") {
-    domain = "messages";
+function createTranslator({
+  messages,
+  locale = getDefaultLocale(),
+  localeFallbacks = {},
+  throwWhenNotFound = false
+}) {
+  const _messages = messages;
+  const _localeFallbacks = localeFallbacks;
+  let _locale = locale;
+  let _throwWhenNotFound = throwWhenNotFound;
+  function setLocale(locale2) {
+    _locale = locale2;
   }
-  if (typeof locale === "undefined" || null === locale) {
-    locale = getLocale();
+  function getLocale() {
+    return _locale;
   }
-  if (typeof message.translations === "undefined") {
-    return message.id;
+  function setThrowWhenNotFound(throwWhenNotFound2) {
+    _throwWhenNotFound = throwWhenNotFound2;
   }
-  const localesFallbacks = getLocaleFallbacks();
-  const translationsIntl = message.translations[`${domain}+intl-icu`];
-  if (typeof translationsIntl !== "undefined") {
-    while (typeof translationsIntl[locale] === "undefined") {
-      locale = localesFallbacks[locale];
-      if (!locale) {
-        break;
-      }
+  function trans(id, parameters = {}, domain = "messages", locale2 = null) {
+    if (typeof domain === "undefined") {
+      domain = "messages";
     }
-    if (locale) {
-      return formatIntl(translationsIntl[locale], parameters, locale);
+    if (typeof locale2 === "undefined" || null === locale2) {
+      locale2 = _locale;
     }
-  }
-  const translations = message.translations[domain];
-  if (typeof translations !== "undefined") {
-    while (typeof translations[locale] === "undefined") {
-      locale = localesFallbacks[locale];
-      if (!locale) {
-        break;
+    const message = _messages[id] ?? null;
+    if (message === null) {
+      return id;
+    }
+    const translationsIntl = message.translations[`${domain}+intl-icu`] ?? void 0;
+    if (typeof translationsIntl !== "undefined") {
+      while (typeof translationsIntl[locale2] === "undefined") {
+        locale2 = _localeFallbacks[locale2];
+        if (!locale2) {
+          break;
+        }
+      }
+      if (locale2) {
+        return formatIntl(translationsIntl[locale2], parameters, locale2);
       }
     }
-    if (locale) {
-      return format(translations[locale], parameters, locale);
+    const translations = message.translations[domain] ?? void 0;
+    if (typeof translations !== "undefined") {
+      while (typeof translations[locale2] === "undefined") {
+        locale2 = _localeFallbacks[locale2];
+        if (!locale2) {
+          break;
+        }
+      }
+      if (locale2) {
+        return format(translations[locale2], parameters, locale2);
+      }
     }
+    if (_throwWhenNotFound) {
+      throw new Error(`No translation message found with id "${id}".`);
+    }
+    return id;
   }
-  if (_throwWhenNotFound) {
-    throw new Error(`No translation message found with id "${message.id}".`);
-  }
-  return message.id;
+  return {
+    setLocale,
+    getLocale,
+    setThrowWhenNotFound,
+    trans
+  };
 }
 export {
-  getLocale,
-  getLocaleFallbacks,
-  setLocale,
-  setLocaleFallbacks,
-  throwWhenNotFound,
-  trans
+  createTranslator,
+  getDefaultLocale
 };

src/Translator/assets/package.json

@@ -27,9 +27,7 @@
     "symfony": {
         "importmap": {
             "intl-messageformat": "^10.5.11",
-            "@symfony/ux-translator": "path:%PACKAGE%/dist/translator_controller.js",
-            "@app/translations": "path:var/translations/index.js",
-            "@app/translations/configuration": "path:var/translations/configuration.js"
+            "@symfony/ux-translator": "path:%PACKAGE%/dist/translator_controller.js"
         }
     },
     "peerDependencies": {