Merge branch 'next' into locale/introduce-metadata

Author: ST-DDT

.editorconfig

@@ -9,5 +9,4 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 
 [*.md]
-max_line_length = off
 trim_trailing_whitespace = false

docs/api/ApiIndex.vue

@@ -96,7 +96,9 @@ onUnmounted(() => window.removeEventListener('keydown', apiSearchFocusHandler));
       <h2 :id="slugify(section.text)">{{ section.text }}</h2>
       <div class="api-groups">
         <div v-for="item of section.items" :key="item.text" class="api-group">
-          <h3>{{ item.text }}</h3>
+          <h3>
+            <a :href="item.link + '.html'">{{ item.text }}</a>
+          </h3>
           <ul>
             <li v-for="h of item.headers" :key="h.anchor">
               <a :href="item.link + '.html#' + slugify(h.anchor)">{{
@@ -158,19 +160,19 @@ h3 {
   margin-bottom: 64px;
 }
 
-.api-groups a {
+.api-groups ul a {
   font-size: 15px;
   font-weight: 500;
   line-height: 2;
   color: var(--vp-c-text-code);
   transition: color 0.5s;
 }
 
-.dark .api-groups a {
+.dark .api-groups ul a {
   font-weight: 400;
 }
 
-.api-groups a:hover {
+.api-groups ul a:hover {
   color: var(--vp-c-green);
   transition: none;
 }
@@ -233,7 +235,7 @@ h3 {
     padding-top: 32px;
   }
 
-  .api-groups a {
+  .api-groups ul a {
     font-size: 14px;
   }
 

docs/guide/localization.md

@@ -44,7 +44,7 @@ If our built-in faker instances don't satisfy your needs, you can build your own
 
 ```ts
 import type { LocaleDefinition } from '@faker-js/faker';
-import { Faker, de_CH, de, en } from '@faker-js/faker';
+import { Faker, de_CH, de, en, base } from '@faker-js/faker';
 
 const customLocale: LocaleDefinition = {
   title: 'My custom locale',
@@ -54,10 +54,18 @@ const customLocale: LocaleDefinition = {
 };
 
 export const customFaker = new Faker({
-  locale: [customLocale, de_CH, de, en, global],
+  locale: [customLocale, de_CH, de, en, base],
 });
 ```
 
+In this example there are 5 locales. Each of these is checked in order, and the first locale which contains the requested data will be used:
+
+- `customLocale` is your custom locale definition which will override all other fallback definitions.
+- `de_CH` is a specific locale definition that overrides some German definitions with `CH` (Switzerland) data.
+- `de` is a generic `de` (German) locale definition.
+- `en` is a generic `en` (English) locale definition. This is our most complete locale, so we add it to fill some gaps. Depending on your needs, you might want or not want to have it as a fallback.
+- `base` is the base locale definition which contains definitions that can be used in every language (e.g. emojis).
+
 ## Available locales
 
 <!-- LOCALES-AUTO-GENERATED-START -->
@@ -69,6 +77,7 @@ export const customFaker = new Faker({
 | `af_ZA`       | Afrikaans                 | `fakerAF_ZA`       |
 | `ar`          | Arabic                    | `fakerAR`          |
 | `az`          | Azerbaijani               | `fakerAZ`          |
+| `base`        | Base                      | `fakerBASE`        |
 | `cz`          | Czech                     | `fakerCZ`          |
 | `de`          | German                    | `fakerDE`          |
 | `de_AT`       | German (Austria)          | `fakerDE_AT`       |

docs/guide/upgrading.md

@@ -60,12 +60,12 @@ const b = customFaker.internet.emoji();
 **New**
 
 ```ts
-import { Faker, de_CH, de, en, global } from '@faker-js/faker';
+import { Faker, de_CH, de, en, base } from '@faker-js/faker';
 
 // same as fakerDE_CH
 export const customFaker = new Faker({
   // Now multiple fallbacks are supported
-  locale: [de_CH, de, en, global],
+  locale: [de_CH, de, en, base],
 });
 const a = customFaker.internet.email();
 const b = customFaker.internet.emoji();

package.json

@@ -112,7 +112,7 @@
     "glob": "~9.3.2",
     "npm-run-all": "~4.1.5",
     "picocolors": "~1.0.0",
-    "prettier": "2.8.4",
+    "prettier": "2.8.7",
     "prettier-plugin-organize-imports": "~3.2.2",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",

pnpm-lock.yaml

@@ -1,7 +1,7 @@
 import type { DeclarationReflection, ProjectReflection } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import { writeApiDocsData, writeApiDocsModulePage } from './apiDocsWriter';
-import { analyzeSignature, toBlock } from './signature';
+import { analyzeSignature, stripAbsoluteFakerUrls, toBlock } from './signature';
 import {
   extractModuleFieldName,
   extractModuleName,
@@ -40,7 +40,7 @@ function processModuleMethod(module: DeclarationReflection): PageAndDiffIndex {
   const moduleName = extractModuleName(module);
   const moduleFieldName = extractModuleFieldName(module);
   console.log(`Processing Module ${moduleName}`);
-  const comment = toBlock(module.comment);
+  const comment = stripAbsoluteFakerUrls(toBlock(module.comment));
 
   const methods: Method[] = [];
 

scripts/apidoc/moduleMethods.ts

@@ -44,6 +44,10 @@ export function toBlock(comment?: Comment): string {
   return joinTagParts(comment?.summary) || 'Missing';
 }
 
+export function stripAbsoluteFakerUrls(markdown: string): string {
+  return markdown.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/');
+}
+
 let markdown: MarkdownRenderer;
 
 export async function initMarkdownRenderer(): Promise<void> {

scripts/apidoc/signature.ts

@@ -126,10 +126,15 @@ function generateLocaleFile(locale: string): void {
     }
   }
 
-  if (locales[locales.length - 1] !== 'en') {
+  // TODO christopher 2023-03-07: Remove 'en' fallback in a separate PR
+  if (locales[locales.length - 1] !== 'en' && locale !== 'base') {
     locales.push('en');
   }
 
+  if (locales[locales.length - 1] !== 'base') {
+    locales.push('base');
+  }
+
   let content = `
       ${autoGeneratedCommentHeader}
 

scripts/generateLocales.ts

@@ -45,17 +45,17 @@ export type LocationDefinitions = LocaleEntry<{
   country_code: Array<{ alpha2: string; alpha3: string }>;
 
   /**
-   * The names of this country's states.
+   * The names of this country's states, or other first-level administrative areas.
    */
   state: string[];
 
   /**
-   * The abbreviated names of this country's states.
+   * The abbreviated names of this country's states, or other first-level administrative areas.
    */
   state_abbr: string[];
 
   /**
-   * The names of counties inside the country or state.
+   * The names of counties, or other second-level administrative areas, inside the country's states.
    */
   county: string[];