Introduction 🫥
The recent addition to the current generation of Agentic AI is Skills. Instead of a formal definition, the analogy is closely related to skills that humans possess, which provide them with an edge over others, but not for agents. This is a nascent space since most of the teams and organizations are creating the required skills for their product. This looks like the right time to introduce the ideology of i8n to Skills. Let's understand in depth the need and solution for the same.
Why i8n for skills❓
Let's understand the primary reasons that you will be missing if skills aren't internationalized:
- Agent skills are instructions: if your team or users don't read the default, the skill is useless regardless of how well it's written.
- Language Unification — an agent skill in Japanese, Hindi, or Arabic unlocks entire engineering communities that would otherwise skip it entirely.
- Technical details survive translation — with a proper glossary, terms like MCP, SKILL.md, and API stay intact while the surrounding instructions become locally natural.
- Skills out of sync without i18n infrastructure — When the source skill updates, translated copies fall out of sync. A standardised tool makes re-translation a one-command operation, not a manual effort.
- Agent ecosystems are Global 🌍 — Claude, Cursor, and other agents are deployed worldwide. Skills that can't localise are a ceiling on how far an agent platform can actually reach.
This is where the skills-i8n project or tool comes to the rescue. It easily fits into the current skills framework without needing any fancy plugins and heavy dependencies. Get your free API key at lingo.dev.
Features of the tool ✨
-
Async concurrency with semaphore limit — all skills translate in parallel using
asyncio, bounded by--concurrency(default 3, max 10). A 10-skill repo doesn't make 10 simultaneous API calls — it makes 3 at a time, preventing rate-limit errors while still being significantly faster than sequential translation. - One request, full context — name, description, and the entire body travel as a single flat payload. The Lingo.dev engine applies Glossary, Brand Voice, and Instructions holistically across the whole skill, not on separate strings.
-
Zero SDK dependency — talks directly to
api.lingo.devvia purehttpx. No third-party wrapper that can silently break or lag behind the real API. - Repo-aware, incremental by default — discovers skills across all known agent layouts (.claude/skills/, skills/*/, flat), skips already-translated files, copies companion scripts and assets untouched. Re-run safely after any source skill update.
-
Engine ID unlocks production-grade localization — pass
--engine-id eng_xxxand every translation inherits your org's configured glossary, brand voice, and per-locale LLM selection — all without touching the code.
Setup 🔌
Follow these steps to get your first translation:
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone repository
git clone https://github.com/srini047/skills-i18n
cd skills-i18n
# Install dependencies
uv sync
# Set environment variables
cp .env.example .env
# OR
export LINGODOTDEV_API_KEY=your_key_here
🎉 You have successfully installed the tool and are ready to proceed with your first translation.
Workflow 🏗️
Tool usage 🛠️
Now that we have all set up, let's understand what this tool has to offer you:
➜ skills-i18n git:(master) uv run skills-i8n --help
Usage: skills-i8n [OPTIONS] COMMAND [ARGS]...
🌐 i8n for AI Agent Skills — powered by Lingo.dev
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ translate Translate all SKILL.md files in a skills repository. │
│ scan Scan a skills repository and list discovered SKILL.md files. │
│ list-locales List all locales supported by Lingo.dev. │
│ detect Detect the source language of a SKILL.md file. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Translate 💬
Core implementation of the tool, where the SKILL.md is translated from the detected language to the target language. It preserves the directory structure.
➜ skills-i18n git:(master) uv run skills-i8n translate ./example_skills de
____ _ _ _ _ _ ___
/ ___|| | _(_) | |___ (_)( _ ) _ __
\___ \| |/ / | | / __|_____| |/ _ \| '_ \
___) | <| | | \__ \_____| | (_) | | | |
|____/|_|\_\_|_|_|___/ |_|\___/|_| |_|
Skill i18n · powered by Lingo.dev
╭──────────────────────────────────────────────── 🌐 skills-i8n Translation Job ─────────────────────────────────────────────────╮
│ Repository: /Users/apple/Documents/skills-i18n/example_skills │
│ Target: de · German │
│ Source: en │
│ Output: /Users/apple/Documents/skills-i18n/example_skills/i8n │
│ Engine: eng_L7DVg4T8pYoYu8BJ │
│ Threads: 3 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Found 3 skill(s) to translate:
• code-review (code-review/SKILL.md)
• pdf-processing (pdf-processing/SKILL.md)
• readme-writer (readme-writer/SKILL.md)
⏭ readme-writer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
📊 Translation Results — de (German)
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Skill ┃ Status ┃ Output Path ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ code-review │ ⏭ skipped │ de/code-review/SKILL.md │
│ pdf-processing │ ⏭ skipped │ de/pdf-processing/SKILL.md │
│ readme-writer │ ⏭ skipped │ de/readme-writer/SKILL.md │
└────────────────┴────────────┴────────────────────────────┘
✓ 3 succeeded
Output: /Users/apple/Documents/skills-i18n/example_skills/i8n
Scan 🔍
Before translating, it's advised that you execute the scan command, which lists the relative path of the SKILL.md file that would be translated. It provides a tabular output for quick reference that helps you decide beforehand if any modification(s) is/are required.
uv run skills-i8n scan ./example_skills
____ _ _ _ _ _ ___
/ ___|| | _(_) | |___ (_)( _ ) _ __
\___ \| |/ / | | / __|_____| |/ _ \| '_ \
___) | <| | | \__ \_____| | (_) | | | |
|____/|_|\_\_|_|_|___/ |_|\___/|_| |_|
Skill i18n · powered by Lingo.dev
📁 Skills in example_skills
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name ┃ Description ┃ License ┃ Path ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ code-review │ Performs thorough code reviews covering bugs, security │ Apache-2.0 │ code-review/SKILL.md │
│ │ vulnerabilities, performa… │ │ │
│ pdf-processing │ Extract text and tables from PDF files, fill PDF forms, merge and │ Apache-2.0 │ pdf-processing/SKILL.md │
│ │ split document… │ │ │
│ readme-writer │ Creates and writes professional README.md files for software projects. │ Apache-2.0 │ readme-writer/SKILL.md │
│ │ Use when … │ │ │
└────────────────┴────────────────────────────────────────────────────────────────────────┴────────────┴─────────────────────────┘
3 skill(s) found.
List Locales📝
Currently, lingo.dev supports an array of locales, and I have tried to port in most of them, which ideally means some are pending for sure. Feel free to reach out to me in case a target language you are looking for is missing incase.
➜ skills-i18n git:(master) ✗ uv run skills-i8n list-locales
____ _ _ _ _ _ ___
/ ___|| | _(_) | |___ (_)( _ ) _ __
\___ \| |/ / | | / __|_____| |/ _ \| '_ \
___) | <| | | \__ \_____| | (_) | | | |
|____/|_|\_\_|_|_|___/ |_|\___/|_| |_|
Skill i18n · powered by Lingo.dev
🌍 Supported Locales (83+)
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Code ┃ Language ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ af │ Afrikaans │
│ sq │ Albanian │
│ am │ Amharic │
│ ar │ Arabic │
│ │ │
│ ... │ ... │
│ │ │
│ yo │ Yoruba │
│ zu │ Zulu │
└────────────┴───────────────────────┘
83 locale(s) shown.
Detect 🕵️
You can also detect the language of the current SKILL.md file using the detect command. This will help you translate to the right target language and save time on debugging why your translation didn't succeed 😅
➜ skills-i18n git:(master) ✗ uv run skills-i8n detect ./example_skills/readme-writer/SKILL.md
____ _ _ _ _ _ ___
/ ___|| | _(_) | |___ (_)( _ ) _ __
\___ \| |/ / | | / __|_____| |/ _ \| '_ \
___) | <| | | \__ \_____| | (_) | | | |
|____/|_|\_\_|_|_|___/ |_|\___/|_| |_|
Skill i18n · powered by Lingo.dev
╭──────────────────────────────────────────────────── 🔍 Language Detection ─────────────────────────────────────────────────────╮
│ Skill: readme-writer │
│ Detected locale: en — English │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Traversing the code 🧑💻
Keeping line-by-line code aside, summarized the overall repository structure and what each part achieves in its entirety.
.
├── example_skills
│ ├── i8n # Directory containing translated SKILL.md files (organized by locale)
│ │ ├── de
│ │ │ ├── code-review
│ │ │ │ └── SKILL.md
│ │ │ ├── pdf-processing
│ │ │ │ └── SKILL.md
│ │ │ └── readme-writer
│ │ │ └── SKILL.md
│ │ └── es
│ │ ├── code-review
│ │ │ └── SKILL.md
│ │ ├── pdf-processing
│ │ │ └── SKILL.md
│ │ └── readme-writer
│ │ └── SKILL.md
│ ├── pdf-processing
│ │ └── SKILL.md
│ └── readme-writer
│ └── SKILL.md
├── LICENSE
├── pyproject.toml # Project configuration and dependencies
├── README.md
├── skills_i8n
│ ├── __init__.py
│ ├── cli.py # Command-line interface for the tool
│ ├── parser.py # Parses SKILL.md files into structured data
│ ├── repo.py # Orchestrates skill discovery and parsing
│ └── translator.py # Translation module with lingo.dev interaction
└── uv.lock # Lock file for dependencies
Next steps
I don't want to call it a Conclusion; instead, I would want you to give the tool a try as the next step. Furthermore, to improve this tool further, I have some ideas:
- Make it part of the RFC standard of Agent Skills.
- Integrate AI reviewer to validate Lingo.dev's localization engines' output statistics and confident translation results rendered.
- Integrate as part of the CI/CD pipeline and also make it available as a git hook.
Since both of us have next steps, let us sign off and work on those steps. Until then, this is Sriniketh J | srini047 signing off. Hope you had a fruitful time reading this article.
Top comments (0)