tribunal-kit 1.0.0 → 2.4.0

package/.agent/skills/i18n-localization/SKILL.md

@@ -1,154 +1,216 @@
 ---
 name: i18n-localization
 description: Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.
-allowed-tools: Read, Glob, Grep
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# i18n & Localization
+# Internationalization & Localization
 
-> Internationalization (i18n) and Localization (L10n) best practices.
+> Internationalization (i18n) is preparing code to support multiple languages.
+> Localization (l10n) is the work of adapting to a specific locale.
+> Do i18n once, properly. Do l10n for each market.
 
 ---
 
-## 1. Core Concepts
+## The Core Rule: No Hardcoded Strings
 
-| Term | Meaning |
-|------|---------|
-| **i18n** | Internationalization - making app translatable |
-| **L10n** | Localization - actual translations |
-| **Locale** | Language + Region (en-US, tr-TR) |
-| **RTL** | Right-to-left languages (Arabic, Hebrew) |
+Every user-visible string in the source code is a localization problem waiting to happen.
+
+```ts
+// ❌ Hardcoded — untranslatable
+<button>Save Changes</button>
+<p>You have {count} messages</p>
+<p>Error: Invalid email address</p>
+
+// ✅ Key-referenced — translatable
+<button>{t('common.save')}</button>
+<p>{t('inbox.messageCount', { count })}</p>
+<p>{t('errors.invalidEmail')}</p>
+```
 
 ---
 
-## 2. When to Use i18n
+## Translation File Structure
+
+Organize translation keys hierarchically — flat files become unmaintainable past ~50 keys:
+
+```json
+// en.json
+{
+  "common": {
+    "save": "Save Changes",
+    "cancel": "Cancel",
+    "loading": "Loading…",
+    "error": "Something went wrong"
+  },
+  "auth": {
+    "login": "Sign In",
+    "logout": "Sign Out",
+    "register": "Create Account",
+    "errors": {
+      "invalidEmail": "Enter a valid email address",
+      "passwordTooShort": "Password must be at least {{min}} characters"
+    }
+  },
+  "inbox": {
+    "messageCount_one": "{{count}} message",
+    "messageCount_other": "{{count}} messages"
+  }
+}
+```
 
-| Project Type | i18n Needed? |
-|--------------|--------------|
-| Public web app | ✅ Yes |
-| SaaS product | ✅ Yes |
-| Internal tool | ⚠️ Maybe |
-| Single-region app | ⚠️ Consider future |
-| Personal project | ❌ Optional |
+**Key naming conventions:**
+- `feature.element` or `feature.element.state`
+- Error keys under `.errors`
+- Never use the English text as the key (`"Save Changes": "Save Changes"`)
 
 ---
 
-## 3. Implementation Patterns
+## Pluralization
 
-### React (react-i18next)
+Pluralization rules differ per language. Use your i18n library's plural system — never manual `if count > 1`:
 
-```tsx
-import { useTranslation } from 'react-i18next';
+```ts
+// ❌ Only works for English
+const label = count === 1 ? 'message' : 'messages';
 
-function Welcome() {
-  const { t } = useTranslation();
-  return <h1>{t('welcome.title')}</h1>;
-}
+// ✅ i18next handles per-language plural rules
+t('inbox.messageCount', { count })
+
+// Translation files handle the variants:
+// English: { "messageCount_one": "{{count}} message", "messageCount_other": "{{count}} messages" }
+// Arabic:  6 plural forms (zero, one, two, few, many, other)
+// Russian: 3 plural forms with complex rules
 ```
 
-### Next.js (next-intl)
+---
 
-```tsx
-import { useTranslations } from 'next-intl';
+## Date, Number & Currency Formatting
 
-export default function Page() {
-  const t = useTranslations('Home');
-  return <h1>{t('title')}</h1>;
-}
-```
+Never format these manually. Use the browser's `Intl` API:
 
-### Python (gettext)
+```ts
+// Date
+const date = new Date();
+new Intl.DateTimeFormat('en-US').format(date);  // "2/20/2026"
+new Intl.DateTimeFormat('de-DE').format(date);  // "20.2.2026"
 
-```python
-from gettext import gettext as _
+// Number
+new Intl.NumberFormat('en-US').format(1234567.89);  // "1,234,567.89"
+new Intl.NumberFormat('de-DE').format(1234567.89);  // "1.234.567,89"
 
-print(_("Welcome to our app"))
+// Currency
+new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(99.99);
+// "$99.99"
+new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(99.99);
+// "99,99 €"
 ```
 
 ---
 
