feat(locale): add additional metadata properties (#2025)

docs/guide/localization.md

@@ -74,7 +74,7 @@ In this example there are 5 locales. Each of these is checked in order, and the
 
 | Locale        | Name                      | Faker              |
 | :------------ | :------------------------ | :----------------- |
-| `af_ZA`       | Afrikaans                 | `fakerAF_ZA`       |
+| `af_ZA`       | Afrikaans (South Africa)  | `fakerAF_ZA`       |
 | `ar`          | Arabic                    | `fakerAR`          |
 | `az`          | Azerbaijani               | `fakerAZ`          |
 | `base`        | Base                      | `fakerBASE`        |
@@ -98,7 +98,7 @@ In this example there are 5 locales. Each of these is checked in order, and the
 | `en_ZA`       | English (South Africa)    | `fakerEN_ZA`       |
 | `es`          | Spanish                   | `fakerES`          |
 | `es_MX`       | Spanish (Mexico)          | `fakerES_MX`       |
-| `fa`          | Farsi                     | `fakerFA`          |
+| `fa`          | Farsi/Persian             | `fakerFA`          |
 | `fi`          | Finnish                   | `fakerFI`          |
 | `fr`          | French                    | `fakerFR`          |
 | `fr_BE`       | French (Belgium)          | `fakerFR_BE`       |
@@ -109,31 +109,31 @@ In this example there are 5 locales. Each of these is checked in order, and the
 | `hr`          | Croatian                  | `fakerHR`          |
 | `hu`          | Hungarian                 | `fakerHU`          |
 | `hy`          | Armenian                  | `fakerHY`          |
-| `id_ID`       | Indonesian                | `fakerID_ID`       |
+| `id_ID`       | Indonesian (Indonesia)    | `fakerID_ID`       |
 | `it`          | Italian                   | `fakerIT`          |
 | `ja`          | Japanese                  | `fakerJA`          |
 | `ka_GE`       | Georgian (Georgia)        | `fakerKA_GE`       |
 | `ko`          | Korean                    | `fakerKO`          |
 | `lv`          | Latvian                   | `fakerLV`          |
 | `mk`          | Macedonian                | `fakerMK`          |
-| `nb_NO`       | Norwegian                 | `fakerNB_NO`       |
-| `ne`          | Nepalese                  | `fakerNE`          |
+| `nb_NO`       | Norwegian (Norway)        | `fakerNB_NO`       |
+| `ne`          | Nepali                    | `fakerNE`          |
 | `nl`          | Dutch                     | `fakerNL`          |
 | `nl_BE`       | Dutch (Belgium)           | `fakerNL_BE`       |
 | `pl`          | Polish                    | `fakerPL`          |
 | `pt_BR`       | Portuguese (Brazil)       | `fakerPT_BR`       |
 | `pt_PT`       | Portuguese (Portugal)     | `fakerPT_PT`       |
 | `ro`          | Romanian                  | `fakerRO`          |
 | `ru`          | Russian                   | `fakerRU`          |
-| `sk`          | Slovakian                 | `fakerSK`          |
-| `sr_RS_latin` | Serbian (Latin)           | `fakerSR_RS_latin` |
+| `sk`          | Slovak                    | `fakerSK`          |
+| `sr_RS_latin` | Serbian (Serbia, Latin)   | `fakerSR_RS_latin` |
 | `sv`          | Swedish                   | `fakerSV`          |
 | `th`          | Thai                      | `fakerTH`          |
 | `tr`          | Turkish                   | `fakerTR`          |
 | `uk`          | Ukrainian                 | `fakerUK`          |
 | `ur`          | Urdu                      | `fakerUR`          |
 | `vi`          | Vietnamese                | `fakerVI`          |
-| `zh_CN`       | Chinese                   | `fakerZH_CN`       |
+| `zh_CN`       | Chinese (China)           | `fakerZH_CN`       |
 | `zh_TW`       | Chinese (Taiwan)          | `fakerZH_TW`       |
 | `zu_ZA`       | Zulu (South Africa)       | `fakerZU_ZA`       |
 

src/definitions/definitions.ts

@@ -32,7 +32,7 @@ export type LocaleEntry<T extends Record<string, unknown>> = Partial<T> &
  * that most properties are optional and extra properties are allowed.
  */
 export type LocaleDefinition = {
-  metadata: MetadataDefinitions;
+  metadata?: MetadataDefinitions;
   airline?: AirlineDefinitions;
   animal?: AnimalDefinitions;
   color?: ColorDefinitions;

src/definitions/metadata.ts

@@ -1,6 +1,60 @@
-export type MetadataDefinitions = {
+import type { LocaleEntry } from './definitions';
+
+/**
+ * Metadata for pre-built locales.
+ */
+export type PreBuiltMetadataDefinitions = {
   /**
    * The English name of the language (and the specific country, if defined).
    */
   title: string;
-} & Record<string, unknown>;
+  /**
+   * The full code of the locale, including the country code if applicable.
+   */
+  code: string;
+  /**
+   * The endonym (native name) of the language (and the specific country, if defined).
+   *
+   * @see https://en.wikipedia.org/wiki/List_of_countries_and_dependencies_and_their_capitals_in_native_languages
+   */
+  endonym: string;
+  /**
+   * The ISO 639-1 code of the language.
+   *
+   * @see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+   */
+  language: string;
+  /**
+   * The specific variant of the language. This usually refers to a dialect or slang.
+   */
+  variant?: string;
+  /**
+   * The direction of the language, either 'ltr' (left to right) or 'rtl' (right to left).
+   */
+  dir: 'ltr' | 'rtl';
+  /**
+   * The ISO 15924 code of the script.
+   *
+   * @see https://en.wikipedia.org/wiki/ISO_15924
+   */
+  script: string;
+};
+
+/**
+ * Metadata for pre-built locales for a specific country.
+ */
+export type PreBuiltMetadataDefinitionsForCountry =
+  PreBuiltMetadataDefinitions & {
+    /**
+     * The ISO 3166-1 alpha-2 code of the country.
+     *
+     * @see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+     */
+    country: string;
+  };
+
+/**
+ * Metadata for the current locale.
+ */
+export type MetadataDefinitions =
+  LocaleEntry<PreBuiltMetadataDefinitionsForCountry>;

src/locales/af_ZA/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
-  title: 'Afrikaans',
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
+  title: 'Afrikaans (South Africa)',
+  code: 'af_ZA',
+  country: 'ZA',
+  language: 'af',
+  endonym: 'Afrikaans (Suid-Afrika)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/ar/metadata.ts

@@ -1,7 +1,12 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitions } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitions = {
   title: 'Arabic',
+  code: 'ar',
+  language: 'ar',
+  endonym: 'اَلْعَرَبِيَّةُ',
+  dir: 'rtl',
+  script: 'Arab',
 };
 
 export default metadata;

src/locales/az/metadata.ts

@@ -1,7 +1,12 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitions } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitions = {
   title: 'Azerbaijani',
+  code: 'az',
+  language: 'az',
+  endonym: 'azərbaycan dili',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/base/metadata.ts

@@ -2,6 +2,7 @@ import type { MetadataDefinitions } from '../..';
 
 const metadata: MetadataDefinitions = {
   title: 'Base',
+  code: 'base',
 };
 
 export default metadata;

src/locales/cs_CZ/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
   title: 'Czech (Czechia)',
+  code: 'cs_CZ',
+  country: 'CZ',
+  language: 'cs',
+  endonym: 'čeština (Česká republika)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/de/metadata.ts

@@ -1,7 +1,12 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitions } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitions = {
   title: 'German',
+  code: 'de',
+  language: 'de',
+  endonym: 'Deutsch',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/de_AT/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
   title: 'German (Austria)',
+  code: 'de_AT',
+  country: 'AT',
+  language: 'de',
+  endonym: 'Deutsch (Österreich)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/de_CH/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
   title: 'German (Switzerland)',
+  code: 'de_CH',
+  country: 'CH',
+  language: 'de',
+  endonym: 'Deutsch (Schweiz)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/dv/metadata.ts

@@ -1,7 +1,12 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitions } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitions = {
   title: 'Maldivian',
+  code: 'dv',
+  language: 'dv',
+  endonym: 'ދިވެހި',
+  dir: 'rtl',
+  script: 'Thaa',
 };
 
 export default metadata;

