docs: localization

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' },

docs/.vitepress/config.ts

@@ -130,6 +130,10 @@ export default defineConfig({
               text: 'Getting Started',
               link: '/guide/',
             },
+            {
+              text: 'Localization',
+              link: '/guide/localization',
+            },
           ],
         },
         {

docs/api/localization.md → 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 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
+
 <!-- LOCALES-AUTO-GENERATED-START -->
 
 <!-- Run 'pnpm run generate:locales' to update. -->
@@ -78,16 +95,3 @@ faker.locale = 'de';
 | zu_ZA       | Zulu (South Africa)       |
 
 <!-- LOCALES-AUTO-GENERATED-END -->
-
-## 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');
-```

scripts/apidoc.ts

@@ -34,7 +34,6 @@ async function build(): Promise<void> {
   patchProject(project);
 
   const modulesPages: PageIndex = [];
-  modulesPages.push({ text: 'Localization', link: '/api/localization.html' });
   modulesPages.push(...processModuleMethods(project));
   modulesPages.push(...processDirectMethods(project));
   writeApiPagesIndex(modulesPages);

scripts/generateLocales.ts

@@ -28,7 +28,7 @@ const pathLocalesIndex = resolve(pathLocales, 'index.ts');
 const pathDocsApiLocalization = resolve(
   pathRoot,
   'docs',
-  'api',
+  'guide',
   'localization.md'
 );