diff --git a/README.md b/README.md index bb67fadadf5..73bfa9e59f3 100644 --- a/README.md +++ b/README.md @@ -121,9 +121,9 @@ 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. +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 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/.vitepress/config.ts b/docs/.vitepress/config.ts index a3b716337e5..aad3bdf2ace 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -130,6 +130,10 @@ export default defineConfig({ text: 'Getting Started', link: '/guide/', }, + { + text: 'Localization', + link: '/guide/localization', + }, { text: 'Upgrading to v7', link: '/guide/upgrading', 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/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..c6eca2148d3 100644 --- a/docs/api/localization.md +++ b/docs/guide/localization.md @@ -1,18 +1,35 @@ # Localization -As of version `v2.0.0` Faker has support for multiple localities. +## Switching locales -The default language locale is set to English. +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')`. -Setting a new locale is simple: +::: tip +Alternatively you can also just use `faker.locale = 'de'` instead to switch the locale. +::: -```js -// sets locale to de -faker.setLocale('de'); -// or -faker.locale = 'de'; +## Individual localized packages + +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. + +_But we got your back!_ +When encountering such a problem in a test or production environment, you can use the individual localized packages. + +```ts +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 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. +All locales together are around 5 MB in size. +::: + +## Available locales + @@ -78,16 +95,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/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); diff --git a/scripts/generateLocales.ts b/scripts/generateLocales.ts index 1d41948ffcc..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. @@ -25,10 +25,10 @@ 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', - 'api', + 'guide', 'localization.md' ); @@ -323,13 +323,13 @@ let indexContent = ` indexContent = format(indexContent, prettierTsOptions); writeFileSync(pathLocalesIndex, indexContent); -// docs/api/localization.md +// docs/guide/localization.md 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);