Localization you run yourself.

Paste this into Claude Code, Cursor, Codex, or opencode from your project root. Your agent reads the Rosetta skill and does the whole setup, then opens one PR for you to review.

Set up Rosetta (npm: rosetta-i18n) for translations in this repo. Follow https://raw.githubusercontent.com/ian/rosetta/main/skills/rosetta/SKILL.md step by step: discover our locale files and current translation setup and report back, configure .rosetta/config.json, adopt our existing translations with `rosetta status` + `rosetta push` (list any translations it flags as broken), add tests and CI, remove the old translation tooling, document the workflow in AGENTS.md, and open one PR. Ask me before running `push --force`, before any large translation run, and before choosing how translations land if it's unclear.

What your agent will do

1. Discover. Finds your i18n runtime, locale files, locale list, and current translation setup, then reports back.
2. Configure. Writes .rosetta/config.json and carries over your brand voice, context, and do-not-translate terms.
3. Adopt. Records your existing translations for free, and lists any that are broken today.
4. Guard. Adds tests that keep the config in sync with your app's locale list.
5. Wire up CI. Keeps your existing flow, or proposes check, commit, or PR mode.
6. Clean up. Removes the old tooling, documents the workflow in AGENTS.md, and opens one PR.

It asks before anything expensive: push --force, large translation runs, or choosing how translations land.

Keep your agent fluent

Install the Rosetta skill so everyday requests ("add a German string", "why is the i18n job red?") just work. For agents that can't fetch URLs, use the self-contained prompt.

# Claude Code (other agents: see docs/agent-prompt.md)
mkdir -p .claude/skills/rosetta && curl -fsSL https://raw.githubusercontent.com/ian/rosetta/main/skills/rosetta/SKILL.md -o .claude/skills/rosetta/SKILL.md

1. Install

   Add Rosetta as a dev dependency. The package is rosetta-i18n, and it installs arosetta command.

   Copy install command

   npm install -D rosetta-i18n@next

2. Create the config

   init finds your source files (messages/en.json,locales/en/*.json, pages.en.json, …), infers target locales from the files next to them, and writes .rosetta/config.json. Coming from Lingo.dev? Use--from-lingo.

   Copy init command

   npx rosetta init
   # or: npx rosetta init --pattern messages/en.json --target es,fr,de
   # or: npx rosetta init --from-lingo

3. Tune the engine

   Pick a model and give it your brand voice and never-translate terms. Add lockedKeysfor anything that must stay identical (URLs, prices), and a context per file.

   .rosetta/config.json

   {
     "sourceLocale": "en",
     "targetLocales": ["es", "fr", "de", "ja", "pt-BR", "zh-CN"],
     "files": [
       { "pattern": "messages/en.json", "context": "Acme web app UI" }
     ],
     "engine": {
       "model": "anthropic/claude-sonnet-4.5",
       "brandVoice": { "*": "Friendly, plain, and direct." },
       "glossary": { "*": { "Acme": "Acme" } }
     }
   }

4. Add your model key

   Rosetta has no key of its own. Use your OpenRouter key, or point engine.baseURL at any OpenAI-compatible endpoint and set engine.apiKeyEnv to its variable.

   export OPENROUTER_API_KEY=sk-or-...

5. Preview, then push

   status shows what would happen, with no key and no cost. The first pushadopts your existing translations for free and translates only what's missing, changed, or broken.

   Copy commands

   npx rosetta status   # es  3 to translate · 412 to adopt
   npx rosetta push     # writes locale files + .rosetta/lock.json

6. Commit, then keep it in sync

   Commit .rosetta/ with your locale files. From then on it's edit English → push → commit, run yourself, by an agent, or by the GitHub Action.

   .github/workflows/i18n.yml

   on:
     pull_request:
     push: { branches: [main] }
   jobs:
     i18n:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: ian/rosetta@v1.0.0-beta.3
           with:
             # PRs: check (no key needed). main: translate + open a PR.
             mode: ${{ github.event_name == 'pull_request'
               && 'check' || 'pull-request' }}
           env:
             OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}