[Translator] add throwWhenNotFound method

Author: Crovitche-1623

src/Translator/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.20.0
+
+-   Add option to throw an exception when a translation is missing.
+
 ## 2.19.0
 
 -   Add configuration to filter dumped translations by domain.

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

@@ -21,6 +21,7 @@ export interface Message<Translations extends TranslationsType, Locale extends L
 }
 export declare function setLocale(locale: LocaleType | null): void;
 export declare function getLocale(): LocaleType;
+export declare function throwWhenNotFound(enabled: boolean): void;
 export declare function setLocaleFallbacks(localeFallbacks: Record<LocaleType, LocaleType>): void;
 export declare function getLocaleFallbacks(): Record<LocaleType, LocaleType>;
-export 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 declare function trans<M extends Message<TranslationsType, LocaleType>, D extends DomainsOf<M>, P extends ParametersOf<M, D>, T>(...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;

src/Translator/assets/dist/translator_controller.js

@@ -220,6 +220,7 @@ function getPluralizationRule(number, locale) {
 
 let _locale = null;
 let _localeFallbacks = {};
+let _throwWhenNotFound = false;
 function setLocale(locale) {
     _locale = locale;
 }
@@ -229,6 +230,9 @@ function getLocale() {
         document.documentElement.lang ||
         'en');
 }
+function throwWhenNotFound(enabled) {
+    _throwWhenNotFound = enabled;
+}
 function setLocaleFallbacks(localeFallbacks) {
     _localeFallbacks = localeFallbacks;
 }
@@ -270,7 +274,10 @@ function trans(message, parameters = {}, domain = 'messages', locale = null) {
             return format(translations[locale], parameters, locale);
         }
     }
+    if (_throwWhenNotFound) {
+        throw new Error(`No translation message with id "${message.id}" is found.`);
+    }
     return message.id;
 }
 
-export { getLocale, getLocaleFallbacks, setLocale, setLocaleFallbacks, trans };
+export { getLocale, getLocaleFallbacks, setLocale, setLocaleFallbacks, throwWhenNotFound, trans };

src/Translator/assets/src/translator.ts

@@ -38,6 +38,7 @@ import { format } from './formatters/formatter';
 
 let _locale: LocaleType | null = null;
 let _localeFallbacks: Record<LocaleType, LocaleType> = {};
+let _throwWhenNotFound = false;
 
 export function setLocale(locale: LocaleType | null) {
     _locale = locale;
@@ -52,6 +53,10 @@ export function getLocale(): LocaleType {
     );
 }
 
+export function throwWhenNotFound(enabled: boolean): void {
+    _throwWhenNotFound = enabled;
+}
+
 export function setLocaleFallbacks(localeFallbacks: Record<LocaleType, LocaleType>): void {
     _localeFallbacks = localeFallbacks;
 }
@@ -162,5 +167,9 @@ export function trans<
         }
     }
 
+    if (_throwWhenNotFound) {
+        throw new Error(`No translation message with id "${message.id}" is found.`);
+    }
+
     return message.id;
 }

src/Translator/assets/test/translator.test.ts

@@ -4,6 +4,7 @@ import {
     type NoParametersType,
     setLocale,
     setLocaleFallbacks,
+    throwWhenNotFound,
     trans,
 } from '../src/translator';
 
@@ -387,6 +388,27 @@ describe('Translator', () => {
             );
         });
 
+        test('missing message should throw an error if `throwWhenNotFound` is true', () => {
+            throwWhenNotFound(true);
+            setLocale('fr');
+
+            const MESSAGE_IN_ANOTHER_DOMAIN: Message<{ security: { parameters: NoParametersType } }, 'en'> = {
+                id: 'Invalid credentials.',
+                translations: {
+                    messages: {
+                        en: 'Invalid credentials.',
+                    },
+                },
+            };
+
+            expect(() => {
+                trans(MESSAGE_IN_ANOTHER_DOMAIN);
+            }).toThrow(`No translation message with id "${MESSAGE_IN_ANOTHER_DOMAIN.id}" is found.`);
+
+            // Set the default behavior for the next tests
+            throwWhenNotFound(false);
+        });
+
         test('message from intl domain should be prioritized over its non-intl equivalent', () => {
             const MESSAGE: Message<
                 { 'messages+intl-icu': { parameters: NoParametersType }; messages: { parameters: NoParametersType } },

src/Translator/doc/index.rst

@@ -98,6 +98,13 @@ By default, the default locale is ``en`` (English) that you can configure throug
 #. Or with ``<html data-symfony-ux-translator-locale="your-locale">`` attribute
 #. Or with ``<html lang="your-locale">`` attribute
 
+Detecting missing translations on the front-end
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the translator will return the translation key as is when the translation is missing.
+
+You can configure this behavior to throw an error instead by calling ``throwWhenNotFound(true)`` from ``@symfony/ux-translator`` package.
+
 Importing and using translations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~