chore: improve docs

Author: chrisbbreuer

README.md

@@ -13,33 +13,9 @@ A performance-focused and lightweight faker library for TypeScript with comprehe
 ## Features
 
 - ⚡️ **Performance-focused** - Built with speed and efficiency in mind
-- 🌍 **Multi-locale Support** - Complete translations for 26 languages:
-  - Afrikaans _(af)_
-  - Arabic _(ar)_
-  - Azerbaijani _(az)_
-  - Czech _(cs)_
-  - Danish _(da)_
-  - German _(de)_
-  - English _(en)_
-  - Esperanto _(eo)_
-  - Spanish _(es)_
-  - Persian/Farsi _(fa)_
-  - Finnish _(fi)_
-  - French _(fr)_
-  - Hebrew _(he)_
-  - Hindi _(hi)_
-  - Italian _(it)_
-  - Japanese _(ja)_
-  - Korean _(ko)_
-  - Dutch _(nl)_
-  - Norwegian _(no)_
-  - Polish _(pl)_
-  - Portuguese _(pt)_
-  - Swedish _(sv)_
-  - Filipino _(tl)_
-  - Turkish _(tr)_
-  - Ukrainian _(uk)_
-  - Chinese _(zh)_
+- 🌍 **Multi-locale Support** - Complete translations for 28 languages with 22+ regional variants:
+  - Afrikaans _(af)_, Arabic _(ar)_, Azerbaijani _(az)_, Czech _(cs)_, Danish _(da)_, German _(de)_, English _(en)_, Esperanto _(eo)_, Spanish _(es)_, Persian/Farsi _(fa)_, Finnish _(fi)_, French _(fr)_, Hebrew _(he)_, Hindi _(hi)_, Italian _(it)_, Japanese _(ja)_, Korean _(ko)_, Dutch _(nl)_, Norwegian _(no)_, Polish _(pl)_, Portuguese _(pt)_, Swedish _(sv)_, Filipino _(tl)_, Turkish _(tr)_, Ukrainian _(uk)_, Chinese Simplified _(zh-cn)_, Chinese Traditional _(zh-tw)_, Zulu _(zu)_
+  - Plus regional variants: `en-us`, `en-gb`, `en-ca`, `en-ie`, `en-in`, `en-za`, `en-gh`, `en-ng`, `en-hk`, `fr-ca`, `fr-ch`, `fr-be`, `fr-lu`, `fr-sn`, `de-at`, `de-ch`, `es-mx`, `pt-mz`, `af-za`, `zu-za`, and more!
 - 📦 **Lightweight** - Minimal dependencies and small bundle size
 - 💪 **Fully Typed** - Written in TypeScript with comprehensive type definitions
 - 🎯 **Comprehensive Data** - 16+ data categories including:
@@ -103,11 +79,22 @@ console.log(faker.person.fullName()) // "María García"
 // Or create a new instance with a specific locale
 const spanishFaker = new Faker({ locale: 'es' })
 const japaneseFaker = new Faker({ locale: 'ja' })
-const chineseFaker = new Faker({ locale: 'zh' })
+const chineseSimplifiedFaker = new Faker({ locale: 'zh-cn' })
+const chineseTraditionalFaker = new Faker({ locale: 'zh-tw' })
 
 console.log(spanishFaker.person.fullName()) // "Carlos López"
 console.log(japaneseFaker.person.fullName()) // "田中太郎"
