Agent skill

i18n-glossary-sync

Maintain a canonical i18n glossary file — sync new terms across all language pairs, detect drift, flag missing translations, and enforce consistent terminology across the codebase.

View SKILL.md on GitHub Repository
Stars 123
Forks 27

Install this agent skill to your Project

npx add-skill https://github.com/Fr-e-d/GAAI-framework/tree/main/.gaai/core/skills/cross/i18n-glossary-sync

SKILL.md

Skill: i18n Glossary Sync (Term Consistency)

Purpose

Ensure all domain-specific terms used in i18n translations are documented in the glossary and applied consistently across all languages. Prevents terminology drift and simplifies future language additions.

Usage context: Post-extraction, post-translation, and ongoing (every release). Keeps glossary in sync with actual usage.

Input

json
{
  "locales_path": "locales/",
  "glossary_path": "domains/i18n/glossary.md",
  "languages": ["en", "fr", "de", "es"],
  "domain_terms": [
    "lead", "prospect", "expert", "milestone", "direct link",
    "spending limit", "flag", "qualification rate", "trust score"
  ],
  "analysis_mode": "comprehensive",  // or "quick" (just check coverage)
  "output_format": "json"
}

Output

json
{
  "glossary_summary": {
    "status": "NEEDS_UPDATE",         // UP_TO_DATE, NEEDS_UPDATE, CRITICAL_GAPS
    "glossary_terms": 28,
    "translations_found": 26,
    "missing_translations": 2,
    "inconsistent_usage": 5,
    "new_terms_discovered": 3,
    "deprecated_terms": 1,
    "last_updated": "2026-03-01"
  },
  "term_analysis": [
    {
      "term": "lead",
      "status": "INCONSISTENT",
      "glossary": {
        "en": "lead",
        "fr": "prospect",
        "de": "Lead",
        "es": "prospecto"
      },
      "actual_usage": {
        "en": {
          "usage_count": 12,
          "variants": ["lead", "leads"],
          "consistent": true
        },
        "fr": {
          "usage_count": 11,
          "variants": ["prospect", "prospects", "Leads"],  // ❌ "Leads" is variant
          "consistent": false,
          "inconsistent_instances": [
            {
              "key": "dashboard.leads.header",
              "text": "Mes Leads",
              "should_be": "Mes prospects",
              "file": "locales/fr/dashboard.json",
              "line": 15
            }
          ]
        },
        "de": {
          "usage_count": 8,
          "variants": ["Lead", "Leads"],
          "consistent": true
        },
        "es": {
          "usage_count": 9,
          "variants": ["prospecto", "prospectos"],
          "consistent": true
        }
      },
      "recommendations": [
        "Fix FR usage: change 'Leads' to 'prospect' in dashboard.leads.header",
        "Update glossary note: explain EN 'lead' vs FR 'prospect' distinction"
      ]
    },
    {
      "term": "milestone",
      "status": "COMPLETE",
      "glossary": {
        "en": "milestone",
        "fr": "jalon",
        "de": "Meilenstein",
        "es": "hito"
      },
      "actual_usage": {
        "en": { "usage_count": 24, "variants": ["milestone", "milestones"], "consistent": true },
        "fr": { "usage_count": 24, "variants": ["jalon", "jalons"], "consistent": true },
        "de": { "usage_count": 24, "variants": ["Meilenstein", "Meilensteine"], "consistent": true },
        "es": { "usage_count": 24, "variants": ["hito", "hitos"], "consistent": true }
      },
      "recommendations": []
    },
    {
      "term": "qualification_rate",
      "status": "MISSING_TRANSLATION",
      "glossary": {
        "en": "qualification rate",
        "fr": null,                   // ❌ missing
        "de": null,                   // ❌ missing
        "es": null                    // ❌ missing
      },
      "actual_usage": {
        "en": { "usage_count": 5, "variants": ["qualification rate", "qualification_rate"], "consistent": true },
        "fr": { "usage_count": 4, "variants": ["taux de qualification"], "consistent": true },
        "de": { "usage_count": 4, "variants": ["Qualifizierungsquote"], "consistent": true },
        "es": { "usage_count": 4, "variants": ["tasa de calificación"], "consistent": true }
      },
      "recommendations": [
        "Add FR translation to glossary: 'taux de qualification'",
        "Add DE translation to glossary: 'Qualifizierungsquote'",
        "Add ES translation to glossary: 'tasa de calificación'"
      ]
    }
  ],
  "discovered_terms": [
    {
      "term": "free mode",
      "languages": {
        "en": "free mode",
        "fr": "mode gratuit",
        "de": "kostenloser Modus",
        "es": "modo gratuito"
      },
      "usage_count": 3,
      "recommendation": "Add to glossary (new term in E12S16 direct link pricing)"
    },
    {
      "term": "spending limit",
      "languages": {
        "en": "spending limit",
        "fr": "limite de dépenses",
        "de": "Ausgabenlimit",
        "es": "límite de gasto"
      },
      "usage_count": 8,
      "recommendation": "Already in glossary, but verify ES variant ('límite de gasto' vs 'límite de gastos')"
    }
  ],
  "deprecated_terms": [
    {
      "term": "matchable",
      "glossary_status": "active",
      "usage_count": 0,
      "recommendation": "Remove from glossary — replaced by 'profil visible' (E12S13 milestone rename)"
    }
  ],
  "pluralization_analysis": {
    "status": "NEEDS_REVIEW",
    "note": "Plural forms detected but not formally managed. Consider i18next-plural extension for full support.",
    "examples": [
      {
        "term": "lead/leads",
        "en_variants": ["lead", "leads"],
        "fr_variants": ["prospect", "prospects"],
        "current_handling": "Both forms in translation strings (manual)",
        "recommended": "Use i18next pluralization plugin (lead_singular, lead_plural)"
      }
    ]
  },
  "statistics": {
    "glossary_coverage": "92.8%",     // terms in glossary / discovered terms
    "translation_coverage": {
      "fr": "100%",
      "de": "92.8%",
      "es": "96.4%"
    },
    "consistency_score": {
      "en": "100%",
      "fr": "88%",
      "de": "95%",
      "es": "98%"
    },
    "missing_glossary_entries": 2,
    "inconsistent_term_usage": 5,
    "deprecated_terms": 1
  },
  "glossary_update_proposal": {
    "add_terms": [
      {
        "term": "free mode",
        "translations": {
          "en": "free mode",
          "fr": "mode gratuit",
          "de": "kostenloser Modus",
          "es": "modo gratuito"
        },
        "context": "Direct link feature (E12S16) — when spending limit exceeded",
        "source": "auto-discovered from locales/*/dashboard.json"
      }
    ],
    "update_terms": [
      {
        "term": "qualification rate",
        "action": "add missing translations",
        "add": {
          "fr": "taux de qualification",
          "de": "Qualifizierungsquote",
          "es": "tasa de calificación"
        }
      }
    ],
    "remove_terms": [
      {
        "term": "matchable",
        "reason": "Replaced by 'profil visible' (milestone rename E12S13)",
        "deprecation_date": "2026-03-02"
      }
    ]
  },
  "recommendations": [
    "Update glossary with 'free mode' (new term from E12S16)",
    "Fix FR inconsistency: change 'Mes Leads' → 'Mes prospects' in dashboard.leads.header",
    "Complete glossary translations for 'qualification_rate' (FR, DE, ES already used, just not in glossary)",
    "Consider using i18next pluralization plugin for robust lead/leads handling",
    "Review ES variant: 'límite de gasto' vs 'límite de gastos' (use consistently)",
    "Remove deprecated term 'matchable' from glossary (replaced by 'profil visible')"
  ]
}

