Getting Started

Prerequisites

• Node.js 18+
• An LLM API key — OpenAI, Anthropic, Google, or a local Ollama instance. See Providers for details.
• A source locale file — at least one JSON, TypeScript, YAML, or PO file with your source strings.

1. Install

pnpm

pnpm add -D koto-i18n

npm

npm install -D koto-i18n

yarn

yarn add -D koto-i18n

bun

bun add -D koto-i18n

2. Run the init wizard

npx koto init

koto auto-detects your framework, i18n library, and existing locale files:

npx koto init

koto v0.1.0 ┌ Detected │ │ Framework: Next.js 14 │ i18n library: next-intl │ Source: src/locales/en.json (214 keys) │ └ ◆ Which LLM provider? │ ● OpenAI (gpt-4o-mini — fast & cheap) │ ○ Anthropic (claude-sonnet — high quality) │ ○ Google (gemini-2.5-flash — fast & cheap) │ ○ Ollama (local, free, private) ◆ Target locales? │ ◼ 🇪🇸 es ◼ 🇫🇷 fr ◼ 🇩🇪 de ◼ 🇯🇵 ja ✔ Created koto.config.ts ✔ Created koto.lock

3. Set your API key

OpenAI

export OPENAI_API_KEY=sk-...

Anthropic

export ANTHROPIC_API_KEY=sk-ant-...

Google

export GOOGLE_API_KEY=...

Ollama

No API key needed — just make sure Ollama is running:

ollama serve

4. Translate

npx koto translate

npx koto translate

koto v0.1.0 Translating → 🇪🇸 🇫🇷 🇩🇪 🇯🇵 (4 locales) 🇪🇸 es ████████████████████████████████ 214/214 ✓ 🇫🇷 fr ████████████████████████████████ 214/214 ✓ 🇩🇪 de ████████████████████████████████ 214/214 ✓ 🇯🇵 ja ████████████████████████████████ 214/214 ✓ ✓ 856 translations written in 4.7s Quality score: 97/100

What just happened?

1. Diff — koto compared your source locale against each target. Only new or changed keys were queued.
2. Translate — Pending keys were sent to your LLM with the appropriate context profile, batched for speed.
3. Write — Translated strings were written to your target locale files. A lockfile (koto.lock) was updated so the next run skips unchanged keys.

Files created

File	Purpose
koto.config.ts	Project configuration
koto.lock	Content hashes for incremental translation — commit this
src/locales/es.json	Translated locale files (one per target)

Tip

Commit koto.lock to your repo. It lets koto skip unchanged keys on subsequent runs.

Next steps

• Context profiles — give different sections of your app different translation tones
• Type safety — generate TypeScript types from your translation keys
• CI/CD — translate automatically on every PR
• CLI reference — all commands and flags