-console.log(chineseFaker.person.fullName()) // "王伟"
+console.log(chineseSimplifiedFaker.person.fullName()) // "王伟"
+console.log(chineseTraditionalFaker.person.fullName()) // "陳小明"
+
+// Regional variants provide localized data
+const usFaker = new Faker({ locale: 'en-us' })
+const ukFaker = new Faker({ locale: 'en-gb' })
+const canadianFrenchFaker = new Faker({ locale: 'fr-ca' })
+
+console.log(usFaker.address.city()) // "New York"
+console.log(ukFaker.address.city()) // "London"
+console.log(canadianFrenchFaker.address.city()) // "Montréal"
 ```
 
 ### Available Locales
@@ -137,7 +124,56 @@ console.log(chineseFaker.person.fullName()) // "王伟"
 - `tl` - Filipino
 - `tr` - Turkish
 - `uk` - Ukrainian
-- `zh` - Chinese
+- `zh-cn` - Chinese (Simplified)
+- `zh-tw` - Chinese (Traditional)
+- `zu` - Zulu
+
+#### Regional Variants
+
+Many languages also have regional variants with localized data for specific countries:
+
+**English Variants:**
+
+- `en-us` - English (United States)
+- `en-gb` - English (United Kingdom)
+- `en-ca` - English (Canada)
+- `en-ie` - English (Ireland)
+- `en-in` - English (India)
+- `en-za` - English (South Africa)
+- `en-gh` - English (Ghana)
+- `en-ng` - English (Nigeria)
+- `en-hk` - English (Hong Kong)
+
+**French Variants:**
+
+- `fr-ca` - French (Canada)
+- `fr-ch` - French (Switzerland)
+- `fr-be` - French (Belgium)
+- `fr-lu` - French (Luxembourg)
+- `fr-sn` - French (Senegal)
+
+**German Variants:**
+
+- `de-at` - German (Austria)
+- `de-ch` - German (Switzerland)
+
+**Spanish Variants:**
+
+- `es-mx` - Spanish (Mexico)
+
+**Portuguese Variants:**
+
+- `pt-mz` - Portuguese (Mozambique)
+
+**Afrikaans Variants:**
+
+- `af-za` - Afrikaans (South Africa)
+
+**Zulu Variants:**
+
+- `zu-za` - Zulu (South Africa)
+
+These regional variants include country-specific data such as local cities, addresses, phone formats, and cultural references.
 
 ### API Examples
 
@@ -309,7 +345,7 @@ ts-mocker methods food
 
 ### Options
 
-- `--locale <locale>` - Use a specific locale (af, ar, az, cs, da, de, en, eo, es, fa, fi, fr, he, hi, it, ja, ko, nl, no, pl, pt, sv, tl, tr, uk, zh)
+- `--locale <locale>` - Use a specific locale (af, ar, az, cs, da, de, en, eo, es, fa, fi, fr, he, hi, it, ja, ko, nl, no, pl, pt, sv, tl, tr, uk, zh-cn, zh-tw, zu)
 - `--count <count>` - Number of items to generate
 - `--seed <seed>` - Seed for reproducible results
 - `--json` - Output as JSON

docs/cli.md

@@ -28,7 +28,7 @@ ts-mocker generate <category> <method> [options]
 
 **Options:**
 
-- `--locale <locale>` - Locale to use (af, ar, az, cs, da, de, en, eo, es, fa, fi, fr, he, hi, it, ja, ko, nl, no, pl, pt, sv, tl, tr, uk, zh)
+- `--locale <locale>` - Locale to use (af, ar, az, cs, da, de, en, eo, es, fa, fi, fr, he, hi, it, ja, ko, nl, no, pl, pt, sv, tl, tr, uk, zh-cn, zh-tw, zu)
 - `--count <count>` - Number of items to generate (default: 1)
 - `--seed <seed>` - Seed for reproducible results
 - `--json` - Output as JSON
@@ -116,7 +116,7 @@ List all available locales.
 ts-mocker locales
 ```
 
-Shows all 26 supported locales:
+Shows all 28 supported locales:
 
 - af - Afrikaans
 - ar - Arabic
@@ -143,7 +143,9 @@ Shows all 26 supported locales:
 - tl - Filipino
 - tr - Turkish
 - uk - Ukrainian
-- zh - Chinese
+- zh-cn - Chinese (Simplified)
+- zh-tw - Chinese (Traditional)
+- zu - Zulu
 
 ### batch
 

docs/config.md

@@ -47,24 +47,36 @@ const customFaker: Faker = faker.locale('en')
 
 ## Available Locales
 
-ts-mocker supports the following locales with complete translations across all categories:
+ts-mocker supports 28 locales with complete translations across all categories:
 
