feat: add base locale (#1748)

docs/guide/localization.md

@@ -44,7 +44,7 @@ If our built-in faker instances don't satisfy your needs, you can build your own
 
 ```ts
 import type { LocaleDefinition } from '@faker-js/faker';
-import { Faker, de_CH, de, en } from '@faker-js/faker';
+import { Faker, de_CH, de, en, base } from '@faker-js/faker';
 
 const customLocale: LocaleDefinition = {
   title: 'My custom locale',
@@ -54,10 +54,18 @@ const customLocale: LocaleDefinition = {
 };
 
 export const customFaker = new Faker({
-  locale: [customLocale, de_CH, de, en, global],
+  locale: [customLocale, de_CH, de, en, base],
 });
 ```
 
+In this example there are 5 locales. Each of these is checked in order, and the first locale which contains the requested data will be used:
+
+- `customLocale` is your custom locale definition which will override all other fallback definitions.
+- `de_CH` is a specific locale definition that overrides some German definitions with `CH` (Switzerland) data.
+- `de` is a generic `de` (German) locale definition.
+- `en` is a generic `en` (English) locale definition. This is our most complete locale, so we add it to fill some gaps. Depending on your needs, you might want or not want to have it as a fallback.
+- `base` is the base locale definition which contains definitions that can be used in every language (e.g. emojis).
+
 ## Available locales
 
 <!-- LOCALES-AUTO-GENERATED-START -->
@@ -69,6 +77,7 @@ export const customFaker = new Faker({
 | `af_ZA`       | Afrikaans                 | `fakerAF_ZA`       |
 | `ar`          | Arabic                    | `fakerAR`          |
 | `az`          | Azerbaijani               | `fakerAZ`          |
+| `base`        | Base                      | `fakerBASE`        |
 | `cz`          | Czech                     | `fakerCZ`          |
 | `de`          | German                    | `fakerDE`          |
 | `de_AT`       | German (Austria)          | `fakerDE_AT`       |

docs/guide/upgrading.md

@@ -60,12 +60,12 @@ const b = customFaker.internet.emoji();
 **New**
 
 ```ts
-import { Faker, de_CH, de, en, global } from '@faker-js/faker';
+import { Faker, de_CH, de, en, base } from '@faker-js/faker';
 
 // same as fakerDE_CH
 export const customFaker = new Faker({
   // Now multiple fallbacks are supported
-  locale: [de_CH, de, en, global],
+  locale: [de_CH, de, en, base],
 });
 const a = customFaker.internet.email();
 const b = customFaker.internet.emoji();

scripts/generateLocales.ts

@@ -125,10 +125,15 @@ function generateLocaleFile(locale: string): void {
     }
   }
 
-  if (locales[locales.length - 1] !== 'en') {
+  // TODO christopher 2023-03-07: Remove 'en' fallback in a separate PR
+  if (locales[locales.length - 1] !== 'en' && locale !== 'base') {
     locales.push('en');
   }
 
+  if (locales[locales.length - 1] !== 'base') {
+    locales.push('base');
+  }
+
   let content = `
       ${autoGeneratedCommentHeader}
 
@@ -148,8 +153,10 @@ function generateLocaleFile(locale: string): void {
   writeFileSync(resolve(pathLocale, `${locale}.ts`), content);
 }
 
-function tryLoadLocalesMainIndexFile(pathModules: string): LocaleDefinition {
-  let localeDef: LocaleDefinition;
+function tryLoadLocalesMainIndexFile(
+  pathModules: string
+): LocaleDefinition | undefined {
+  let localeDef: LocaleDefinition | undefined;
   // This call might fail, if the module setup is broken.
   // Unfortunately, we try to fix it with this script
   // Thats why have a fallback logic here, we only need the title anyway
@@ -165,9 +172,10 @@ function tryLoadLocalesMainIndexFile(pathModules: string): LocaleDefinition {
         resolve(pathModules, 'index.ts'),
         'utf-8'
       );
-      localeDef = {
-        title: localeIndex.match(/title: '(.*)',/)[1],
-      };
+      const title = localeIndex.match(/title: '(.*)',/)?.[1];
+      if (title) {
+        localeDef = { title };
+      }
     } catch {
       console.error(`Failed to load ${pathModules} or manually parse it.`, e);
     }

src/locale/af_ZA.ts

@@ -5,8 +5,9 @@
 
 import { Faker } from '../faker';
 import af_ZA from '../locales/af_ZA';
+import base from '../locales/base';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [af_ZA, en],
+  locale: [af_ZA, en, base],
 });

src/locale/ar.ts

@@ -5,8 +5,9 @@
 
 import { Faker } from '../faker';
 import ar from '../locales/ar';
+import base from '../locales/base';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [ar, en],
+  locale: [ar, en, base],
 });

