From a2a318c8d24aaaeee5b07a05330b07a2568aed20 Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 13:15:01 +0200 Subject: [PATCH 01/11] docs: locales --- docs/.vitepress/config.ts | 4 ++++ docs/guide/locales.md | 17 +++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 docs/guide/locales.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 59e2d1ba22a..2cd5e8087c8 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -130,6 +130,10 @@ export default defineConfig({ text: 'Getting Started', link: '/guide/', }, + { + text: 'Locales', + link: '/guide/locales', + }, ], }, { diff --git a/docs/guide/locales.md b/docs/guide/locales.md new file mode 100644 index 00000000000..a03befe9b66 --- /dev/null +++ b/docs/guide/locales.md @@ -0,0 +1,17 @@ +# Locales + +Did you know Faker supports many different locales? +By default when using `import { faker } from '@faker-js/faker'` you actually use every available locale that is supported by Faker and you can switch the locale at runtime with `faker.setLocale('de')`. + +::: info +Since [v7.3.0](https://github.com/faker-js/faker/releases/tag/v7.3.0) you can also just use `faker.locale = 'de'` instead to switch the locale. +::: + +There is one downside of using the default faker instance because it will load all locales into memory resulting in a slower startup time. So if you encounter performance issues e.g. while running tests you should consider using customized faker instances. +And we got you back! You can import specific pre-configured faker instances for each locale by just using e.g. `import { faker } from '@faker-js/faker/locale/de'`. +This will then just load the german locales with additional english locales as fallback. + +:::info +In v7 and earlier versions faker always use english as fallback. The english locales are around 600 KB in size. In v8 we plan to change the behavior and allow to create custom faker instances with e.g. only german but no english locales. +You will then safe these 600 KB of memory overhead but might run into issues when there is no value provided in the german locales. +::: From e767ec942eed88a8aa93bc310da2e6cec646f978 Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 14:15:04 +0200 Subject: [PATCH 02/11] docs: locales --- docs/guide/locales.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/guide/locales.md b/docs/guide/locales.md index a03befe9b66..50d0a63ef27 100644 --- a/docs/guide/locales.md +++ b/docs/guide/locales.md @@ -3,15 +3,14 @@ Did you know Faker supports many different locales? By default when using `import { faker } from '@faker-js/faker'` you actually use every available locale that is supported by Faker and you can switch the locale at runtime with `faker.setLocale('de')`. -::: info -Since [v7.3.0](https://github.com/faker-js/faker/releases/tag/v7.3.0) you can also just use `faker.locale = 'de'` instead to switch the locale. +::: tip +Alternatively you can also just use `faker.locale = 'de'` instead to switch the locale. ::: There is one downside of using the default faker instance because it will load all locales into memory resulting in a slower startup time. So if you encounter performance issues e.g. while running tests you should consider using customized faker instances. -And we got you back! You can import specific pre-configured faker instances for each locale by just using e.g. `import { faker } from '@faker-js/faker/locale/de'`. -This will then just load the german locales with additional english locales as fallback. +And we got your back! You can import specific pre-configured faker instances for each locale by just using e.g. `import { faker } from '@faker-js/faker/locale/de'`. +This will then just load the German locales with additional English locales as fallback. The fallback is required due to not all locales supporting all features. If you encounter a missing locale feature in your required language, feel free to open a Pull Request fixing that issue. -:::info -In v7 and earlier versions faker always use english as fallback. The english locales are around 600 KB in size. In v8 we plan to change the behavior and allow to create custom faker instances with e.g. only german but no english locales. -You will then safe these 600 KB of memory overhead but might run into issues when there is no value provided in the german locales. +::: info +The English locales are around 600 KB in size. ::: From 08c056d845381d2c3cf73efacaaf7c1b2a881cc6 Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 14:20:19 +0200 Subject: [PATCH 03/11] docs: locales --- docs/guide/locales.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guide/locales.md b/docs/guide/locales.md index 50d0a63ef27..5e1a0ebb476 100644 --- a/docs/guide/locales.md +++ b/docs/guide/locales.md @@ -12,5 +12,6 @@ And we got your back! You can import specific pre-configured faker instances for This will then just load the German locales with additional English locales as fallback. The fallback is required due to not all locales supporting all features. If you encounter a missing locale feature in your required language, feel free to open a Pull Request fixing that issue. ::: info -The English locales are around 600 KB in size. +The English locales are around 600 KB in size. +All locales together are around 5 MB in size. ::: From e8c5d8532ad2f35ac409eb8cbd21bcfc6bfffac4 Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 14:37:57 +0200 Subject: [PATCH 04/11] docs: merging old localization docs into new docs --- docs/.vitepress/config.ts | 4 +-- docs/guide/locales.md | 17 --------- docs/{api => guide}/localization.md | 54 +++++++++++++++++++++-------- scripts/generateLocales.ts | 2 +- 4 files changed, 42 insertions(+), 35 deletions(-) delete mode 100644 docs/guide/locales.md rename docs/{api => guide}/localization.md (69%) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 2cd5e8087c8..90edabf7ead 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -131,8 +131,8 @@ export default defineConfig({ link: '/guide/', }, { - text: 'Locales', - link: '/guide/locales', + text: 'Localization', + link: '/guide/localization', }, ], }, diff --git a/docs/guide/locales.md b/docs/guide/locales.md deleted file mode 100644 index 5e1a0ebb476..00000000000 --- a/docs/guide/locales.md +++ /dev/null @@ -1,17 +0,0 @@ -# Locales - -Did you know Faker supports many different locales? -By default when using `import { faker } from '@faker-js/faker'` you actually use every available locale that is supported by Faker and you can switch the locale at runtime with `faker.setLocale('de')`. - -::: tip -Alternatively you can also just use `faker.locale = 'de'` instead to switch the locale. -::: - -There is one downside of using the default faker instance because it will load all locales into memory resulting in a slower startup time. So if you encounter performance issues e.g. while running tests you should consider using customized faker instances. -And we got your back! You can import specific pre-configured faker instances for each locale by just using e.g. `import { faker } from '@faker-js/faker/locale/de'`. -This will then just load the German locales with additional English locales as fallback. The fallback is required due to not all locales supporting all features. If you encounter a missing locale feature in your required language, feel free to open a Pull Request fixing that issue. - -::: info -The English locales are around 600 KB in size. -All locales together are around 5 MB in size. -::: diff --git a/docs/api/localization.md b/docs/guide/localization.md similarity index 69% rename from docs/api/localization.md rename to docs/guide/localization.md index 50e09665f9a..acb38098e6d 100644 --- a/docs/api/localization.md +++ b/docs/guide/localization.md @@ -1,8 +1,10 @@ # Localization -As of version `v2.0.0` Faker has support for multiple localities. +## Switching locales -The default language locale is set to English. +Faker has support for multiple locales. + +The default locale is set to English. Setting a new locale is simple: @@ -13,6 +15,41 @@ faker.setLocale('de'); faker.locale = 'de'; ``` +## Individual localized packages + +Faker supports incremental loading of locales. + +By default, requiring `faker` will include _all_ locale data. + +In a production environment, you may only want to include the locale data for a specific set of locales. + +```js +// loads only de locale +const { faker } = require('@faker-js/faker/locale/de'); +``` + +--- + +Did you know Faker supports many different locales? +By default when using `import { faker } from '@faker-js/faker'` you actually use every available locale that is supported by Faker and you can switch the locale at runtime with `faker.setLocale('de')`. + +::: tip +Alternatively you can also just use `faker.locale = 'de'` instead to switch the locale. +::: + +There is one downside of using the default faker instance because it will load all locales into memory resulting in a slower startup time. So if you encounter performance issues e.g. while running tests you should consider using customized faker instances. +And we got your back! You can import specific pre-configured faker instances for each locale by just using e.g. `import { faker } from '@faker-js/faker/locale/de'`. +This will then just load the German locales with additional English locales as fallback. The fallback is required due to not all locales supporting all features. If you encounter a missing locale feature in your required language, feel free to open a Pull Request fixing that issue. + +::: info +The English locales are around 600 KB in size. +All locales together are around 5 MB in size. +::: + +--- + +## Available locales + @@ -78,16 +115,3 @@ faker.locale = 'de'; | zu_ZA | Zulu (South Africa) | - -## Individual Localization Packages - -As of version `v3.0.0` Faker supports incremental loading of locales. - -By default, requiring `faker` will include _all_ locale data. - -In a production environment, you may only want to include the locale data for a specific set of locales. - -```js -// loads only de locale -const { faker } = require('@faker-js/faker/locale/de'); -``` diff --git a/scripts/generateLocales.ts b/scripts/generateLocales.ts index 1d41948ffcc..1e979a0faac 100644 --- a/scripts/generateLocales.ts +++ b/scripts/generateLocales.ts @@ -28,7 +28,7 @@ const pathLocalesIndex = resolve(pathLocales, 'index.ts'); const pathDocsApiLocalization = resolve( pathRoot, 'docs', - 'api', + 'guide', 'localization.md' ); From 20703fbff4551a577d0442a88d55b03b55cdb0aa Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 14:52:59 +0200 Subject: [PATCH 05/11] docs: remove old link --- docs/.vitepress/api-pages.ts | 1 - docs/guide/localization.md | 2 -- scripts/apidoc.ts | 1 - 3 files changed, 4 deletions(-) diff --git a/docs/.vitepress/api-pages.ts b/docs/.vitepress/api-pages.ts index 8e8b19d7875..dd2df610ee5 100644 --- a/docs/.vitepress/api-pages.ts +++ b/docs/.vitepress/api-pages.ts @@ -16,7 +16,6 @@ export const apiPages = [ { text: 'Helpers', link: '/api/helpers.html' }, { text: 'Image', link: '/api/image.html' }, { text: 'Internet', link: '/api/internet.html' }, - { text: 'Localization', link: '/api/localization.html' }, { text: 'Lorem', link: '/api/lorem.html' }, { text: 'Mersenne', link: '/api/mersenne.html' }, { text: 'Music', link: '/api/music.html' }, diff --git a/docs/guide/localization.md b/docs/guide/localization.md index acb38098e6d..1573e836dbd 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -17,8 +17,6 @@ faker.locale = 'de'; ## Individual localized packages -Faker supports incremental loading of locales. - By default, requiring `faker` will include _all_ locale data. In a production environment, you may only want to include the locale data for a specific set of locales. diff --git a/scripts/apidoc.ts b/scripts/apidoc.ts index 165034bc885..0ad01248542 100644 --- a/scripts/apidoc.ts +++ b/scripts/apidoc.ts @@ -34,7 +34,6 @@ async function build(): Promise { patchProject(project); const modulesPages: PageIndex = []; - modulesPages.push({ text: 'Localization', link: '/api/localization.html' }); modulesPages.push(...processModuleMethods(project)); modulesPages.push(...processDirectMethods(project)); writeApiPagesIndex(modulesPages); From 697d00738ae7a3ab6b1e4c99c7b066e9fe04e2c3 Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 15:10:10 +0200 Subject: [PATCH 06/11] docs: merging old and new docs --- docs/guide/localization.md | 42 +++++++++++--------------------------- 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/docs/guide/localization.md b/docs/guide/localization.md index 1573e836dbd..b4a68944c21 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -2,50 +2,32 @@ ## Switching locales -Faker has support for multiple locales. - -The default locale is set to English. - -Setting a new locale is simple: +Did you know Faker supports many different locales? +By default when using `import { faker } from '@faker-js/faker'` you actually use every available locale that is supported by Faker and you can switch the locale at runtime with `faker.setLocale('de')`. -```js -// sets locale to de -faker.setLocale('de'); -// or -faker.locale = 'de'; -``` +::: tip +Alternatively you can also just use `faker.locale = 'de'` instead to switch the locale. +::: ## Individual localized packages -By default, requiring `faker` will include _all_ locale data. +By default, Faker will include **all** locale data. +This might result in loading around 5 MB of data into memory and slow down startup times. -In a production environment, you may only want to include the locale data for a specific set of locales. +_But we got your back!_ +When encountering such a problem in a test or production environment, you can use the individual localized packages. -```js -// loads only de locale -const { faker } = require('@faker-js/faker/locale/de'); +```ts +import { faker } from '@faker-js/faker/locale/de'; ``` ---- - -Did you know Faker supports many different locales? -By default when using `import { faker } from '@faker-js/faker'` you actually use every available locale that is supported by Faker and you can switch the locale at runtime with `faker.setLocale('de')`. - -::: tip -Alternatively you can also just use `faker.locale = 'de'` instead to switch the locale. -::: - -There is one downside of using the default faker instance because it will load all locales into memory resulting in a slower startup time. So if you encounter performance issues e.g. while running tests you should consider using customized faker instances. -And we got your back! You can import specific pre-configured faker instances for each locale by just using e.g. `import { faker } from '@faker-js/faker/locale/de'`. -This will then just load the German locales with additional English locales as fallback. The fallback is required due to not all locales supporting all features. If you encounter a missing locale feature in your required language, feel free to open a Pull Request fixing that issue. +This will then just load the German locales with additional English locales as fallback. The fallback is required due to not all locales contain data for all features. If you encounter a missing locale entry in your selected language, feel free to open a Pull Request fixing that issue. ::: info The English locales are around 600 KB in size. All locales together are around 5 MB in size. ::: ---- - ## Available locales From 542150b63bd3c55d50a598d9e62f0354ca50b646 Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 15:12:03 +0200 Subject: [PATCH 07/11] docs: improve wording --- 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 b4a68944c21..83362b140f7 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -3,7 +3,7 @@ ## Switching locales Did you know Faker supports many different locales? -By default when using `import { faker } from '@faker-js/faker'` you actually use every available locale that is supported by Faker and you can switch the locale at runtime with `faker.setLocale('de')`. +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')`. ::: tip Alternatively you can also just use `faker.locale = 'de'` instead to switch the locale. From 8b11902a89c577fd1f1b5d2993c07dec69e19b00 Mon Sep 17 00:00:00 2001 From: Shinigami Date: Sat, 10 Sep 2022 15:47:28 +0200 Subject: [PATCH 08/11] Update docs/guide/localization.md Co-authored-by: ST-DDT --- 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 83362b140f7..c6eca2148d3 100644 --- a/docs/guide/localization.md +++ b/docs/guide/localization.md @@ -21,7 +21,7 @@ When encountering such a problem in a test or production environment, you can us import { faker } from '@faker-js/faker/locale/de'; ``` -This will then just load the German locales with additional English locales as fallback. The fallback is required due to not all locales contain data for all features. If you encounter a missing locale entry in your selected language, feel free to open a Pull Request fixing that issue. +This will then just load the German locales with additional English locales as fallback. The fallback is required due to not all locales containing data for all features. If you encounter a missing locale entry in your selected language, feel free to open a Pull Request fixing that issue. ::: info The English locales are around 600 KB in size. From a1efce082ed743325a855368e67493a3c114f1fe Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 15:49:56 +0200 Subject: [PATCH 09/11] chore: rename constant --- scripts/generateLocales.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/generateLocales.ts b/scripts/generateLocales.ts index 1e979a0faac..4c95d5ef2a0 100644 --- a/scripts/generateLocales.ts +++ b/scripts/generateLocales.ts @@ -25,7 +25,7 @@ const pathRoot = resolve(__dirname, '..'); const pathLocale = resolve(pathRoot, 'src', 'locale'); const pathLocales = resolve(pathRoot, 'src', 'locales'); const pathLocalesIndex = resolve(pathLocales, 'index.ts'); -const pathDocsApiLocalization = resolve( +const pathDocsGuideLocalization = resolve( pathRoot, 'docs', 'guide', @@ -327,9 +327,9 @@ writeFileSync(pathLocalesIndex, indexContent); localizationLocales = format(localizationLocales, prettierMdOptions); -let localizationContent = readFileSync(pathDocsApiLocalization, 'utf-8'); +let localizationContent = readFileSync(pathDocsGuideLocalization, 'utf-8'); localizationContent = localizationContent.replace( /(^$).*(^$)/gms, `$1\n\n\n\n${localizationLocales}\n$2` ); -writeFileSync(pathDocsApiLocalization, localizationContent); +writeFileSync(pathDocsGuideLocalization, localizationContent); From 422cc65480664393a7d9362955bf9e52b4031dfa Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 15:53:40 +0200 Subject: [PATCH 10/11] chore: fix links --- README.md | 2 +- docs/api/.gitignore | 1 - scripts/generateLocales.ts | 4 ++-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index bb67fadadf5..45b7c1a4905 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,7 @@ Setting a new locale is simple: faker.locale = 'de'; ``` -See our documentation for a list of [provided languages](https://fakerjs.dev/api/localization.html#localization) +See our documentation for a list of [provided languages](https://fakerjs.dev/guide/localization.html#available-locales) Please note that not every locale provides data for every module. In out pre-made locales, we fallback to english in such a case as this is the most complete and most common used language. diff --git a/docs/api/.gitignore b/docs/api/.gitignore index fc720b3c131..47b11a83ed7 100644 --- a/docs/api/.gitignore +++ b/docs/api/.gitignore @@ -1,7 +1,6 @@ # Markdown *.md !index.md -!localization.md # TypeScript *.ts diff --git a/scripts/generateLocales.ts b/scripts/generateLocales.ts index 4c95d5ef2a0..dea43bcd001 100644 --- a/scripts/generateLocales.ts +++ b/scripts/generateLocales.ts @@ -4,7 +4,7 @@ * - `src/locale/.ts` * - `src/locales//index.ts` * - `src/locales///index.ts` - * - `src/docs/api/localization.md` + * - `src/docs/guide/localization.md` * * If you wish to edit all/specific locale data files you can do so using the * `updateLocaleFileHook()` method. @@ -323,7 +323,7 @@ let indexContent = ` indexContent = format(indexContent, prettierTsOptions); writeFileSync(pathLocalesIndex, indexContent); -// docs/api/localization.md +// docs/guide/localization.md localizationLocales = format(localizationLocales, prettierMdOptions); From a548c8a24b26e69ac70dcf0f6bd75ed73ae2a7e5 Mon Sep 17 00:00:00 2001 From: Shinigami Date: Sat, 10 Sep 2022 19:10:56 +0200 Subject: [PATCH 11/11] Update README.md Co-authored-by: Eric Cheng --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 45b7c1a4905..73bfa9e59f3 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ faker.locale = 'de'; See our documentation for a list of [provided languages](https://fakerjs.dev/guide/localization.html#available-locales) -Please note that not every locale provides data for every module. In out pre-made locales, we fallback to english in such a case as this is the most complete and most common used language. +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. ## ⚙️ Setting a randomness seed