| type | skill |
| id | i18n-validate |
| name | i18n-validate |
| description | Validate translation completeness and consistency across all locale files — detect missing keys, untranslated strings, format mismatches, and glossary violations. |
| layer | cross |
| category | analysis |
| created_at | "2026-03-02T00:00:00.000Z" |
| updated_at | "2026-03-02T00:00:00.000Z" |
Skill: i18n Validate (Translation Completeness & Consistency)
Purpose
Validate i18n JSON files for completeness, consistency, and quality across multiple languages. Catch missing translations, orphaned keys, placeholder mismatches, and length violations before deployment.
Usage context: Post-translation (after idiomatique-translate), before committing to codebase. Also useful as CI/CD validation on every PR.
Input
{
"locales_path": "locales/",
"languages": ["en", "fr", "de", "es"],
"reference_language": "en",
"validation_rules": {
"check_missing_translations": true,
"check_orphaned_keys": true,
"check_placeholder_consistency": true,
"check_length_budget": true,
"check_json_syntax": true,
"check_glossary_alignment": true
},
"length_budget": {
"en": "baseline",
"fr": 1.2,
"de": 1.3,
"es": 1.15
},
"glossary_path": "domains/i18n/glossary.md",
"ignore_keys": ["copyright", "version"],
"output_format": "json"
}
Output
{
"validation_summary": {
"status": "FAIL",
"total_keys": 342,
"languages_checked": 4,
"errors": 8,
"warnings": 12,
"timestamp": "2026-03-02T03:15:00Z"
},
"errors": [
{
"type": "missing_translation",
"severity": "critical",
"language": "fr",
"key": "billing.directLink.perRequest",
"message": "Translation missing in locales/fr/billing.json"
},
{
"type": "orphaned_key",
"severity": "high",
"language": "en",
"key": "onboarding.legacyField",
"message": "Key exists in locales/en/onboarding.json but is not referenced in codebase (no t('onboarding.legacyField') found)"
},
{
"type": "placeholder_mismatch",
"severity": "high",
"key": "errors.welcomeMessage",
"en_placeholders": ["{userName}", "{date}"],
"fr_placeholders": ["{userName}"],
"message": "French translation missing {date} placeholder"
},
{
"type": "length_violation",
"severity": "medium",
"key": "buttons.submitForm",
"en_length": 10,
"fr_length": 16,
"budget": 12,
"en_text": "Submit",
"fr_text": "Soumettre le formulaire",
"message": "French translation exceeds 120% length budget (16 > 12 chars)"
},
{
"type": "glossary_mismatch",
"severity": "warning",
"key": "dashboard.leads.title",
"en_text": "Leads",
"glossary_term": "lead",
"glossary_fr": "prospect",
"found_fr": "Leads",
"message": "Key contains term 'lead' but French translation uses 'Leads' instead of glossary term 'prospect'"
},
{
"type": "json_syntax_error",
"severity": "critical",
"language": "de",
"file": "locales/de/common.json",
"line": 42,
"message": "Invalid JSON: unexpected token at line 42 (missing comma)"
}
],
"warnings": [
{
"type": "empty_translation",
"severity": "warning",
"language": "es",
"key": "analytics.description",
"message": "Spanish translation is empty string (placeholder)"
},
{
"type": "potential_untranslated",
"severity": "info",
"key": "footer.copyright",
"en_text": "© 2026 YourProject",
"fr_text": "© 2026 YourProject",
"message": "Text identical to EN — may be intentional (proper noun) or missed translation"
}
],
"statistics": {
"by_language": {
"en": { "total_keys": 342, "complete": true },
"fr": { "total_keys": 342, "translated": 334, "missing": 8, "completion": "97.7%" },
"de": { "total_keys": 342, "translated": 340, "missing": 2, "completion": "99.4%" },
"es": { "total_keys": 342, "translated": 336, "missing": 6, "completion": "98.2%" }
},
"by_severity": {
"critical": 2,
"high": 4,
"medium": 3,
"warning": 3,
"info": 0
},
"completion_percentage": {
"en": "100%",
"fr": "97.7%",
"de": "99.4%",
"es": "98.2%"
}
},
"recommendations": ["Complete 8 missing French translations (billing.directLink.perRequest, etc.)", "Remove orphaned key: onboarding.legacyField (not used in codebase)", "Fix placeholder mismatch in errors.welcomeMessage (FR missing {date})", "Shorten French translation of buttons.submitForm (16 > 12 chars budget)", "Verify glossary usage: dashboard.leads.title should use 'prospect' instead of 'Leads'", "Fix JSON syntax error in locales/de/common.json line 42"],
"next_steps": ["Address all CRITICAL errors before merging", "HIGH errors should be fixed before release", "MEDIUM warnings are UX issues (button text overflows on tight layouts)", "INFO messages are FYI (proper nouns, intentional repetition)"]
}
Validation Rules (Industry Standard)
1. Missing Translations
Every key in reference language (EN) must have a translation in all target languages.
en/common.json has "buttons.save"
├─ fr/common.json has "buttons.save" ✅
├─ de/common.json is MISSING "buttons.save" ❌
└─ es/common.json has "buttons.save" ✅
Result: ERROR (missing in de)
2. Orphaned Keys
Keys in i18n files but not referenced in codebase (no t('key') call).
locales/en/onboarding.json has "onboarding.legacyField"
Search codebase for t('onboarding.legacyField')
Result: NOT FOUND ❌
Result: ERROR (orphaned key, should be removed)
3. Placeholder Consistency
Template variables (e.g., {userName}, {date}) must appear in all translations.
en: "Welcome, {userName}! Your next call is {date}."
fr: "Bienvenue, {userName}! Votre prochain appel est {date}." ✅
en: "Welcome, {userName}! Your next call is {date}."
fr: "Bienvenue, {userName}!" ❌ (missing {date})
Result: ERROR (placeholder mismatch)
4. Length Budget
Translated text should not exceed language-specific length budgets (account for verbose languages).
en: "Submit" (6 chars)
Budget for FR: 6 × 1.2 = 7.2 chars
fr: "Soumettre" (9 chars) ❌ exceeds budget
Result: WARNING (UI may break on narrow screens)
5. JSON Syntax
All JSON files must be valid.
❌ Missing comma:
{ "key": "value" "another": "value" }
✅ Valid:
{ "key": "value", "another": "value" }
6. Glossary Alignment
Translations should use terms defined in domains/i18n/glossary.md.
Glossary: "lead" → { "en": "lead", "fr": "prospect" }
Translation: "leads" → "Leads" ❌ should be "Prospects"
Result: WARNING (inconsistent terminology)
Acceptance Criteria
Output for CI/CD Integration
For automated validation (e.g., GitHub Actions):
{
"status": "FAIL",
"exit_code": 1,
"error_count": 8,
"critical_errors": 2,
"warnings": 12,
"report_url": "gs://bucket/reports/2026-03-02.json"
}
Exit code rules:
0 = PASS (all validations successful)1 = FAIL (critical or high errors)2 = WARNINGS (only medium/low issues)
Integration with i18next
Best practice: Run this validation:
- Before merge: Every PR that modifies locale files
- Before deploy: Pre-release validation
- Post-build: After bundle creation (verify all keys are present)
Example GitHub Actions workflow:
- name: Validate i18n
run: |
# invokes i18n-validate skill
# outputs report, exits with code 0/1/2
# blocks merge if exit_code > 0 and critical errors
Known Constraints
- Dynamic keys: Keys generated at runtime (e.g.,
errors.${errorCode}) cannot be detected statically
- String concatenation: Translations built from multiple keys (e.g.,
t('errors.prefix') + t('errors.code')) are harder to validate
- Component context: Same string used in different contexts (button vs heading) may need different translations — not detected
- Pluralization: Plural forms (e.g., "1 lead", "2 leads") require special handling (not in basic validation)
Notes for Delivery Agent
This skill is validation & reporting only. It does NOT:
- Auto-fix errors
- Generate missing translations
- Remove orphaned keys
- Shorten long translations
Delivery Agent must:
- Run this skill
- Review errors + recommendations
- Manually fix issues (add missing translations, remove orphaned keys, etc.)
- Re-run validation until PASS
For bulk fixes (e.g., "translate all missing FR strings"), use idiomatique-translate skill.
