Merge pull request #806 from smapiot/feature/fallback-language

Add "fallbackLanguage" to piral-translate

Author: FlorianRappl

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 1.10.1 (tbd)
 
 - Improved trusted publishing
+- Added `fallbackLanguage` in `piral-translate`
 
 ## 1.10.0 (February 24, 2026)
 

src/plugins/piral-translate/src/create.ts

@@ -32,7 +32,13 @@ export interface LocaleConfig {
    */
   language?: string | RetrieveCurrentLanguage;
   /**
-   * Sets the optional fallback to use.
+   * Sets the fallback language to be used when a translation
+   * is not available in the current language.
+   */
+  fallbackLanguage?: string;
+  /**
+   * Sets the optional fallback to use when a translation is neither
+   * available in the current language or {@link fallbackLanguage}.
    */
   fallback?: TranslationFallback;
 }
@@ -48,7 +54,7 @@ export function setupLocalizer(config: LocaleConfig = {}): Localizable {
   const computeLang = config.language;
   const usedLang = typeof computeLang === 'function' ? computeLang(languages, defaultLang, 'en') : computeLang;
   const language = usedLang || defaultLang;
-  return new Localizer(msgs, language, languages.length ? languages : [language], config.fallback);
+  return new Localizer(msgs, language, languages.length ? languages : [language], config.fallbackLanguage, config.fallback);
 }
 
 /**

src/plugins/piral-translate/src/localize.test.ts

@@ -32,7 +32,7 @@ describe('Localize Module', () => {
     expect(result).toBe('hiho');
   });
 
-  it('localizeLocal translates from the global translations if local not available', () => {
+  it('localizeLocal translates from the global translations if local and fallback language are not available', () => {
     const localizer = new Localizer(messages, 'en');
     const result = localizer.localizeLocal(
       {
@@ -45,6 +45,19 @@ describe('Localize Module', () => {
     expect(result).toBe('hello');
   });
 
+  it('localizeLocal prioritzes fallback language over global translations', () => {
+    const localizer = new Localizer(messages, 'de', undefined, 'en');
+    const result = localizer.localizeLocal(
+      {
+        en: {
+          fallback: 'fallback',
+        },
+      },
+      'fallback'
+    );
+    expect(result).toBe('fallback');
+  });
+
   it('localizeGlobal translates from the global translations', () => {
     const localizer = new Localizer(messages, 'en');
     const result = localizer.localizeGlobal('hi');
@@ -69,6 +82,12 @@ describe('Localize Module', () => {
     expect(result).toBe('Hi {{name}}, welcome back');
   });
 
+  it('localizeGlobal uses fallback language', () => {
+    const localizer = new Localizer(messages, 'de', undefined, 'en');
+    const result = localizer.localizeGlobal('greeting', { name: 'fallback' });
+    expect(result).toBe('Hi fallback, welcome back');
+  });
+
   it('localizeGlobal places missing string placeholder if not found', () => {
     const localizer = new Localizer(messages, 'en');
     const result = localizer.localizeGlobal('ho');

src/plugins/piral-translate/src/localize.ts

@@ -16,7 +16,7 @@ function defaultFallback(key: string, language: string): string {
 
 function formatMessage<T extends object>(message: string, variables: T): string {
   return message.replace(/{{\s*([A-Za-z0-9_.]+)\s*}}/g, (_match: string, p1: string) => {
-    return p1 in variables ? variables[p1] ?? '' : `{{${p1}}}`;
+    return p1 in variables ? (variables[p1] ?? '') : `{{${p1}}}`;
   });
 }
 
@@ -29,7 +29,8 @@ export class Localizer implements Localizable {
   constructor(
     messages: LocalizationMessages | NestedLocalizationMessages,
     public language: string,
-    public languages: Array<string>,
+    public languages: Array<string> = [language],
+    private fallbackLanguage?: string,
     private fallback: TranslationFallback = defaultFallback,
   ) {
     this.messages = flattenTranslations(messages);
@@ -73,8 +74,10 @@ export class Localizer implements Localizable {
 
   private translateMessage<T extends object>(messages: LocalizationMessages, key: string, variables?: T) {
     const language = this.language;
+    const fallbackLanguage = this.fallbackLanguage;
     const translations = language && messages[language];
-    const translation = translations && translations[key];
+    const fallbackTranslations = fallbackLanguage && messages[fallbackLanguage];
+    const translation = (translations && translations[key]) || (fallbackTranslations && fallbackTranslations[key]);
     return translation && (variables ? formatMessage(translation, variables) : translation);
   }
 }