-## 4. File Structure
+## RTL (Right-to-Left) Support
+
+Arabic, Hebrew, Persian, Urdu are RTL languages. Supporting them requires more than flipping direction.
+
+```html
+<!-- Set direction on html element based on locale -->
+<html lang="ar" dir="rtl">
 
+<!-- Or dynamically -->
+<html lang={locale} dir={isRTL(locale) ? 'rtl' : 'ltr'}>
 ```
-locales/
-├── en/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-├── tr/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-└── ar/          # RTL
-    └── ...
+
+```css
+/* Use logical properties — they flip automatically with direction */
+/* ❌ Physical: only works for LTR */
+padding-left: 1rem;
+margin-right: 2rem;
+border-left: 2px solid;
+
+/* ✅ Logical: works for both LTR and RTL */
+padding-inline-start: 1rem;
+margin-inline-end: 2rem;
+border-inline-start: 2px solid;
 ```
 
 ---
 
-## 5. Best Practices
+## Detecting Hardcoded Strings (Code Audit)
 
-### DO ✅
+Look for:
+- JSX text content directly in tags: `<p>some text</p>` (not `<p>{t(...)}</p>`)
+- Template literals with user-facing copy: `` `Welcome, ${name}!` ``
+- Alert/toast calls with string literals: `toast.success('Saved!')`
+- Error messages: `new Error('Invalid input')` shown to users
+- `placeholder`, `aria-label`, `title` attributes hardcoded
 
-- Use translation keys, not raw text
-- Namespace translations by feature
-- Support pluralization
-- Handle date/number formats per locale
-- Plan for RTL from the start
-- Use ICU message format for complex strings
+---
 
-### DON'T ❌
+## Scripts
 
-- Hardcode strings in components
-- Concatenate translated strings
-- Assume text length (German is 30% longer)
-- Forget about RTL layout
-- Mix languages in same file
+| Script | Purpose | Run With |
+|---|---|---|
+| `scripts/i18n_checker.py` | Scans codebase for hardcoded strings | `python scripts/i18n_checker.py <project_path>` |
 
 ---
 
-## 6. Common Issues
+## Output Format
+
+When this skill produces a recommendation or design decision, structure your output as:
+
+```
+━━━ I18N Localization Recommendation ━━━━━━━━━━━━━━━━
+Decision:    [what was chosen / proposed]
+Rationale:   [why — one concise line]
+Trade-offs:  [what is consciously accepted]
+Next action: [concrete next step for the user]
+─────────────────────────────────────────────────
+Pre-Flight:  ✅ All checks passed
+             or ❌ [blocking item that must be resolved first]
+```
+
 
-| Issue | Solution |
-|-------|----------|
-| Missing translation | Fallback to default language |
-| Hardcoded strings | Use linter/checker script |
-| Date format | Use Intl.DateTimeFormat |
-| Number format | Use Intl.NumberFormat |
-| Pluralization | Use ICU message format |
 
 ---
 
-## 7. RTL Support
+## 🤖 LLM-Specific Traps
 
-```css
-/* CSS Logical Properties */
-.container {
-  margin-inline-start: 1rem;  /* Not margin-left */
-  padding-inline-end: 1rem;   /* Not padding-right */
-}
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-[dir="rtl"] .icon {
-  transform: scaleX(-1);
-}
-```
+1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
+2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
+3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
+4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
 
 ---
 
-## 8. Checklist
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-Before shipping:
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
 
-- [ ] All user-facing strings use translation keys
-- [ ] Locale files exist for all supported languages
-- [ ] Date/number formatting uses Intl API
-- [ ] RTL layout tested (if applicable)
-- [ ] Fallback language configured
-- [ ] No hardcoded strings in components
+### ❌ Forbidden AI Tropes
 
----
+1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
+2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
+3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before confirming output:
+```
+✅ Did I rely ONLY on real, verified tools and methods?
+✅ Is this solution appropriately scoped to the user's constraints?
+✅ Did I handle potential failure modes and edge cases?
+✅ Have I avoided generic boilerplate that doesn't add value?
+```
 
-## Script
+### 🛑 Verification-Before-Completion (VBC) Protocol
 
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python scripts/i18n_checker.py <project_path>` |
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.