+- `af` - Afrikaans
+- `ar` - Arabic
+- `az` - Azerbaijani
+- `cs` - Czech
+- `da` - Danish
+- `de` - German
 - `en` - English
+- `eo` - Esperanto
 - `es` - Spanish
+- `fa` - Persian/Farsi
+- `fi` - Finnish
 - `fr` - French
-- `de` - German
+- `he` - Hebrew
+- `hi` - Hindi
 - `it` - Italian
-- `pt` - Portuguese
 - `ja` - Japanese
-- `tl` - Filipino
-- `zh` - Chinese
-- `nl` - Dutch
 - `ko` - Korean
+- `nl` - Dutch
 - `no` - Norwegian
+- `pl` - Polish
+- `pt` - Portuguese
 - `sv` - Swedish
-- `da` - Danish
+- `tl` - Filipino
+- `tr` - Turkish
 - `uk` - Ukrainian
-- `hi` - Hindi
+- `zh-cn` - Chinese (Simplified)
+- `zh-tw` - Chinese (Traditional)
+- `zu` - Zulu
 
 All locales have full coverage across all 16 data categories.
 

docs/features/locales.md

@@ -4,7 +4,7 @@ ts-mocker provides comprehensive locale support with **complete translations** a
 
 ## Supported Locales
 
-All 26 locales have full coverage across all 16 data categories:
+All 28 locales have full coverage across all 16 data categories:
 
 ### Afrikaans (af)
 
@@ -332,19 +332,48 @@ console.log(faker.person.fullName()) // "Олександр Шевченко"
 console.log(faker.address.city()) // "Київ"
 ```
 
-### Chinese (zh)
+### Chinese Simplified (zh-cn)
 
 - **Status**: Full coverage ✓
 - **Categories**: All 16 categories fully translated
+- **Region**: Mainland China
 
 ```ts
 import { faker } from 'ts-mocker'
 
