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

1 files changed, 82 insertions, 0 deletions

diff --git a/docs/guide/localization.md b/docs/guide/localization.md
index fe7c60a4..f40a2f48 100644
--- a/docs/guide/localization.md
+++ b/docs/guide/localization.md
@@ -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)