refactor!: remove dynamic locale switching support (#1735)

3 files changed, 184 insertions, 73 deletions

diff --git a/docs/guide/localization.md b/docs/guide/localization.md
index b0bfbad8..b3003aad 100644
--- a/docs/guide/localization.md
+++ b/docs/guide/localization.md
@@ -3,15 +3,20 @@
 ## Switching locales
 
 Did you know Faker supports many different locales?  
-By default, when using `import { faker } from '@faker-js/faker'` actually every available locale that is supported by Faker will be loaded and you can switch the locale at runtime with `faker.setLocale('de')`.
+When using our default instance `import { faker } from '@faker-js/faker'` you get English data.
+However, we also provide pre-built instances for more than 50 other locales.
 
-::: tip
-Alternatively you can also just use `faker.locale = 'de'` instead to switch the locale.
+`import { fakerDE as faker } from '@faker-js/faker'`
+
+See below for a list of available locales.
+
+:::tip Note
+You can also build your own Faker instances, with custom locales/overwrites.
 :::
 
 ## Individual localized packages
 
-By default, Faker will include **all** locale data.  
+Currently, the imports from the main package have a [bug](https://github.com/faker-js/faker/issues/1791) and always cause the entire Faker lib to be imported.
 This might result in loading around 5 MB of data into memory and slow down startup times.
 
 _But we got your back!_  
@@ -33,72 +38,98 @@ Some locales have limited coverage and rely more heavily on the English locale a
 However, in most cases, using a specific locale will be beneficial in the long term as specifying a locale reduces the time necessary for startup, which has a compounding effect on testing frameworks that reload the imports every execution.
 :::
 
+## Custom locales and fallbacks
+
+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';
+
+const customLocale: LocaleDefinition = {
+  title: 'My custom locale',
+  internet: {
+    domainSuffix: ['test'],
+  },
+};
+
+export const customFaker = new Faker({
+  locale: [customLocale, de_CH, de, en, global],
+});
+```
+
 ## Available locales
 
 <!-- LOCALES-AUTO-GENERATED-START -->
 
 <!-- Run 'pnpm run generate:locales' to update. -->
 
-| Locale      | Name                      |
-| :---------- | :------------------------ |
-| af_ZA       | Afrikaans                 |
-| ar          | Arabic                    |
-| az          | Azerbaijani               |
-| cz          | Czech                     |
-| de          | German                    |
-| de_AT       | German (Austria)          |
-| de_CH       | German (Switzerland)      |
-| dv          | Dhivehi                   |
-| el          | Greek                     |
-| en          | English                   |
-| en_AU       | English (Australia)       |
-| en_AU_ocker | English (Australia Ocker) |
-| en_BORK     | English (Bork)            |
-| en_CA       | English (Canada)          |
-| en_GB       | English (Great Britain)   |
-| en_GH       | English (Ghana)           |
-| en_IE       | English (Ireland)         |
-| en_IN       | English (India)           |
-| en_NG       | Nigeria (English)         |
-| en_US       | English (United States)   |
-| en_ZA       | English (South Africa)    |
-| es          | Spanish                   |
-| es_MX       | Spanish (Mexico)          |
-| fa          | Farsi                     |
-| fi          | Finnish                   |
-| fr          | French                    |
-| fr_BE       | Français (Belgique)       |
-| fr_CA       | French (Canada)           |
-| fr_CH       | French (Switzerland)      |
-| fr_LU       | French (Luxembourg)       |
-| ge          | Georgian                  |
-| he          | Hebrew                    |
-| hr          | Hrvatski                  |
-| hu          | Hungarian                 |
-| hy          | Armenian                  |
-| id_ID       | Indonesian                |
-| it          | Italian                   |
-| ja          | Japanese                  |
-| ko          | Korean                    |
-| lv          | Latvian                   |
-| mk          | Macedonian                |
-| nb_NO       | Norwegian                 |
-| ne          | Nepalese                  |
-| nl          | Dutch                     |
-| nl_BE       | Dutch (Belgium)           |
-| pl          | Polish                    |
-| pt_BR       | Portuguese (Brazil)       |
-| pt_PT       | Portuguese (Portugal)     |
-| ro          | Romanian                  |
-| ru          | Russian                   |
-| sk          | Slovakian                 |
-| sv          | Swedish                   |
-| tr          | Turkish                   |
-| uk          | Ukrainian                 |
-| ur          | Urdu                      |
-| vi          | Vietnamese                |
-| zh_CN       | Chinese                   |
-| zh_TW       | Chinese (Taiwan)          |
-| zu_ZA       | Zulu (South Africa)       |
+| Locale        | Name                      | Faker              |
+| :------------ | :------------------------ | :----------------- |
+| `af_ZA`       | Afrikaans                 | `fakerAF_ZA`       |
+| `ar`          | Arabic                    | `fakerAR`          |
+| `az`          | Azerbaijani               | `fakerAZ`          |
+| `cz`          | Czech                     | `fakerCZ`          |
+| `de`          | German                    | `fakerDE`          |
+| `de_AT`       | German (Austria)          | `fakerDE_AT`       |
+| `de_CH`       | German (Switzerland)      | `fakerDE_CH`       |
+| `dv`          | Dhivehi                   | `fakerDV`          |
+| `el`          | Greek                     | `fakerEL`          |
+| `en`          | English                   | `fakerEN`          |
+| `en_AU`       | English (Australia)       | `fakerEN_AU`       |
+| `en_AU_ocker` | English (Australia Ocker) | `fakerEN_AU_ocker` |
+| `en_BORK`     | English (Bork)            | `fakerEN_BORK`     |
+| `en_CA`       | English (Canada)          | `fakerEN_CA`       |
+| `en_GB`       | English (Great Britain)   | `fakerEN_GB`       |
+| `en_GH`       | English (Ghana)           | `fakerEN_GH`       |
+| `en_IE`       | English (Ireland)         | `fakerEN_IE`       |
+| `en_IN`       | English (India)           | `fakerEN_IN`       |
+| `en_NG`       | Nigeria (English)         | `fakerEN_NG`       |
+| `en_US`       | English (United States)   | `fakerEN_US`       |
+| `en_ZA`       | English (South Africa)    | `fakerEN_ZA`       |
+| `es`          | Spanish                   | `fakerES`          |
+| `es_MX`       | Spanish (Mexico)          | `fakerES_MX`       |
+| `fa`          | Farsi                     | `fakerFA`          |
+| `fi`          | Finnish                   | `fakerFI`          |
+| `fr`          | French                    | `fakerFR`          |
+| `fr_BE`       | Français (Belgique)       | `fakerFR_BE`       |
+| `fr_CA`       | French (Canada)           | `fakerFR_CA`       |
+| `fr_CH`       | French (Switzerland)      | `fakerFR_CH`       |
+| `fr_LU`       | French (Luxembourg)       | `fakerFR_LU`       |
+| `ge`          | Georgian                  | `fakerGE`          |
+| `he`          | Hebrew                    | `fakerHE`          |
+| `hr`          | Hrvatski                  | `fakerHR`          |
+| `hu`          | Hungarian                 | `fakerHU`          |
+| `hy`          | Armenian                  | `fakerHY`          |
+| `id_ID`       | Indonesian                | `fakerID_ID`       |
+| `it`          | Italian                   | `fakerIT`          |
+| `ja`          | Japanese                  | `fakerJA`          |
+| `ko`          | Korean                    | `fakerKO`          |
+| `lv`          | Latvian                   | `fakerLV`          |
+| `mk`          | Macedonian                | `fakerMK`          |
+| `nb_NO`       | Norwegian                 | `fakerNB_NO`       |
+| `ne`          | Nepalese                  | `fakerNE`          |
+| `nl`          | Dutch                     | `fakerNL`          |
+| `nl_BE`       | Dutch (Belgium)           | `fakerNL_BE`       |
+| `pl`          | Polish                    | `fakerPL`          |
+| `pt_BR`       | Portuguese (Brazil)       | `fakerPT_BR`       |
+| `pt_PT`       | Portuguese (Portugal)     | `fakerPT_PT`       |
+| `ro`          | Romanian                  | `fakerRO`          |
+| `ru`          | Russian                   | `fakerRU`          |
+| `sk`          | Slovakian                 | `fakerSK`          |
+| `sv`          | Swedish                   | `fakerSV`          |
+| `tr`          | Turkish                   | `fakerTR`          |
+| `uk`          | Ukrainian                 | `fakerUK`          |
+| `ur`          | Urdu                      | `fakerUR`          |
+| `vi`          | Vietnamese                | `fakerVI`          |
+| `zh_CN`       | Chinese                   | `fakerZH_CN`       |
+| `zh_TW`       | Chinese (Taiwan)          | `fakerZH_TW`       |
+| `zu_ZA`       | Zulu (South Africa)       | `fakerZU_ZA`       |
 
 <!-- LOCALES-AUTO-GENERATED-END -->
+
+The `Locale` (data) and `Faker` columns refer to the respective `import` names:
+
+```ts
+import { de, fakerDE } from '@faker-js/faker';
+```
diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md
index 709a76d0..82bfd2ac 100644
--- a/docs/guide/upgrading.md
+++ b/docs/guide/upgrading.md
@@ -14,6 +14,90 @@ Not the version you are looking for?
 
 ## Breaking changes
 
+### Removed ability to change the locale on existing `Faker` instances
+
+:::tip NOTE
+If you are using only the default (`en`) locale, then you don't have to change anything.
+:::
+
+In order to facilitate better and easier locale fallback mechanics, we removed the methods to change the locales on existing `Faker` instances.
+Now, we expose specific faker instances for each locale that you can use:
+
+**Old**
+
+```ts
+import { faker } from '@faker-js/faker';
+
+faker.setLocale('de_CH');
+// or
+faker.locale = 'de_CH';
+faker.fallbackLocale = 'en';
+```
+
+**New**
+
+```ts
+import { fakerDE_CH as faker } from '@faker-js/faker';
+```
+
+This also fixes issues where more than two locales are required:
+
+**Old**
+
+```ts
+import { faker } from '@faker-js/faker';
+
+const customFaker = new Faker({
+  locale: 'de_CH', // the expected locale
+  fallbackLocale: 'de', // ensure we have a German fallbacks for addresses
+  locales: { de_CH, de, en },
+});
+const a = customFaker.internet.email();
+customFaker.locale = 'en'; // neither 'de_CH' nor 'de' have emojis
+const b = customFaker.internet.emoji();
+```
+
+**New**
+
+```ts
+import { Faker, de_CH, de, en, global } from '@faker-js/faker';
+
+// same as fakerDE_CH
+export const customFaker = new Faker({
+  // Now multiple fallbacks are supported
+  locale: [de_CH, de, en, global],
+});
+const a = customFaker.internet.email();
+const b = customFaker.internet.emoji();
+```
+
+If you wish to create entries for multiple locales, you can still do so:
+
+**Old**
+
+```ts
+import { faker } from '@faker-js/faker';
+
+for (let user of users) {
+  const lang = faker.helpers.arrayElement(['de', 'en', 'fr']);
+  faker.locale = lang;
+  user.email = faker.internet.email();
+}
+```
+
+**New**
+
+```ts
+import { faker, fakerDE, fakerEN, fakerFR } from '@faker-js/faker';
+
+for (let user of users) {
+  const currentFaker = faker.helpers.arrayElement([fakerDE, fakerEN, fakerFR]);
+  user.email = currentFaker.internet.email();
+}
+```
+
+For more information refer to our [Localization Guide](localization).
+
 ### `faker.mersenne` and `faker.helpers.repeatString` removed
 
 `faker.mersenne` and `faker.helpers.repeatString` were only ever intended for internal use, and are no longer available.
diff --git a/docs/guide/usage.md b/docs/guide/usage.md
index 6d325a0b..7448a699 100644
--- a/docs/guide/usage.md
+++ b/docs/guide/usage.md
@@ -6,18 +6,12 @@ Using Faker is as easy as importing it from `@faker-js/faker`.
 
 ```js
 import { faker } from '@faker-js/faker';
-// or, if desiring only a specific locale
-// import { faker } from '@faker-js/faker/locale/de'
+// or, if desiring a different locale
+// import { fakerDE as faker } from '@faker-js/faker'
 const randomName = faker.person.fullName(); // Rowan Nikolaus
 const randomEmail = faker.internet.email(); // [email protected]
 ```
 
-:::tip Note
-Using the first import statement will load every locale into memory.
-As such, start-up times and performance may be slow.
-Thus, by declaring a locale in the import, one can increase performance and reduce the time on start-up.
-:::
-
 Or if you're using CommonJS:
 
 ```js
@@ -27,6 +21,8 @@ const randomName = faker.person.fullName(); // Rowan Nikolaus
 const randomEmail = faker.internet.email(); // [email protected]
 ```
 
+For more information about changing and customizing the locales, please refer to our [Localization Guide](localization).
+
 ## Browser
 
 ```html