@wazir-dev/cli 1.0.0

package/expertise/i18n/foundations/locale-and-language-tags.md

@@ -0,0 +1,79 @@
+# Locale and Language Tags — i18n/RTL Expertise Module
+
+> BCP 47 (RFC 5646) defines language tags: `en-US`, `ar-SA`, `zh-Hans-CN`. Structure, lookup, fallback chain, and locale resolution for i18n.
+
+> **Category:** Foundation
+> **Applies to:** All
+> **Key standards:** BCP 47 (RFC 5646), RFC 4647 (matching)
+> **RTL impact:** Low — locale selects RTL; tags don't encode direction
+
+## 1. Core Concepts
+
+### BCP 47 Structure
+
+```
+language ["-" script] ["-" region] ["-" variant] ["-" extension]
+```
+
+| Subtag | Source | Example |
+|--------|--------|---------|
+| language | ISO 639 | en, ar, zh |
+| script | ISO 15924 | Hans, Hant, Latn |
+| region | ISO 3166-1 / UN M.49 | US, SA, 419 |
+| variant | Registered | |
+| extension | u-, t- | u-ca-hebrew |
+
+### Examples
+
+- `en` — English
+- `en-US` — American English
+- `ar-SA` — Arabic (Saudi Arabia)
+- `zh-Hans-CN` — Chinese Simplified (China)
+- `sr-Cyrl` — Serbian (Cyrillic script)
+- `en-u-ca-hebrew` — English with Hebrew calendar extension
+
+### Legacy: `iw` = `he`
+
+- `iw` was deprecated for Hebrew; use `he`
+
+---
+
+## 2. Fallback Chain
+
+When `ar-SA` is requested but a translation is missing:
+
+1. `ar-SA`
+2. `ar`
+3. Default (e.g., `en`)
+
+Implement via RFC 4647 lookup or framework fallback.
+
+---
+
+## 3. Locale Resolution
+
+- **User preference:** `Accept-Language` header, OS locale, app setting
+- **Explicit:** Pass locale to API/component
+- **Default:** Project default when no match
+
+---
+
+## 4. Anti-Patterns
+
+1. **Hardcoding locale** — Use user preference or explicit param
+2. **No fallback** — Always have a default
+3. **Using `iw`** — Use `he` for Hebrew
+4. **Ignoring script** — `zh-Hans` vs `zh-Hant` matter
+5. **Wrong region** — `es-ES` vs `es-419` (Latin America)
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Use BCP 47 tags
+- [ ] Implement fallback chain
+- [ ] Resolve from user preference
+- [ ] Use `he` not `iw`
+
+---
+*Researched: 2026-03-08 | Sources: RFC 5646, W3C BCP 47, IANA registry*

package/expertise/i18n/foundations/numbers-currency-units.md

@@ -0,0 +1,61 @@
+# Numbers, Currency, and Units — i18n/RTL Expertise Module
+
+> Number formatting varies: decimal separator (`.` vs `,`), grouping, currency symbol position, and numeral system (Western vs Eastern Arabic). Use `Intl.NumberFormat`; never hardcode.
+
+> **Category:** Foundation
+> **Applies to:** All
+> **Key standards:** CLDR, Intl API
+> **RTL impact:** Medium — Eastern Arabic numerals (٠١٢٣) in some locales
+
+## 1. Core Concepts
+
+### Decimal and Grouping
+
+| Locale | Decimal | Thousands |
+|--------|---------|-----------|
+| en-US | . | , |
+| de-DE | , | . |
+| ar-SA | ٫ (Arabic decimal) | ٬ (Arabic thousands) |
+| fr-FR | , | space |
+
+### Numeral Systems
+
+- **Western (0123):** en, de, fr, he-IL
+- **Eastern Arabic (٠١٢٣):** ar-SA, ar-EG, fa-IR
+- **Locale-dependent:** Use `Intl.NumberFormat(locale)` — it picks the right one
+
+### Currency
+
+```javascript
+new Intl.NumberFormat('ar-SA', {
+  style: 'currency',
+  currency: 'SAR'
+}).format(1234.56);
+// "١٬٢٣٤٫٥٦ ر.س"
+```
+
+### Units
+
+- **Intl.NumberFormat** with `style: 'unit'` for lengths, etc.
+- Or use `Intl` + custom unit strings
+
+---
+
+## 2. Anti-Patterns
+
+1. **Hardcoded decimal separator** — Use Intl
+2. **Assuming Western numerals** — ar-SA uses Eastern
+3. **Currency symbol position** — Locale-dependent (before/after, spacing)
+4. **No currency code** — Use ISO 4217 (USD, EUR, SAR)
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Use Intl.NumberFormat
+- [ ] Pass locale and currency
+- [ ] No hardcoded separators
+- [ ] Test with ar-SA (Eastern numerals)
+
+---
+*Researched: 2026-03-08 | Sources: MDN Intl.NumberFormat, CLDR*