Sync Principles (Industry Best Practices)

1. Single Source of Truth for Terminology

Glossary is the canonical reference. All translations should match glossary definitions.

glossary.md:
  "lead": { "en": "lead", "fr": "prospect", "de": "Lead" }

locales/fr/dashboard.json should use "prospect", not "Leads" or "client"

2. Plural Forms Strategy

Different languages handle pluralization differently. Options:

Option A: Manual (current MVP approach)

json
{
  "leads.singular": "1 lead",
  "leads.plural": "{count} leads"
}

Option B: i18next-plural (recommended post-MVP)

json
{
  "lead_one": "1 lead",
  "lead_other": "{count} leads"
}

Glossary should document chosen approach.

3. Variant Tracking

Some terms have multiple forms (singular/plural, capitalized/lowercase). Glossary should document ALL accepted variants.

Term: "lead"
Variants:
  - "lead" (singular)
  - "leads" (plural)
  - "Lead" (capitalized, rare)
Status: All variants acceptable if consistent per context

4. Deprecation Lifecycle

When renaming terms (e.g., milestone rename E12S13):

1. Add new term to glossary ("profil visible")
2. Mark old term as deprecated ("matchable")
3. Update all usage in translations (batch replace)
4. Keep deprecated entry for 1 release (document why)
5. Remove deprecated entry in next major version

