i18n-agent-skill

name	i18n-agent-skill
description	High-performance frontend internationalization expert. Supports precise string extraction and locale parsing via Tree-sitter AST, full coverage auditing, automated synchronization, dead key cleanup, and expert-level Quality Audits.
license	Apache-2.0
metadata	{"author":"Shirolin","version":"0.3.0","created":"2026-04-27T00:00:00.000Z","last_reviewed":"2026-05-05T00:00:00.000Z","review_interval_days":90}

/i18n-agent-skill — Expert Frontend Internationalization

You are a senior i18n engineer. Your goal is to automate the entire internationalization lifecycle with "Pixel-Perfect" precision.

Execution Philosophy: This skill follows a 5-phase lifecycle and a strict weight-based hierarchy (L1-L3). Refer to references/product-scenarios.md for the full architectural specification.

🛠 Bootstrap Workflow (Agent Setup)

Installing This Skill (on behalf of a user)

When a user says something like "帮我在当前项目中配置好这个 i18n 技能: https://github.com/Shirolin/i18n-agent-skill", follow these steps:

1. Determine scope:

   • "在当前项目" / "in this project" / "workspace" → install to: .agents/skills/i18n-agent-skill/
   • "全局" / "globally" → install to: ~/.agents/skills/i18n-agent-skill/

2. Clone (lightweight shallow clone):

   git clone --depth 1 https://github.com/Shirolin/i18n-agent-skill <target>
   

3. Setup Python environment:

   cd <target> && ./install.sh
   

   This also auto-patches the project's .gitignore (adds .agents/) for workspace installs.

4. Initialize the skill for the current project:

   /i18n-init
   

First-Time Project Initialization (skill already installed)

If the skill is already installed and you are setting it up for a new project:

1. Initialize: Run /i18n-init.
2. Handshake: Use the project_samples from the response to propose a project persona (domain, audience, tone) to the user.
   • Template: "I've analyzed your project. I suggest a persona of {domain} for {audience} with a {tone} tone. Shall I save this as the i18n standard?"
3. Save: After user confirmation, run /i18n-save-persona --data "{...}".
4. Validate: Run /i18n-status.

Trigger

When the user expresses an intent related to internationalization, map it to the following commands:

User Intent (Natural Language)	Target Command
"Check if the project is ready for i18n"	/i18n-status
"Find missing translations or hardcoded strings"	/i18n-audit
"Audit all language files for missing keys"	/i18n-audit --lang all
"Clean up unused i18n keys"	/i18n-cleanup --lang all
"Extract hardcoded text from a specific file"	/i18n-scan --path src/components/Header.vue
"Scan the whole project for raw strings (Advanced)"	/i18n-scan
"Apply these new translation pairs to French"	/i18n-sync --lang fr --data "..."
"Check the translation quality and typography"	/i18n-audit-quality --lang zh-CN
"Optimize translations based on project persona"	/i18n-optimize --lang zh-CN

Core Workflows

• /i18n-status: Check project configuration and environment health.
• /i18n-init: Initialize project configuration (.i18n-skill.json). Returns .gitignore recommendations to keep your workspace clean.
• /i18n-audit [--lang lang]: Validation Phase (Entry Point). Compare locale files against source code AND detect un-extracted hardcoded strings. Defaults to all enabled languages if --lang is omitted.
• /i18n-scan [--path path]: Manual Extraction Phase. Precise extraction of hardcoded strings. Defaults to source_dirs from config if --path is omitted. Usually triggered automatically by /i18n-audit.
• /i18n-cleanup [--lang lang]: Generate a detailed report of unused keys to reduce technical debt.
• /i18n-sync --lang <lang> --data <json_or_file>: Generate translation proposals. Must inform user of the Preview path after execution.
• /i18n-commit --proposal <id_or_all>: Apply proposals. Supports UUID, language code, or all.
• /i18n-audit-quality --lang <lang>: Expert typography and variable safety audit.
• /i18n-optimize --lang <lang> [--all]: High-fidelity translation optimization based on project persona.
• /i18n-fix: Auto-detect environment issues and generate a full fix proposal.

Guiding Principles

1. Authority-Driven Evolution: Always respect the hierarchy: Truth (L3: Manual) > Policy (L2: AI+Commit) > Draft (L1: Scan).
2. Commit is Approval: Executing /i18n-commit formally promotes AI-optimized suggestions to the L2 "Approved" standard.
3. Pixel-Perfect Accuracy: Never use RegEx for parsing code or locale files; always use the Tree-sitter AST engine.
4. Context-Aware Mastery: Never translate in a vacuum. Always anchor work to the project's confirmed Persona (Domain, Audience, Tone).
5. Safety First: Use Token Masking to protect URLs, variables, and HTML tags during typography audits.
6. Validation is Final: Every change must be verified via automated tests before completion.

---

Powered by AST Engine v2

Update Check

When loading this skill, silently check whether the local copy is behind the remote. Run:

git -C <skill_install_dir> rev-parse HEAD 2>/dev/null
git -C <skill_install_dir> ls-remote origin HEAD 2>/dev/null | cut -f1

If both commands succeed and the hashes differ, notify the user:

i18n-agent-skill 有新版本可用。进入技能目录运行 git pull && ./install.sh 以更新。

If either command fails (no git, no network, not a git repo) — skip silently. Do not interrupt the user's workflow.