Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(guide): add locale error handling sections #3055

Merged
merged 13 commits into from
Aug 14, 2024
82 changes: 82 additions & 0 deletions docs/guide/localization.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,3 +165,85 @@ for (let key of Object.keys(allFakers)) {
}
}
```

## Handling Missing Data Errors

```txt
[Error]: The locale data for 'category.entry' are missing in this locale.
Please contribute the missing data to the project or use a locale/Faker instance that has these data.
For more information see https://fakerjs.dev/guide/localization.html
```

If you receive this error, this means you are using a locale (`Faker` instance) that does not have the relevant data for that method yet.
Please consider contributing the missing data, so that others can use them in the future as well.

As a workaround, you can provide additional fallbacks to your `Faker` instance:

```ts
import { Faker, el } from '@faker-js/faker'; // [!code --]
import { Faker, el, en } from '@faker-js/faker'; // [!code ++]

const faker = new Faker({
locale: [el], // [!code --]
locale: [el, en], // [!code ++]
});
console.log(faker.location.country()); // 'Belgium'
```

::: tip Note
Of course, you can use [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) for this as well.
:::

## Handling Not-Applicable Data Errors

```txt
[Error]: The locale data for 'category.entry' aren't applicable to this locale.
If you think this is a bug, please report it at: https://github.com/faker-js/faker
```

If you receive this error, this means the current locale is unable to provide reasonable values for that method.
For example, there are no zip codes in Hongkong, so for that reason the `en_HK` locale is unable to provide these data.
The same applies to other locales and methods.

```ts
import { fakerEN_HK } from '@faker-js/faker';

console.log(fakerEN_HK.location.zipCode()); // Error // [!code error]
```

For these cases, we explicitly set the data to `null` to clarify, that we have thought about it, but there are no valid values to put there.
We could have used an empty array `[]`, but some locale data are stored as objects `{}`,
so `null` works for both of them without custom downstream handling of missing data.

::: tip Note
We are by far no experts in all provided languages/countries/locales,
so if you think this is an error for your locale, please create an issue and consider contributing the relevant data.
:::

If you want to use other fallback data instead, you can define them like this:

```ts{4}
import { Faker, en, en_HK } from '@faker-js/faker';

const faker = new Faker({
locale: [{ location: { postcode: en.location.postcode } }, en_HK],
});
console.log(faker.location.zipCode()); // '17551-0348'
```

::: warning Warning
Since `null` is considered present data, it will not use any fallbacks for that.
So the following code does **not** work:

```ts
import { Faker, en, en_HK } from '@faker-js/faker';

const faker = new Faker({
locale: [en_HK, { location: { postcode: en.location.postcode } }], // [!code warning]
});
console.log(faker.location.zipCode()); // Error // [!code error]
```

:::

See also: [Custom Locales and Fallbacks](#custom-locales-and-fallbacks)