Acceptance Criteria

  • AC1: Detects all domain terms used in translation files
  • AC2: Cross-references against glossary (coverage ≥ 95%)
  • AC3: Identifies inconsistent usage (same term, different translations)
  • AC4: Flags missing glossary translations (e.g., FR exists in files but not in glossary)
  • AC5: Discovers new terms and proposes glossary additions
  • AC6: Identifies deprecated terms (in glossary but not used)
  • AC7: Analyzes pluralization strategy (singular/plural variants)
  • AC8: Provides consistency score per language (target: ≥ 95%)

Glossary File Format

Canonical format (Markdown with YAML table):

markdown
# {YourProject} i18n Glossary

## Domain Terms

| Term | EN | FR | DE | ES | Context | Notes | Variants |
|---|---|---|---|---|---|---|---|
| dashboard | dashboard | tableau de bord | Dashboard | panel | Navigation | Main overview screen | dashboard, dashboards |
| workspace | workspace | espace de travail | Arbeitsbereich | espacio de trabajo | Multi-tenant | Container for projects/users | workspace, workspaces |
| plan | plan | forfait | Tarif | plan | Billing | Subscription tier name | plan, plans |

## Deprecation Log

| Deprecated | Replaced By | Deprecation Date | Removal Date |
|---|---|---|---|
| matchable | profil visible | 2026-03-02 | 2026-06-02 |

Integration with Translation Workflow

  1. Extract strings → i18n-extract skill
  2. Batch translate → idiomatic-translate skill (check glossary reference)
  3. Validate translations → i18n-validate skill
  4. Sync glossary → i18n-glossary-sync skill (this one)
  5. Commit → All glossary updates included in PR

Notes for Delivery Agent

This skill is audit + proposal only. Delivery Agent must:

  1. Run this skill (generates report + proposals)
  2. Review "glossary_update_proposal" section
  3. Manually update domains/i18n/glossary.md (or use glossary editor UI post-MVP)
  4. Re-run skill to verify sync is complete

Post-MVP: Consider UI editor for glossary management (no-code glossary updates).

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

Fr-e-d/GAAI-framework

ci-watch-and-fix

Watch GitHub Actions CI after PR creation, detect failures, extract logs, apply minimal fixes, and re-push — keeping the delivery session alive until CI resolves or escalating after 3 cycles. Activate immediately after gh pr create and before marking the story done.

123 27
Explore
Fr-e-d/GAAI-framework

qa-review

Validate that implemented code fully satisfies Story acceptance criteria, respects rules, and introduces no regressions. This is the hard quality gate — no pass means no delivery. Activate after implementation is complete.

123 27
Explore
Fr-e-d/GAAI-framework

compose-team

Assemble the context bundles for each sub-agent based on evaluate-story output. Produces spawn-ready packages for Planning, Implementation, QA, or MicroDelivery sub-agents. Activate after evaluate-story, before spawning any sub-agent.

123 27
Explore
Fr-e-d/GAAI-framework

coordinate-handoffs

Validate sub-agent handoff artefacts, sequence phase transitions, and manage retry and escalation logic. Activate after each sub-agent terminates to determine next action.

123 27
Explore
Fr-e-d/GAAI-framework

implement

Generate correct, minimal, maintainable code that satisfies a validated Story's acceptance criteria against an execution plan. Activate when a Story is validated, a plan exists, and all prerequisites are unambiguous.

123 27
Explore
Fr-e-d/GAAI-framework

delivery-high-level-plan

Transform validated Stories into a clear, minimal, governed execution plan. Used by the Planning Sub-Agent as the first planning pass before prepare-execution-plan for Tier 2/3, or as the sole planning output for simple Stories.

123 27
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results