package/expertise/i18n/foundations/pluralization-and-gender.md

@@ -0,0 +1,109 @@
+# Pluralization and Gender — i18n/RTL Expertise Module
+
+> Languages have different plural rules (English: 2 forms; Arabic: 6; Japanese: 1) and gender agreement. ICU MessageFormat handles both via `plural` and `select`. Never use `count === 1 ? 'item' : 'items'`.
+
+> **Category:** Foundation
+> **Applies to:** All
+> **Key standards:** CLDR plural rules, ICU MessageFormat
+> **RTL impact:** Low — plural/gender are language rules
+
+## 1. Core Concepts
+
+### CLDR Plural Categories
+
+- **zero** — Some languages (e.g., Arabic) have explicit zero form
+- **one** — Singular (n=1 in English; varies by language)
+- **two** — Dual (Arabic, Welsh, etc.)
+- **few** — Small quantity (e.g., 2–4 in Russian)
+- **many** — Large quantity (e.g., Polish)
+- **other** — Default; required in every plural rule
+
+No language uses all six. English uses one + other. Arabic uses all six.
+
+### ICU MessageFormat: plural
+
+```
+{count, plural,
+  zero {لا رسائل}
+  one {رسالة واحدة}
+  two {رسالتان}
+  few {# رسائل}
+  many {# رسالة}
+  other {# رسالة}
+}
+```
+
+`#` = formatted number.
+
+### ICU MessageFormat: select (gender)
+
+```
+{gender, select,
+  male {He}
+  female {She}
+  other {They}
+} liked this.
+```
+
+### Locale Examples
+
+| Language | Forms | Example |
+|----------|-------|---------|
+| English | one, other | 1 item / 2 items |
+| Arabic | zero, one, two, few, many, other | 6 forms |
+| Hebrew | one, two, other | 3 forms |
+| Russian | one, few, many, other | 4 forms |
+| Japanese | other | 1 form |
+| Polish | one, few, many, other | 4 forms |
+
+---
+
+## 2. Implementation
+
+### JavaScript (formatjs/react-intl)
+
+```tsx
+<FormattedMessage
+  id="itemCount"
+  defaultMessage="{count, plural, one {# item} other {# items}}"
+  values={{ count: 5 }}
+/>
+```
+
+### Dart (Flutter)
+
+```dart
+AppLocalizations.of(context)!.itemCount(5)
+// From ARB: "{count, plural, one {# item} other {# items}}"
+```
+
+### Nested: plural + select
+
+```
+{count, plural,
+  one {{gender, select, male {He has} female {She has} other {They have}} one.}
+  other {{gender, select, male {He has} female {She has} other {They have}} #.}
+}
+```
+
+---
+
+## 3. Anti-Patterns
+
+1. **`count === 1 ? 'item' : 'items'`** — Fails for Arabic, Russian, etc.
+2. **Missing `other`** — Required in ICU
+3. **Concatenating** — "You have " + count + " items"; use full message
+4. **No gender** — French, German, etc. need gender agreement
+5. **Ordinal as cardinal** — Use `selectordinal` for "1st", "2nd"
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Use ICU MessageFormat for plurals
+- [ ] Include `other` in every plural
+- [ ] Use `select` for gender when needed
+- [ ] Never concatenate for plurals
+
+---
+*Researched: 2026-03-08 | Sources: CLDR plurals, ICU MessageFormat, IntlPull guide*

package/expertise/i18n/foundations/string-externalization.md

