跳到主要内容

Quick Start

Translate your first locale file in 60 seconds.

1. Set Up Your Locale Files​

Create a source locale file. Rosetta supports JSON, TOML, and YAML:

locales/en.json
{
  "hero": {
    "title": "Welcome to our platform",
    "subtitle": "Build something amazing"
  },
  "nav": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}

2. Set Your API Key​

export OPENROUTER_API_KEY=sk-or-v1-...

3. Run Sync​

npx i18n-rosetta sync

Rosetta will:

  1. Auto-detect locales/en.json as the source
  2. Find (or prompt for) target languages
  3. Translate all keys
  4. Write locales/fr.json, locales/ja.json, etc.
  5. Create .i18n-rosetta.lock to track what's been translated

4. Check the Results​

cat locales/fr.json
{
  "hero": {
    "title": "Bienvenue sur notre plateforme",
    "subtitle": "Construisez quelque chose d'incroyable"
  },
  "nav": {
    "home": "Accueil",
    "about": "À propos",
    "contact": "Contact"
  }
}

What Happens Next?​

When you change a source string, rosetta detects the change via SHA-256 hash tracking and re-translates only that key on the next sync:

locales/en.json (updated)
{
  "hero": {
    "title": "Welcome to Acme Platform",  // ← changed
    "subtitle": "Build something amazing"  // ← unchanged, skipped
  }
}
npx i18n-rosetta sync
# Only "hero.title" is re-translated across all locales

Optional: Create a Config File​

For more control, generate a config file:

npx i18n-rosetta init

Or create one manually:

i18n-rosetta.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "model": "openai/gpt-4o-mini"
}

Optional: Watch Mode​

Auto-translate when your source file changes:

npx i18n-rosetta watch

Next Steps​