feat: multi locale fallback

scripts/generateLocales.ts

@@ -17,6 +17,7 @@ import { resolve } from 'node:path';
 import type { Options } from 'prettier';
 import { format } from 'prettier';
 import options from '../.prettierrc.cjs';
+import { faker } from '../src';
 import type { LocaleDefinition } from '../src/definitions';
 import { DEFINITIONS } from '../src/definitions';
 
@@ -81,19 +82,22 @@ function containsAll(checked?: string[], expected?: string[]): boolean {
 }
 
 function generateLocaleFile(locale: string): void {
+  faker.setLocale(locale);
+
+  const localeOrder = faker.localeOrder;
+
   let content = `
       ${autoGeneratedCommentHeader}
 
       import { Faker } from '../faker';
-      import ${locale} from '../locales/${locale}';
-      ${locale !== 'en' ? "import en from '../locales/en';" : ''}
+      ${localeOrder
+        .map((entry) => `import ${entry} from '../locales/${entry}';`)
+        .join('\n')}
 
       const faker = new Faker({
-        locale: '${locale}',
-        localeFallback: 'en',
+        localeOrder: ${JSON.stringify(localeOrder)},
         locales: {
-          ${locale},
-          ${locale !== 'en' ? 'en,' : ''}
+          ${localeOrder.map((entry) => `${entry},`).join('\n')}
         },
       });
 

src/faker.ts

@@ -38,14 +38,12 @@ export type UsedLocales = Partial<Record<UsableLocale, LocaleDefinition>>;
 
 export interface FakerOptions {
   locales: UsedLocales;
-  locale?: UsableLocale;
-  localeFallback?: UsableLocale;
+  localeOrder?: UsableLocale[];
 }
 
 export class Faker {
   locales: UsedLocales;
-  locale: UsableLocale;
-  localeFallback: UsableLocale;
+  localeOrder: UsableLocale[];
 
   readonly definitions: LocaleDefinition = this.initDefinitions();
 
@@ -95,25 +93,35 @@ export class Faker {
     }
 
     this.locales = opts.locales;
-    this.locale = opts.locale || 'en';
-    this.localeFallback = opts.localeFallback || 'en';
+    this.localeOrder = opts.localeOrder ?? ['en'];
   }
 
   /**
    * Creates a Proxy based LocaleDefinition that virtually merges the locales.
    */
   private initDefinitions(): LocaleDefinition {
+    // Returns the first resolved locale data that aren't undefined
+    const findFirst = <T>(
+      resolver: (data: LocaleDefinition) => T | undefined
+    ): T | undefined => {
+      for (const locale of this.localeOrder) {
+        const baseData = resolver(this.locales[locale]);
+        if (baseData != null) {
+          return baseData;
+        }
+      }
+      return undefined;
+    };
+
     // Returns the first LocaleDefinition[key] in any locale
     const resolveBaseData = (key: keyof LocaleDefinition): unknown =>
-      this.locales[this.locale][key] ?? this.locales[this.localeFallback][key];
+      findFirst((data) => data[key]);
 
     // Returns the first LocaleDefinition[module][entry] in any locale
     const resolveModuleData = (
       module: keyof LocaleDefinition,
       entry: string
-    ): unknown =>
-      this.locales[this.locale][module]?.[entry] ??
-      this.locales[this.localeFallback][module]?.[entry];
+    ): unknown => findFirst((data) => data[module]?.[entry]);
 
     // Returns a proxy that can return the entries for a module (if it exists)
     const moduleLoader = (
@@ -159,11 +167,25 @@ export class Faker {
   }
 
   /**
-   * Set Faker's locale
+   * Set Faker's locale using the default fallback strategy.
    *
    * @param locale The locale to set (e.g. `en` or `en_AU`, `en_AU_ocker`).
+   * @param fallbacks The fixed fallbacks to use. Defaults to `['en']`.
    */
-  setLocale(locale: UsableLocale): void {
-    this.locale = locale;
+  setLocale(locale: UsableLocale, fallbacks: UsableLocale[] = ['en']): void {
+    const localeOrder = [];
+    const parts = locale.split('_');
+    for (let i = parts.length; i > 0; i--) {
+      const subLocale = parts.slice(0, i).join('_');
+      if (this.locales[subLocale] != null) {
+        localeOrder.push(subLocale);
+      }
+    }
+    for (const fallback of fallbacks) {
+      if (!localeOrder.includes(fallback) && this.locales[fallback] != null) {
+        localeOrder.push(fallback);
+      }
+    }
+    this.localeOrder = localeOrder;
   }
 }

src/locale/af_ZA.ts

@@ -8,8 +8,7 @@ import af_ZA from '../locales/af_ZA';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'af_ZA',
-  localeFallback: 'en',
+  localeOrder: ['af_ZA', 'en'],
   locales: {
     af_ZA,
     en,

src/locale/ar.ts

@@ -8,8 +8,7 @@ import ar from '../locales/ar';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'ar',
-  localeFallback: 'en',
+  localeOrder: ['ar', 'en'],
   locales: {
     ar,
     en,

src/locale/az.ts

@@ -8,8 +8,7 @@ import az from '../locales/az';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'az',
-  localeFallback: 'en',
+  localeOrder: ['az', 'en'],
   locales: {
     az,
     en,

src/locale/cz.ts

@@ -8,8 +8,7 @@ import cz from '../locales/cz';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'cz',
-  localeFallback: 'en',
+  localeOrder: ['cz', 'en'],
   locales: {
     cz,
     en,

src/locale/de.ts

@@ -8,8 +8,7 @@ import de from '../locales/de';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'de',
-  localeFallback: 'en',
+  localeOrder: ['de', 'en'],
   locales: {
     de,
     en,

src/locale/de_AT.ts

@@ -4,14 +4,15 @@
  */
 
 import { Faker } from '../faker';
+import de from '../locales/de';
 import de_AT from '../locales/de_AT';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'de_AT',
-  localeFallback: 'en',
+  localeOrder: ['de_AT', 'de', 'en'],
   locales: {
     de_AT,
+    de,
     en,
   },
 });

src/locale/de_CH.ts

@@ -4,14 +4,15 @@
  */
 
 import { Faker } from '../faker';
+import de from '../locales/de';
 import de_CH from '../locales/de_CH';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'de_CH',
-  localeFallback: 'en',
+  localeOrder: ['de_CH', 'de', 'en'],
   locales: {
     de_CH,
+    de,
     en,
   },
 });

src/locale/el.ts

@@ -8,8 +8,7 @@ import el from '../locales/el';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'el',
-  localeFallback: 'en',
+  localeOrder: ['el', 'en'],
   locales: {
     el,
     en,

src/locale/en.ts

@@ -7,8 +7,7 @@ import { Faker } from '../faker';
 import en from '../locales/en';
 
 const faker = new Faker({
-  locale: 'en',
-  localeFallback: 'en',
+  localeOrder: ['en'],
   locales: {
     en,
   },

src/locale/en_AU.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_AU from '../locales/en_AU';
 
 const faker = new Faker({
-  locale: 'en_AU',
-  localeFallback: 'en',
+  localeOrder: ['en_AU', 'en'],
   locales: {
     en_AU,
     en,

src/locale/en_AU_ocker.ts

@@ -5,13 +5,14 @@
 
 import { Faker } from '../faker';
 import en from '../locales/en';
+import en_AU from '../locales/en_AU';
 import en_AU_ocker from '../locales/en_AU_ocker';
 
 const faker = new Faker({
-  locale: 'en_AU_ocker',
-  localeFallback: 'en',
+  localeOrder: ['en_AU_ocker', 'en_AU', 'en'],
   locales: {
     en_AU_ocker,
+    en_AU,
     en,
   },
 });

src/locale/en_BORK.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_BORK from '../locales/en_BORK';
 
 const faker = new Faker({
-  locale: 'en_BORK',
-  localeFallback: 'en',
+  localeOrder: ['en_BORK', 'en'],
   locales: {
     en_BORK,
     en,

src/locale/en_CA.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_CA from '../locales/en_CA';
 
 const faker = new Faker({
-  locale: 'en_CA',
-  localeFallback: 'en',
+  localeOrder: ['en_CA', 'en'],
   locales: {
     en_CA,
     en,

src/locale/en_GB.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_GB from '../locales/en_GB';
 
 const faker = new Faker({
-  locale: 'en_GB',
-  localeFallback: 'en',
+  localeOrder: ['en_GB', 'en'],
   locales: {
     en_GB,
     en,

src/locale/en_GH.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_GH from '../locales/en_GH';
 
 const faker = new Faker({
-  locale: 'en_GH',
-  localeFallback: 'en',
+  localeOrder: ['en_GH', 'en'],
   locales: {
     en_GH,
     en,

src/locale/en_IE.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_IE from '../locales/en_IE';
 
 const faker = new Faker({
-  locale: 'en_IE',
-  localeFallback: 'en',
+  localeOrder: ['en_IE', 'en'],
   locales: {
     en_IE,
     en,

src/locale/en_IND.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_IND from '../locales/en_IND';
 
 const faker = new Faker({
-  locale: 'en_IND',
-  localeFallback: 'en',
+  localeOrder: ['en_IND', 'en'],
   locales: {
     en_IND,
     en,

src/locale/en_NG.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_NG from '../locales/en_NG';
 
 const faker = new Faker({
-  locale: 'en_NG',
-  localeFallback: 'en',
+  localeOrder: ['en_NG', 'en'],
   locales: {
     en_NG,
     en,

src/locale/en_US.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_US from '../locales/en_US';
 
 const faker = new Faker({
-  locale: 'en_US',
-  localeFallback: 'en',
+  localeOrder: ['en_US', 'en'],
   locales: {
     en_US,
     en,

src/locale/en_ZA.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import en_ZA from '../locales/en_ZA';
 
 const faker = new Faker({
-  locale: 'en_ZA',
-  localeFallback: 'en',
+  localeOrder: ['en_ZA', 'en'],
   locales: {
     en_ZA,
     en,

src/locale/es.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import es from '../locales/es';
 
 const faker = new Faker({
-  locale: 'es',
-  localeFallback: 'en',
+  localeOrder: ['es', 'en'],
   locales: {
     es,
     en,

src/locale/es_MX.ts

@@ -5,13 +5,14 @@
 
 import { Faker } from '../faker';
 import en from '../locales/en';
+import es from '../locales/es';
 import es_MX from '../locales/es_MX';
 
 const faker = new Faker({
-  locale: 'es_MX',
-  localeFallback: 'en',
+  localeOrder: ['es_MX', 'es', 'en'],
   locales: {
     es_MX,
+    es,
     en,
   },
 });

src/locale/fa.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import fa from '../locales/fa';
 
 const faker = new Faker({
-  locale: 'fa',
-  localeFallback: 'en',
+  localeOrder: ['fa', 'en'],
   locales: {
     fa,
     en,

src/locale/fi.ts

@@ -8,8 +8,7 @@ import en from '../locales/en';
 import fi from '../locales/fi';
 
 const faker = new Faker({
-  locale: 'fi',
-  localeFallback: 'en',
+  localeOrder: ['fi', 'en'],
   locales: {
     fi,
     en,