-faker.locale = 'zh'
+faker.locale = 'zh-cn'
 console.log(faker.person.fullName()) // "王伟"
 console.log(faker.address.city()) // "北京"
 ```
 
+### Chinese Traditional (zh-tw)
+
+- **Status**: Full coverage ✓
+- **Categories**: All 16 categories fully translated
+- **Region**: Taiwan
+
+```ts
+import { faker } from 'ts-mocker'
+
+faker.locale = 'zh-tw'
+console.log(faker.person.fullName()) // "陳小明"
+console.log(faker.address.city()) // "台北"
+```
+
+### Zulu (zu)
+
+- **Status**: Full coverage ✓
+- **Categories**: All 16 categories fully translated
+- **Region**: South Africa
+
+```ts
+import { faker } from 'ts-mocker'
+
+faker.locale = 'zu'
+console.log(faker.person.fullName()) // "Sipho Dlamini"
+console.log(faker.address.city()) // "Durban"
+```
+
 ## Multi-Locale Applications
 
 For applications that need to support multiple locales simultaneously, create separate instances:

docs/intro.md

@@ -6,7 +6,7 @@
 
 # ts-mocker
 
-ts-mocker is a modern, lightweight TypeScript library for generating fake data. Built with performance and developer experience in mind, it provides comprehensive locale support across 16 languages with complete translations for all data categories.
+ts-mocker is a modern, lightweight TypeScript library for generating fake data. Built with performance and developer experience in mind, it provides comprehensive locale support across 28 languages with complete translations for all data categories.
 
 ## Why ts-mocker?
 
@@ -16,24 +16,36 @@ Built with performance as a top priority, ts-mocker is optimized for speed and e
 
 ### Comprehensive Locale Support
 
-Unlike other faker libraries with limited or incomplete translations, ts-mocker provides **complete** translations across all 16 data categories for 16 different languages:
+Unlike other faker libraries with limited or incomplete translations, ts-mocker provides **complete** translations across all 16 data categories for 28 different languages:
 
+- **Afrikaans (af)** - Full coverage
+- **Arabic (ar)** - Full coverage
+- **Azerbaijani (az)** - Full coverage
+- **Czech (cs)** - Full coverage
+- **Danish (da)** - Full coverage
+- **German (de)** - Full coverage
 - **English (en)** - Full coverage
+- **Esperanto (eo)** - Full coverage
 - **Spanish (es)** - Full coverage
+- **Persian/Farsi (fa)** - Full coverage
+- **Finnish (fi)** - Full coverage
 - **French (fr)** - Full coverage
-- **German (de)** - Full coverage
+- **Hebrew (he)** - Full coverage
+- **Hindi (hi)** - Full coverage
 - **Italian (it)** - Full coverage
-- **Portuguese (pt)** - Full coverage
 - **Japanese (ja)** - Full coverage
-- **Filipino (tl)** - Full coverage
-- **Chinese (zh)** - Full coverage
-- **Dutch (nl)** - Full coverage
 - **Korean (ko)** - Full coverage
+- **Dutch (nl)** - Full coverage
 - **Norwegian (no)** - Full coverage
+- **Polish (pl)** - Full coverage
+- **Portuguese (pt)** - Full coverage
 - **Swedish (sv)** - Full coverage
-- **Danish (da)** - Full coverage
+- **Filipino (tl)** - Full coverage
+- **Turkish (tr)** - Full coverage
 - **Ukrainian (uk)** - Full coverage
-- **Hindi (hi)** - Full coverage
+- **Chinese Simplified (zh-cn)** - Full coverage
+- **Chinese Traditional (zh-tw)** - Full coverage
+- **Zulu (zu)** - Full coverage
 
 ### Rich Data Categories
 

docs/usage.md

@@ -33,35 +33,45 @@ console.log(faker.person.fullName()) // "María García"
 // Or create a locale-specific instance
 const spanishFaker = faker.locale('es')
 const japaneseFaker = faker.locale('ja')
-const chineseFaker = faker.locale('zh')
+const chineseSimplifiedFaker = faker.locale('zh-cn')
+const chineseTraditionalFaker = faker.locale('zh-tw')
 
 console.log(spanishFaker.person.fullName()) // "Carlos López"
 console.log(japaneseFaker.person.fullName()) // "田中太郎"
-console.log(chineseFaker.person.fullName()) // "王伟"
+console.log(chineseSimplifiedFaker.person.fullName()) // "王伟"
+console.log(chineseTraditionalFaker.person.fullName()) // "陳小明"
 ```
 
 ## Available Locales
 
+- `af` - Afrikaans
+- `ar` - Arabic
+- `az` - Azerbaijani
+- `cs` - Czech
+- `da` - Danish
+- `de` - German
 - `en` - English
+- `eo` - Esperanto
 - `es` - Spanish
+- `fa` - Persian/Farsi
+- `fi` - Finnish
 - `fr` - French
-- `de` - German
+- `he` - Hebrew
+- `hi` - Hindi
 - `it` - Italian
-- `pt` - Portuguese
 - `ja` - Japanese
-- `tl` - Filipino
-- `zh` - Chinese
-- `nl` - Dutch
 - `ko` - Korean
+- `nl` - Dutch
 - `no` - Norwegian
+- `pl` - Polish
+- `pt` - Portuguese
 - `sv` - Swedish
-- `da` - Danish
-- `uk` - Ukrainian
-- `hi` - Hindi
-- `fi` - Finnish
+- `tl` - Filipino
 - `tr` - Turkish
-- `pl` - Polish
-- `cs` - Czech
+- `uk` - Ukrainian
+- `zh-cn` - Chinese (Simplified)
+- `zh-tw` - Chinese (Traditional)
+- `zu` - Zulu
 
 ## API Examples
 

packages/zh/package.json

@@ -2,7 +2,7 @@
   "name": "@mock-locale/zh",
   "type": "module",
   "version": "0.1.3",
-  "description": "ZH locale data for ts-mocker",
+  "description": "Chinese locale data for ts-mocker (base locale for zh-cn and zh-tw)",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
   "homepage": "https://github.com/stacksjs/ts-mocker#readme",