From 33a90fb5513c9593747511de98f8df861230885f Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 11:24:22 +0200 Subject: [PATCH 01/11] docs(guide): add locale error handling sections --- docs/guide/localization.md | 110 +++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index fe7c60a4291..8e9a602069b 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -165,3 +165,113 @@ 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' +``` + +If you want to use custom data instead, you can do it like this: + +```ts{4} +import { Faker, el } from '@faker-js/faker'; + +const faker = new Faker({ + locale: [{ location: { country: ['Ελλάδα'] } }, el], +}); +console.log(faker.location.country()); // 'Ελλάδα' +``` + +See also: [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) + +## 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. +Let's say you have a imaginary locale for the planet `mars`, if you call `fakerMars.location.country()`, +then you will get this error, because there aren't any countries' territories on mars. +The same applies to other locales and methods. + +```ts +import type { LocaleDefinition } from '@faker-js/faker'; + +export const mars: LocaleDefinition = { + location: { + country: null, + ... + }, + ... +}; +``` + +```ts +import { Faker } from '@faker-js/faker'; +import { mars } from 'mars'; + +const faker = new Faker({ + locale: mars, +}); +console.log(faker.location.country()); // 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{5} +import { Faker, en } from '@faker-js/faker'; +import { mars } from 'mars'; + +const faker = new Faker({ + locale: [{ location: { country: en.location.country } }, mars], +}); +console.log(faker.location.country()); // 'Belgium' +``` + +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 } from '@faker-js/faker'; + +const mars: LocaleDefinition = ...; + +const faker = new Faker({ + locale: [mars, { location: { state: en.location.state } }], +}); +console.log(faker.location.state()); // Error +``` + +See also: [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) From 3e624f7acc366722c829a22d65f55613ac0df164 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 11:42:55 +0200 Subject: [PATCH 02/11] docs: consistent examples --- docs/guide/localization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index 8e9a602069b..2b933f82269 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -269,9 +269,9 @@ import { Faker, en } from '@faker-js/faker'; const mars: LocaleDefinition = ...; const faker = new Faker({ - locale: [mars, { location: { state: en.location.state } }], + locale: [mars, { location: { country: en.location.country } }], }); -console.log(faker.location.state()); // Error +console.log(faker.location.country()); // Error ``` See also: [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) From 9ff7e6f73f1c2fa27355275a8efdb060c2ea06c7 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 20:27:11 +0200 Subject: [PATCH 03/11] chore: apply suggestions --- docs/guide/localization.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index 2b933f82269..41dd7127e95 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -201,7 +201,11 @@ const faker = new Faker({ console.log(faker.location.country()); // 'Ελλάδα' ``` -See also: [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) +::: tip Note + +Of course, you can use [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) for this as well. + +::: ## Handling Not-Applicable Data Errors @@ -212,7 +216,7 @@ If you think this is a bug, please report it at: https://github.com/faker-js/fak If you receive this error, this means the current locale is unable to provide reasonable values for that method. Let's say you have a imaginary locale for the planet `mars`, if you call `fakerMars.location.country()`, -then you will get this error, because there aren't any countries' territories on mars. +then you will get this error, because there aren't any countries' territories on mars, yet. The same applies to other locales and methods. ```ts @@ -252,7 +256,7 @@ If you want to use other fallback data instead, you can define them like this: ```ts{5} import { Faker, en } from '@faker-js/faker'; -import { mars } from 'mars'; +import { mars } from './locales/mars'; const faker = new Faker({ locale: [{ location: { country: en.location.country } }, mars], @@ -260,13 +264,14 @@ const faker = new Faker({ console.log(faker.location.country()); // 'Belgium' ``` +::: 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 } from '@faker-js/faker'; - -const mars: LocaleDefinition = ...; +import { mars } from './locales/mars'; const faker = new Faker({ locale: [mars, { location: { country: en.location.country } }], @@ -274,4 +279,6 @@ const faker = new Faker({ console.log(faker.location.country()); // Error ``` +::: + See also: [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) From 5c1954e39cc2f0514fbb4be04ee03cfe7ffdfe00 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 20:36:47 +0200 Subject: [PATCH 04/11] chore: apply suggestions --- docs/guide/localization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index 41dd7127e95..e3c664e850b 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -233,7 +233,7 @@ export const mars: LocaleDefinition = { ```ts import { Faker } from '@faker-js/faker'; -import { mars } from 'mars'; +import { mars } from './locales/mars'; const faker = new Faker({ locale: mars, From fdca831292f600194799dd3c05d5ea855bcb9428 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 20:53:16 +0200 Subject: [PATCH 05/11] chore: apply suggestions --- docs/guide/localization.md | 37 +++++++++---------------------------- 1 file changed, 9 insertions(+), 28 deletions(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index e3c664e850b..005870c2201 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -215,30 +215,13 @@ If you think this is a bug, please report it at: https://github.com/faker-js/fak ``` If you receive this error, this means the current locale is unable to provide reasonable values for that method. -Let's say you have a imaginary locale for the planet `mars`, if you call `fakerMars.location.country()`, -then you will get this error, because there aren't any countries' territories on mars, yet. +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 type { LocaleDefinition } from '@faker-js/faker'; - -export const mars: LocaleDefinition = { - location: { - country: null, - ... - }, - ... -}; -``` +import { fakerEN_HK } from '@faker-js/faker'; -```ts -import { Faker } from '@faker-js/faker'; -import { mars } from './locales/mars'; - -const faker = new Faker({ - locale: mars, -}); -console.log(faker.location.country()); // Error +console.log(fakerEN_HK.location.zipCode()); // 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. @@ -255,13 +238,12 @@ so if you think this is an error for your locale, please create an issue and con If you want to use other fallback data instead, you can define them like this: ```ts{5} -import { Faker, en } from '@faker-js/faker'; -import { mars } from './locales/mars'; +import { Faker, en, en_HK } from '@faker-js/faker'; const faker = new Faker({ - locale: [{ location: { country: en.location.country } }, mars], + locale: [{ location: { postcode: en.location.postcode } }, en_HK], }); -console.log(faker.location.country()); // 'Belgium' +console.log(faker.location.zipCode()); // '17551-0348' ``` ::: warning Warning @@ -270,13 +252,12 @@ 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 } from '@faker-js/faker'; -import { mars } from './locales/mars'; +import { Faker, en, en_HK } from '@faker-js/faker'; const faker = new Faker({ - locale: [mars, { location: { country: en.location.country } }], + locale: [en_HK, { location: { postcode: en.location.postcode } }], }); -console.log(faker.location.country()); // Error +console.log(faker.location.zipCode()); // Error ``` ::: From 2ec9e49bd42af2f344cef095271147e7988c9f74 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 20:58:19 +0200 Subject: [PATCH 06/11] chore: apply suggestions --- docs/guide/localization.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index 005870c2201..d847c306e5c 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -202,9 +202,7 @@ console.log(faker.location.country()); // 'Ελλάδα' ``` ::: tip Note - Of course, you can use [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) for this as well. - ::: ## Handling Not-Applicable Data Errors @@ -229,10 +227,8 @@ We could have used an empty array `[]`, but some locale data are stored as objec 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: @@ -247,7 +243,6 @@ 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: From f82e1c0724bb711681cef843a233bb40ee1717c2 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 20:58:38 +0200 Subject: [PATCH 07/11] chore: apply suggestions --- docs/guide/localization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index d847c306e5c..3245b442c34 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -226,7 +226,7 @@ For these cases, we explicitly set the data to `null` to clarify, that we have t 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 +::: 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. ::: From 23586fda0dc800ad5b86935548c7dd7f1b401e8d Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 20:59:23 +0200 Subject: [PATCH 08/11] chore: apply suggestions --- docs/guide/localization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index 3245b442c34..70092912dd2 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -233,7 +233,7 @@ so if you think this is an error for your locale, please create an issue and con If you want to use other fallback data instead, you can define them like this: -```ts{5} +```ts{4} import { Faker, en, en_HK } from '@faker-js/faker'; const faker = new Faker({ From 8999ffec8500b783cd4f809b3949f9d97f2e8f5b Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 21:08:02 +0200 Subject: [PATCH 09/11] chore: apply styling --- docs/guide/localization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index 70092912dd2..81e503e890d 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -219,7 +219,7 @@ The same applies to other locales and methods. ```ts import { fakerEN_HK } from '@faker-js/faker'; -console.log(fakerEN_HK.location.zipCode()); // Error +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. @@ -252,7 +252,7 @@ import { Faker, en, en_HK } from '@faker-js/faker'; const faker = new Faker({ locale: [en_HK, { location: { postcode: en.location.postcode } }], }); -console.log(faker.location.zipCode()); // Error +console.log(faker.location.zipCode()); // Error // [!code error] ``` ::: From 142d2bac057b34dbd1a4830e38d5683173d7c53c Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 13 Aug 2024 21:12:31 +0200 Subject: [PATCH 10/11] chore: apply styling 2 --- docs/guide/localization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index 81e503e890d..a26264e83b2 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -250,7 +250,7 @@ So the following code does **not** work: import { Faker, en, en_HK } from '@faker-js/faker'; const faker = new Faker({ - locale: [en_HK, { location: { postcode: en.location.postcode } }], + locale: [en_HK, { location: { postcode: en.location.postcode } }], // [!code warning] }); console.log(faker.location.zipCode()); // Error // [!code error] ``` From 4c89bbdd6d814425a8be18df7b459084ea2162d8 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 14 Aug 2024 18:23:02 +0200 Subject: [PATCH 11/11] Update docs/guide/localization.md Co-authored-by: DivisionByZero --- docs/guide/localization.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index a26264e83b2..f40a2f48a03 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -190,17 +190,6 @@ const faker = new Faker({ console.log(faker.location.country()); // 'Belgium' ``` -If you want to use custom data instead, you can do it like this: - -```ts{4} -import { Faker, el } from '@faker-js/faker'; - -const faker = new Faker({ - locale: [{ location: { country: ['Ελλάδα'] } }, el], -}); -console.log(faker.location.country()); // 'Ελλάδα' -``` - ::: tip Note Of course, you can use [Custom Locales and Fallbacks](#custom-locales-and-fallbacks) for this as well. :::