Skip to content

Commit

Permalink
refactor!: remove dynamic locale switching support (#1735)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ST-DDT
ST-DDT committed Mar 7, 2023
1 parent a4d5203 commit 9a35dc9
Show file tree
Hide file tree
Showing 103 changed files with 914 additions and 1,222 deletions.
32 changes: 23 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,11 @@ npm install --save-dev @faker-js/faker
## 🪄 Usage

```ts
// ESM
import { faker } from '@faker-js/faker';
// import { faker } from '@faker-js/faker/locale/de';

// CJS
const { faker } = require('@faker-js/faker');

export function createRandomUser(): User {
return {
Expand Down Expand Up @@ -108,7 +111,6 @@ The API covers the following modules:
| Music | `faker.music.genre()` | R&B |
| Person | `faker.person.firstName()` | Cameron |
| Phone | `faker.phone.phoneNumber()` | +1 291-299-0192 |
| Random | `faker.random.locale()` | fr_CA |
| Science | `faker.science.unit()` | `{ name: 'meter', symbol: 'm' }` |
| System | `faker.system.directoryPath()` | /root |
| Vehicle | `faker.vehicle.vehicle()` | Lamborghini Camry |
Expand All @@ -130,18 +132,30 @@ console.log(

Faker has support for multiple locales.

The default language locale is set to English.

Setting a new locale is simple:
The main `faker` instance uses the English locale.
But you can also import instances using other locales.

```ts
// sets locale to de
faker.locale = 'de';
// ESM
import { fakerDE as faker } from '@faker-js/faker';

// CJS
const { fakerDE: faker } = require('@faker-js/faker');
```

See our documentation for a list of [provided languages](https://fakerjs.dev/guide/localization.html#available-locales)
See our documentation for a list of [provided languages](https://fakerjs.dev/guide/localization.html#available-locales).

Please note: Not every locale provides data for every module. In our pre-made faker instances,
we fall back to English in such a case as this is the most complete and most commonly used language.
If you don't want that or prefer a different fallback, you can also build your own instances.

Please note: not every locale provides data for every module. In our pre-made locales, we fallback to English in such a case as this is the most complete and most commonly used language.
```ts
import { Faker, de, de_CH } from '@faker-js/faker';

export const faker = new Faker({
locale: [de_CH, de],
});
```

## ⚙️ Setting a randomness seed

Expand Down
161 changes: 96 additions & 65 deletions docs/guide/localization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!_
Expand All @@ -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';
```
84 changes: 84 additions & 0 deletions docs/guide/upgrading.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
12 changes: 4 additions & 8 deletions docs/guide/usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(); // Kassandra.Haley@erich.biz
```

:::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
Expand All @@ -27,6 +21,8 @@ const randomName = faker.person.fullName(); // Rowan Nikolaus
const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
```

For more information about changing and customizing the locales, please refer to our [Localization Guide](localization).

## Browser

```html
Expand Down
4 changes: 3 additions & 1 deletion scripts/apidoc/typedoc.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,9 @@ export function selectApiModules(
export function selectApiMethods(
module: DeclarationReflection
): DeclarationReflection[] {
return module.getChildrenByKind(ReflectionKind.Method);
return module
.getChildrenByKind(ReflectionKind.Method)
.filter((method) => !method.flags.isPrivate);
}

/**
Expand Down

0 comments on commit 9a35dc9

Please sign in to comment.