@@ -0,0 +1,236 @@
+# String Externalization — i18n/RTL Expertise Module
+
+> Extracting all user-facing strings from code into external resource files so they can be translated without touching source. The foundation of every localization workflow—get this wrong and translators work against the codebase.
+
+> **Category:** Foundation
+> **Applies to:** All (Mobile, Web, Backend)
+> **Key standards:** ICU MessageFormat, XLIFF (ISO 21720), gettext PO, ARB
+> **RTL impact:** Medium — externalized strings enable RTL; keys and placeholders must not assume LTR
+
+## 1. Core Concepts
+
+### What This Area Covers
+
+String externalization is the practice of moving every user-facing string out of source code into separate resource files. This enables:
+- Translation without code changes
+- Consistent key management across languages
+- Context for translators (descriptions, placeholders, screenshots)
+- Automated extraction and validation
+
+### Why It Matters
+
+- **Retrofitting costs 3–5×** — Hunting for hardcoded strings across components, templates, and API responses is expensive
+- **Keys are a contract** — Between developers, translators, and translation management systems
+- **Poor key naming** — Causes 2–3× more time on translation management, reuse errors, and maintenance brittleness
+
+### Common Misconceptions
+
+1. **"We can grep for strings later"** — Strings appear in JSX, templates, error constructors, validation messages, logs. Grep misses many.
+2. **"Keys can be the English text"** — Ties you to English; renames break translation history.
+3. **"One big file per language"** — Doesn't scale; no code-splitting, merge conflicts, slow loads.
+4. **"Translators don't need context"** — "Save" can mean "persist" or "rescue"; "Close" can mean "shut" or "near."
+
+---
+
+## 2. Implementation Patterns
+
+### Key Naming Convention
+
+**Hierarchical, feature-based, semantic:**
+
+```
+{namespace}.{component}.{element}.{modifier}
+```
+
+**Examples:**
+- `auth.login.submitButton` — not `loginSubmitButton`
+- `checkout.cart.emptyState.title` — not `emptyCart`
+- `common.errors.networkError` — not `error1`
+
+**Rules:**
+- Use consistent casing (camelCase or snake_case project-wide)
+- Keep keys under ~50 characters
+- Avoid positional names (`sidebar.firstItem`, `modal.button1`)
+- No special characters or spaces; alphanumeric + dots/underscores only
+
+### File Formats
+
+| Format | Used By | Structure | Plurals |
+|--------|---------|-----------|---------|
+| **ARB** | Flutter/Dart | JSON, `@` metadata | ICU MessageFormat |
+| **JSON** | React, Vue, Node | Key-value, nested or flat | ICU or `_one`/`_other` suffix |
+| **XLIFF** | Enterprise, CAT tools | XML, source+target pairs | Embedded in `<trans-unit>` |
+| **PO** | gettext, Linux, PHP | `msgid`/`msgstr`, `msgid_plural` | `Plural-Forms` header |
+| **strings.xml** | Android | XML, `string`/`plurals` | `quantity` attributes |
+| **Localizable.strings** | iOS | `"key" = "value";` | `.stringsdict` |
+
+### ARB (Flutter) Example
+
+```json
+{
+  "@@locale": "en",
+  "welcomeMessage": "Hello, {name}!",
+  "@welcomeMessage": {
+    "description": "Greeting on dashboard",
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "itemCount": "{count, plural, =0{No items} one{1 item} other{# items}}",
+  "@itemCount": {
+    "description": "Cart item count",
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  }
+}
+```
+
+### JSON (React/i18next) Example
+
+```json
+{
+  "auth": {
+    "login": {
+      "title": "Sign in",
+      "submit": "Log in",
+      "forgotPassword": "Forgot password?"
+    }
+  },
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel"
+  }
+}
+```
+
+### PO (gettext) Example
+
+```
+#: src/components/Login.tsx:42
+msgid "Sign in"
+msgstr ""
+
+#: src/components/Cart.tsx:15
+msgid "One item in cart"
+msgid_plural "%d items in cart"
+msgstr[0] ""
+msgstr[1] ""
+```
+
+### XLIFF 2.0 Snippet
+
+```xml
+<trans-unit id="auth.login.title">
+  <source>Sign in</source>
+  <target>تسجيل الدخول</target>
+  <note>Login screen heading</note>
+</trans-unit>
+```
+
+### Folder Structure
+
+Organize by feature/namespace, not by page or file location:
+
+```
+locales/
+  en/
+    auth.json
+    dashboard.json
+    checkout.json
+    common.json
+  ar/
+    auth.json
+    dashboard.json
+    ...
+```
+
+Enables code-splitting, clear ownership, and lazy loading per namespace.
+
+### Placeholder and Interpolation Rules
+
+1. **Never concatenate** — Use `{name}` or `{{name}}`; let translators control word order.
+2. **Document placeholders** — Type, purpose, example in metadata.
+3. **Escape carefully** — Some formats use `{count}` (ICU) vs `{{count}}` (i18next); know your framework.
+
+---
+
+## 3. Locale Variations
+
+### Arabic
+- Long strings for formal register; short for informal. Provide both if needed.
+- Placeholders may need to appear in different positions: "مرحباً {{name}}" vs "Welcome, {{name}}"
+- RTL affects placeholder placement in mixed content.
+
+### German
+- ~30% longer; design for expansion. Keys should not imply length.
+- Compound words: "E-Mail-Adresse" — ensure UI doesn't truncate.
+
+### Japanese / Chinese
+- Often shorter; avoid fixed-width layouts that assume long text.
+- No spaces; line breaks differ. Provide max length hints for translators.
+
+### Hebrew
+- Similar to Arabic for RTL; different typography. Keys and structure are shared; values differ.
+
+---
+
+## 4. Anti-Patterns
+
+1. **Hardcoded strings in components** — Every visible string must be externalized.
+2. **Keys as English text** — `"Welcome back"` as key; use `auth.welcomeBack`.
+3. **String concatenation** — `"Hello, " + name`; use `t('greeting', { name })`.
+4. **No context for translators** — Add descriptions, screenshots, max length.
+5. **Flat key namespace** — `button1`, `title2`; use hierarchical semantic keys.
+6. **Inconsistent casing** — Mix of camelCase and snake_case; pick one.
+7. **Positional keys** — `sidebar.firstItem`; use `navigation.sidebar.dashboard`.
+8. **Translating in UI only** — API errors, validation, logs shown to users must be externalized.
+9. **Missing placeholder metadata** — Translators need type and purpose.
+10. **One giant file** — Split by feature for maintainability and lazy loading.
+11. **No fallback for missing keys** — Define policy: show key, default locale, or throw.
+12. **Keys that change** — Renaming breaks translation memory; use stable semantic keys.
+13. **Embedding HTML in strings** — Prefer structured messages (e.g., rich text components).
+14. **Translating developer-only strings** — Log messages, debug text—exclude from extraction.
+15. **No extraction automation** — Manual copy-paste leads to drift; use extraction tools.
+
+---
+
+## 5. Testing Approach
+
+### Extraction Validation
+- Run extraction; ensure no new hardcoded strings
+- CI check: fail if strings appear in code without extraction
+
+### Missing Key Detection
+- Test with a locale that has incomplete translations
+- Verify fallback behavior (key vs default locale)
+
+### Placeholder Coverage
+- Ensure all placeholders documented
+- Test with long/short/empty values, RTL text (e.g., العربية)
+
+### Pseudo-Localization
+- Replace values with expanded/accented text to find truncation
+- Use bracketed placeholders `[KeyName]` to find untranslated keys
+
+---
+
+## Quick Reference Checklist
+
+- [ ] All user-facing strings in resource files
+- [ ] Keys are semantic, hierarchical, consistent casing
+- [ ] Placeholders documented (type, purpose)
+- [ ] No string concatenation for sentences
+- [ ] Files organized by feature/namespace
+- [ ] Extraction automated in CI
+- [ ] Missing key policy defined and enforced
+- [ ] Context (descriptions, screenshots) for translators
+- [ ] API/validation/error messages externalized
+- [ ] Test with pseudo-localization and incomplete locales
+
+---
+*Researched: 2026-03-08 | Sources: Locize key naming guide, IntlPull translation keys, Flutter ARB docs, XLIFF spec, gettext PO manual*