[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;

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,13 +4,15 @@ import {
     type NoParametersType,
     setLocale,
     setLocaleFallbacks,
+    throwWhenNotFound,
     trans,
 } from '../src/translator';
 
 describe('Translator', () => {
     beforeEach(() => {
         setLocale(null);
         setLocaleFallbacks({});
+        throwWhenNotFound(false);
         document.documentElement.lang = '';
         document.documentElement.removeAttribute('data-symfony-ux-translator-locale');
     });
@@ -387,6 +389,24 @@ 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 "Invalid credentials." is found.`);
+        });
+
         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,36 @@ 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)``:
+
+.. code-block:: diff
+
+    // assets/translator.js
+
+    /*
+     * This file is part of the Symfony UX Translator package.
+     *
+     * If folder "../var/translations" does not exist, or some translations are missing,
+     * you must warmup your Symfony cache to refresh JavaScript translations.
+     *
+     * If you use TypeScript, you can rename this file to "translator.ts" to take advantage of types checking.
+     */
+
+    -import { trans, getLocale, setLocale, setLocaleFallbacks } from '@symfony/ux-translator';
+    +import { trans, getLocale, setLocale, setLocaleFallbacks, throwWhenNotFound } from '@symfony/ux-translator';
+    import { localeFallbacks } from '../var/translations/configuration';
+
+    setLocaleFallbacks(localeFallbacks);
+    +throwWhenNotFound(true)
+
+    export { trans }
+    export * from '../var/translations';
+
 Importing and using translations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~