docs: localization (#1364)

Co-authored-by: ST-DDT <[email protected]>
Co-authored-by: Leyla Jähnig [email protected]
Co-authored-by: Eric Cheng <[email protected]>

Author: 3 people

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
 

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',
+            },
             {
               text: 'Upgrading to v7',
               link: '/guide/upgrading',

docs/api/.gitignore

@@ -1,7 +1,6 @@
 # Markdown
 *.md
 !index.md
-!localization.md
 
 # TypeScript
 *.ts

docs/api/localization.md renamed to 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
+
 <!-- 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

@@ -4,7 +4,7 @@
  * - `src/locale/<locale>.ts`
  * - `src/locales/<locale>/index.ts`
  * - `src/locales/<locale>/<module...>/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(
   /(^<!-- LOCALES-AUTO-GENERATED-START -->$).*(^<!-- LOCALES-AUTO-GENERATED-END -->$)/gms,
   `$1\n\n<!-- Run '${scriptCommand}' to update. -->\n\n${localizationLocales}\n$2`
 );
-writeFileSync(pathDocsApiLocalization, localizationContent);
+writeFileSync(pathDocsGuideLocalization, localizationContent);