src/locales/el/metadata.ts

@@ -1,7 +1,12 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitions } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitions = {
   title: 'Greek',
+  code: 'el',
+  language: 'el',
+  endonym: 'Ελληνικά',
+  dir: 'ltr',
+  script: 'Grek',
 };
 
 export default metadata;

src/locales/en/metadata.ts

@@ -1,7 +1,12 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitions } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitions = {
   title: 'English',
+  code: 'en',
+  language: 'en',
+  endonym: 'English',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/en_AU/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
   title: 'English (Australia)',
+  code: 'en_AU',
+  country: 'AU',
+  language: 'en',
+  endonym: 'English (Australia)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/en_AU_ocker/metadata.ts

@@ -1,7 +1,14 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
   title: 'English (Australia Ocker)',
+  code: 'en_AU_ocker',
+  country: 'AU',
+  language: 'en',
+  variant: 'ocker',
+  endonym: 'English (Australia)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/en_BORK/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitions } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitions = {
   title: 'English (Bork)',
+  code: 'en_BORK',
+  variant: 'BORK',
+  language: 'en',
+  endonym: 'English (Bork)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/en_CA/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
   title: 'English (Canada)',
+  code: 'en_CA',
+  country: 'CA',
+  language: 'en',
+  endonym: 'English (Canada)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/en_GB/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
   title: 'English (Great Britain)',
+  code: 'en_GB',
+  country: 'GB',
+  language: 'en',
+  endonym: 'English (Great Britain)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;

src/locales/en_GH/metadata.ts

@@ -1,7 +1,13 @@
-import type { MetadataDefinitions } from '../..';
+import type { PreBuiltMetadataDefinitionsForCountry } from '../../definitions/metadata';
 
-const metadata: MetadataDefinitions = {
+const metadata: PreBuiltMetadataDefinitionsForCountry = {
   title: 'English (Ghana)',
+  code: 'en_GH',
+  country: 'GH',
+  language: 'en',
+  endonym: 'English (Ghana)',
+  dir: 'ltr',
+  script: 'Latn',
 };
 
 export default metadata;