i1n-cli

# i1n

**Your app in every language. One command.**

[![npm](https://img.shields.io/npm/v/i1n)](https://www.npmjs.com/package/i1n) [![license](https://img.shields.io/npm/l/i1n)](https://github.com/Pakvothe/i1n-cli/blob/main/LICENSE) [![MCP](https://img.shields.io/badge/MCP-9_tools-amber)](https://i1n.ai) [![Listed on MCP Servers](https://img.shields.io/badge/mcpservers.org-listed-blue)](https://mcpservers.org/servers/pakvothe/i1n-cli) [![Security: DeepSec](https://img.shields.io/badge/security-DeepSec_audited-success)](https://github.com/vercel-labs/deepsec)

![demo](./demo.gif)

Localization as code. Push your translation keys, AI translates to 182 languages, pull type-safe TypeScript definitions. Built for developers, AI agents, and product teams.

**Free forever** · No credit card · [i1n.ai](https://i1n.ai)

---

## Why i1n?

Traditional i18n means dozens of JSON files, zero type safety, hours of copy-pasting, and deploys that break at 2 AM. Existing tools charge $144+/mo and require browser-based workflows.

i1n is different:

- **One command** — `i1n push --translate es,fr,ja` and you're done
- **Type-safe** — auto-generated `i1n.d.ts` with full IDE autocomplete
- **AI-native** — MCP server for Cursor, Claude Code, Windsurf. Your agent handles i18n for you
- **Zero migration** — Bridge Mode wraps your existing i18next/next-intl/vue-i18n
- **5x cheaper** — Free tier included. Pro at $29/mo vs Lokalise at $144/mo

---

## 📦 Install

```bash
# To use the CLI (global)
npm install -g i1n

# To use the SDK + types (in your app)
npm install i1n

# Local CLI usage (optional)
npm install -D i1n
```

_Supports `npm`, `pnpm`, `yarn`, and `bun`._

---

## 🏁 Quick Start

```bash
# 1. Initialize (auth + auto-detect setup)
i1n init

# 2. Push your translation keys
i1n push

# 3. Pull translations + auto-generated TypeScript types
i1n pull
```

---

## ✨ Key Features & Commands

### 🛠️ `i1n init`

**Interactive setup that prepares your workspace.**

- Authenticates via API key.
- **New?** If you don't have a key yet, the CLI provides clear guidance on how to get started.
- Auto-detects frameworks (Next.js, Vite, Expo, Flutter, Rails, etc.).
- Saves configuration to `i1n.config.json` (automatically ignored via `.gitignore`).
- **AI Orchestration**: Optionally sets up rules for your AI coding tools.

### ⬆️ `i1n push`

**Syncs your local translations to i1n.**

- Detects new keys and source changes.
- **Smart Translate**: Offers to translate missing keys with a cost estimate before proceeding.
- Efficient caching layer — repeated translations cost a fraction of fresh ones.
- **Three-way diff** — push only sends the (key, lang) pairs you actually changed, never overwriting edits made via the dashboard or by other teammates. See [Team workflow](#-team-workflow) for the full conflict model.

**Flags:**

- `--translate [langs]` — trigger AI translation after push (e.g. `--translate es,fr,ja`)
- `--strategy <mode>` — how to handle real conflicts: `interactive` (default in TTY), `ours`, `theirs`, `abort`
- `--force` — shorthand for `--strategy ours` (overwrite the server with your local values; destructive)

### ⬇️ `i1n pull`

**Downloads translations and generates type-safe IDs.**

- Updates local locale files in your configured format.
- Generates `i1n.d.ts` for full IDE autocomplete.

### 📊 `i1n limits`

**Real-time usage tracking.**

- View your current plan and credit usage.
- Monitor active language slots and available capacity.

### ✅ `i1n check`

**Catch broken translations before they ship. Built for CI.**

- Detects missing keys per language, **broken interpolation placeholders** (`{{count}}` lost in translation), empty values, and malformed files.
- `--min-coverage 95` fails the build when translation coverage drops below your threshold.
- `--json` for tooling. Exit codes: `0` clean, `1` errors found, `2` config problem.
- 100% offline — no API calls, no secrets needed in CI.

```yaml
# .github/workflows/ci.yml
- name: Validate translations
  run: npx i1n check --min-coverage 95
```

### 🧠 `i1n setup-ai`

**Turns your IDE into a localization expert.**

- Generates project-specific rules for **Cursor (`.mdc`)**, **Claude Code (`CLAUDE.md`)**, **Windsurf**, and more.
- Ensures AI agents follow your naming conventions, file structure, and brand voice.

### 🔌 `i1n mcp`

**MCP server for AI coding assistants.**

Starts a [Model Context Protocol](https://modelcontextprotocol.io) server that lets Cursor, Claude Code, Windsurf, and other AI assistants execute i1n commands directly from your IDE.

```bash
# Add to Claude Code
claude mcp add i1n -- npx i1n mcp

# Or add to .mcp.json / cursor config
```

```json
{
  "mcpServers": {
    "i1n": {
      "command": "npx",
      "args": ["i1n", "mcp"]
    }
  }
}
```

**9 tools available:**

| Tool | Description |
| ---- | ----------- |
| `i1n_status` | Get project status, plan, limits, and active languages |
| `i1n_check` | Validate locale files offline: missing keys, broken placeholders, coverage |
| `i1n_push` | Push local translation files with three-way diff (preserves server-side edits, aborts on conflict so the agent can resolve) |
| `i1n_pull` | Pull translations and generate type-safe TypeScript definitions |
| `i1n_translate` | Translate keys to specified languages using AI |
| `i1n_add_language` | Add new languages with optional auto-translation |
| `i1n_extract_and_translate` | Extract strings from code, push as keys, translate to all languages |
| `i1n_search` | Search existing translation keys by name or value |
| `i1n_setup_bridge` | Detect your i18n library (i18next, vue-i18n, next-intl, etc.) and wire up i1n bridge mode end-to-end |

**The killer workflow** — tell your AI agent "internationalize this component":

1. The agent reads your file and identifies hardcoded strings
2. It calls `i1n_extract_and_translate` with the extracted strings
3. i1n pushes the keys, translates to all active languages, generates types
4. The agent rewrites your component with `t('key')` calls

A 60-minute task in 30 seconds.

---

## 👥 Team workflow

i1n is designed for teams where multiple people edit translations in parallel — devs in different branches, copywriters in the dashboard, AI agents via MCP. `i1n push` is safe to run without worrying that your local working tree might pulverize someone else's edits.

### How push decides what to send

Before every push, the CLI:

1. Reads your local locale files (`L`).
2. Asks the server which keys exist and when each was last modified (cheap metadata-only call, ~50× smaller than a full pull).
3. If anything moved on the server since your last sync, fetches the full server state (`S`).
4. Computes a three-way diff per `(namespace, key, lang)` against the last baseline you synced (`P`, stored in `locales/.i1n-push-state.json`).

For each `(key, lang)` the diff places it in one of these buckets:

| Local | Server | Baseline | Action |
| --- | --- | --- | --- |
| `==` server | — | — | unchanged, skip |
| `==` baseline | changed | — | **server-only** — auto-pull into your locale files |
| changed | `==` baseline | — | **local edit** — push it |
| changed | changed | both moved | **conflict** — resolve interactively |
| missing | present | present in baseline | warn, don't propagate (no delete verb) |

Only the languages that genuinely changed locally are sent. Languages you didn't touch are not in the payload, so the server's per-language merge preserves them. No more "my push silently overwrote yield_rate that I never even opened".

### When there's a real conflict

A real conflict means **you and someone else both edited the same `(key, lang)` to different values** since the last sync. The CLI shows each one and asks you to pick:

```
Conflict 1/3: common.greeting [en_us]

  › Keep local: "Hello there"
    Accept server: "Hi"
    Abort push
```

- **Local** → push your value, overwrite the server.
- **Server** → discard your local, auto-pull the server's value into your file.
- **Abort** → exit; nothing is pushed.

For batch / CI / non-interactive environments, pass a strategy:

```bash
i1n push --strategy theirs   # accept all server values, push nothing for conflicts
i1n push --strategy ours     # local wins (alias: --force)
i1n push --strategy abort    # exit on any conflict
```

In non-TTY contexts (e.g. CI without a strategy flag), push aborts with a diff of the conflicts so you can resolve in code.

### Auto-pulling server-only changes

If a teammate or someone in the dashboard updated a key you never touched, the server's value is automatically written into your local file at push time and your `i1n.d.ts` is regenerated if needed. Your working tree ends up reflecting reality — your `git diff` will show the bring-in so you can commit it alongside your own changes.

### MCP push (AI agents)

The MCP `i1n_push` tool runs the same diff but defaults to **abort on conflict** because an AI agent should not silently pick a winner. Conflicts are reported in the response so the agent can decide to pull, ask you, or resolve manually before retrying.

### Fresh checkouts

`locales/.i1n-push-state.json` is gitignored by design — it's working-tree state, like `.git/index`. On a fresh clone or new branch where the file doesn't exist, the baseline is synthesized from the server. Any local divergence from the server is then treated as a conflict (the CLI can't tell whether you edited locally or have stale data). Run `i1n pull` first if you just cloned and want to bring everything in cleanly.

---

## 📁 Supported Formats

| Format            | Frameworks                   | File Sample           |
| ----------------- | ---------------------------- | --------------------- |
| **Nested JSON**   | i18next, next-intl, vue-i18n | `en/common.json`      |
| **Flat JSON**     | React Native, Generic        | `locales/en.json`     |
| **ARB**           | Flutter / Dart               | `app_en.arb`          |
| **YAML**          | Ruby on Rails