src/locale/az.ts

@@ -5,8 +5,9 @@
 
 import { Faker } from '../faker';
 import az from '../locales/az';
+import base from '../locales/base';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [az, en],
+  locale: [az, en, base],
 });

src/locale/base.ts

@@ -0,0 +1,11 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+
+import { Faker } from '../faker';
+import base from '../locales/base';
+
+export const faker = new Faker({
+  locale: base,
+});

src/locale/cz.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import cz from '../locales/cz';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [cz, en],
+  locale: [cz, en, base],
 });

src/locale/de.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de, en],
+  locale: [de, en, base],
 });

src/locale/de_AT.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import de_AT from '../locales/de_AT';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de_AT, de, en],
+  locale: [de_AT, de, en, base],
 });

src/locale/de_CH.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import de_CH from '../locales/de_CH';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de_CH, de, en],
+  locale: [de_CH, de, en, base],
 });

src/locale/dv.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import dv from '../locales/dv';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [dv, en],
+  locale: [dv, en, base],
 });

src/locale/el.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import el from '../locales/el';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [el, en],
+  locale: [el, en, base],
 });

src/locale/en.ts

@@ -4,8 +4,9 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: en,
+  locale: [en, base],
 });

src/locale/en_AU.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_AU from '../locales/en_AU';
 
 export const faker = new Faker({
-  locale: [en_AU, en],
+  locale: [en_AU, en, base],
 });

src/locale/en_AU_ocker.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_AU from '../locales/en_AU';
 import en_AU_ocker from '../locales/en_AU_ocker';
 
 export const faker = new Faker({
-  locale: [en_AU_ocker, en_AU, en],
+  locale: [en_AU_ocker, en_AU, en, base],
 });

src/locale/en_BORK.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_BORK from '../locales/en_BORK';
 
 export const faker = new Faker({
-  locale: [en_BORK, en],
+  locale: [en_BORK, en, base],
 });

src/locale/en_CA.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_CA from '../locales/en_CA';
 
 export const faker = new Faker({
-  locale: [en_CA, en],
+  locale: [en_CA, en, base],
 });

src/locale/en_GB.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_GB from '../locales/en_GB';
 
 export const faker = new Faker({
-  locale: [en_GB, en],
+  locale: [en_GB, en, base],
 });

src/locale/en_GH.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_GH from '../locales/en_GH';
 
 export const faker = new Faker({
-  locale: [en_GH, en],
+  locale: [en_GH, en, base],
 });

src/locale/en_IE.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_IE from '../locales/en_IE';
 
 export const faker = new Faker({
-  locale: [en_IE, en],
+  locale: [en_IE, en, base],
 });

src/locale/en_IN.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_IN from '../locales/en_IN';
 
 export const faker = new Faker({
-  locale: [en_IN, en],
+  locale: [en_IN, en, base],
 });

src/locale/en_NG.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_NG from '../locales/en_NG';
 
 export const faker = new Faker({
-  locale: [en_NG, en],
+  locale: [en_NG, en, base],
 });

src/locale/en_US.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_US from '../locales/en_US';
 
 export const faker = new Faker({
-  locale: [en_US, en],
+  locale: [en_US, en, base],
 });

src/locale/en_ZA.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_ZA from '../locales/en_ZA';
 
 export const faker = new Faker({
-  locale: [en_ZA, en],
+  locale: [en_ZA, en, base],
 });

src/locale/es.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import es from '../locales/es';
 
 export const faker = new Faker({
-  locale: [es, en],
+  locale: [es, en, base],
 });

src/locale/es_MX.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import es from '../locales/es';
 import es_MX from '../locales/es_MX';
 
 export const faker = new Faker({
-  locale: [es_MX, es, en],
+  locale: [es_MX, es, en, base],
 });

src/locale/fa.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import fa from '../locales/fa';
 
 export const faker = new Faker({
-  locale: [fa, en],
+  locale: [fa, en, base],
 });