i18dev-cli

CLI for managing i18n translations with i18.dev. Sync translation files, extract strings from source code, manage namespaces, and automate your localization workflow.

Installation

Global (recommended)

npm install -g i18dev-cli

One-off with npx

npx i18dev-cli <command>

Local project

npm install --save-dev i18dev-cli

Quick Start

# 1. Initialize your project
i18dev init

# 2. Pull translations from i18.dev
i18dev pull

# 3. (Later) Push local translations back
i18dev push

Authentication

i18.dev uses two tokens:

| Token | Env Variable | Used for | |-------|-------------|----------| | Project API Key | I18DEV_API_KEY | Read operations: pull, status, namespace list, init, setup | | Personal Access Token | I18DEV_PAT_TOKEN | Write operations: push, extract, namespace create, string add/update/delete |

• Project API Key — found in your project's Settings on i18.dev
• Personal Access Token — found in your Account Settings on i18.dev

Configuration

Config file

Create an i18dev.config.cjs in your project root (recommended for all project types, including ESM):

/** @type {import('i18dev-cli').I18DevConfig} */
module.exports = {
  output_dir: "./locales",
  format: "json",
  default_namespace: "common",
  namespaces: ["common", "auth", "dashboard"],
  languages: ["en", "es", "fr"],
  confirmed_only: false,
};

Note: i18dev-cli looks for config in this order: i18dev.config.cjs → i18dev.config.js → i18dev.config.json → .i18devrc → .i18devrc.json → package.json under the "i18dev" key.

Environment variables

| Variable | Required by | Description | |----------|-------------|-------------| | I18DEV_API_KEY | All commands | Project API key for authentication | | I18DEV_PAT_TOKEN | Write commands | Personal Access Token for push, extract, create, update, delete. Found in Account Settings. | | I18DEV_API_URL | — | Custom API base URL (optional) | | I18DEV_PROJECT_ID | — | Project ID (optional) | | I18DEV_OUTPUT_DIR | — | Output directory for translations (optional) |

For most settings, values in your config file override environment variables (CLI flags still win). Use I18DEV_OUTPUT_DIR only when you want a machine-specific path without editing the project config.

.env file support

The CLI automatically loads .env, .env.local, .env.development, and .env.production if present.

Commands

init

Initialize i18dev configuration interactively.

i18dev init [options]

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -o, --output-dir <dir> | Output directory for translations | | -f, --format <format> | Output format: json, flat, or nested | | -y, --yes | Skip prompts and use defaults |

setup

Interactive setup agent for localization bootstrap. Scans your repo, detects frameworks, and generates prompts to set up i18n libraries.

i18dev setup [options]

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -y, --yes | Use defaults when init is triggered |

pull

Download translations from i18.dev to your local project.

i18dev pull [options]

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -o, --output-dir <dir> | Output directory | | -n, --namespace <name> | Pull specific namespace only | | -l, --language <code> | Pull specific language only | | -c, --confirmed-only | Only pull confirmed translations | | --clean | Clean output directory before pulling | | -v, --verbose | Verbose output |

Examples:

# Pull everything
i18dev pull

# Pull specific namespace
i18dev pull --namespace common

# Pull specific language
i18dev pull --language es

# Pull only confirmed, with clean slate
i18dev pull --confirmed-only --clean

push ✍️

Upload local translations to i18.dev. Requires I18DEV_PAT_TOKEN (Personal Access Token from Account Settings).

i18dev push [options]

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -i, --input-dir <dir> | Input directory | | -f, --file <path> | Push a specific file | | -n, --namespace <name> | Target namespace | | -l, --language <code> | Target language | | --overwrite | Overwrite existing translations | | --confirm | Auto-confirm imported translations | | -v, --verbose | Verbose output |

Examples:

# Push all translations
i18dev push

# Push a single file
i18dev push --file ./locales/en.json --namespace common

# Push with overwrite
i18dev push --overwrite

extract ✍️

Extract translatable strings from your source code. Requires I18DEV_PAT_TOKEN (Personal Access Token from Account Settings).

i18dev extract [options]

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -f, --files <pattern> | Glob pattern for source files (default: src/**/*.{ts,tsx,js,jsx}) | | -o, --output <path> | Output file for extracted keys (default: extracted-keys.json) | | -w, --write | Write modified code back to files | | -v, --verbose | Verbose output |

Examples:

# Extract from default pattern
i18dev extract

# Extract from specific files
i18dev extract --files "src/**/*.tsx"

# Extract and write changes to source
i18dev extract --write

namespace (alias: ns)

Manage namespaces.

namespace list

i18dev namespace list [options]

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -v, --verbose | Show namespace IDs |

namespace create <name> ✍️

i18dev namespace create <name> [options]

Requires I18DEV_PAT_TOKEN (Personal Access Token from Account Settings).

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -v, --verbose | Verbose output |

string (alias: str)

Manage translation strings (base strings).

string add <key> <value> ✍️

i18dev string add <key> <value> [options]

Requires I18DEV_PAT_TOKEN (Personal Access Token from Account Settings).

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -n, --namespace <name> | Namespace | | --notes <text> | Notes for translators | | --ai-instructions <text> | AI translation instructions | | -v, --verbose | Verbose output |

string update <key> ✍️

i18dev string update <key> [options]

Requires I18DEV_PAT_TOKEN (Personal Access Token from Account Settings).

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -n, --namespace <name> | Namespace | | --value <text> | New value | | --new-key <name> | Rename key | | --notes <text> | Update notes | | --ai-instructions <text> | Update AI instructions | | --confirmed | Mark as confirmed | | -v, --verbose | Verbose output |

string delete <key> ✍️

i18dev string delete <key> [options]

Requires I18DEV_PAT_TOKEN (Personal Access Token from Account Settings).

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key | | -n, --namespace <name> | Namespace | | -v, --verbose | Verbose output |

status

Show project status and translation progress.

i18dev status [options]

| Option | Description | |--------|-------------| | -k, --api-key <key> | Project API key |

Output Formats

json (default)

Saves translations as {lang}.json with nested namespaces:

locales/
├── en.json
├── es.json
└── fr.json

Example en.json:

{
  "common": {
    "welcome": "Welcome",
    "goodbye": "Goodbye"
  },
  "auth": {
    "login": "Login",
    "logout": "Logout"
  }
}

flat

Saves translations as {lang}/{namespace}.json with flat keys:

locales/
├── en/
│   ├── common.json
│   └── auth.json
├── es/
│   ├── common.json
│   └── auth.json

Example en/common.json:

{
  "welcome": "Welcome",
  "goodbye": "Goodbye"
}

nested

Saves translations as {lang}/{namespace}.json with nested structure:

locales/
├── en/
│   ├── common.json
│   └── auth.json

Example en/common.json:

{
  "welcome": "Welcome",
  "user": {
    "greeting": "Hello {{name}}"
  }
}

Programmatic API

You can also use the API client directly in your code:

import { I18DevApi } from "i18dev-cli";

const api = new I18DevApi({
  api_key: "your-project-api-key",
  api_url: "https://i18.dev", // optional
});

// Get project info
const project = await api.getProjectInfo();

// Get translations
const translations = await api.getTranslations({
  namespace: "common",
  language_code: "en",
});

// Create a string
await api.createBaseString({
  key: "welcome",
  value: "Welcome!",
  namespace: "common",
});

Full HTTP (v1) reference — routes, query/body parameters, and TypeScript request/response types — is in docs/api-reference.md.

CI/CD Integration

GitHub Actions

name: Sync Translations

on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - run: npm install -g i18dev-cli

      - name: Pull translations
        env:
          I18DEV_API_KEY: ${{ secrets.I18DEV_API_KEY }}  # Project API key
        run: i18dev pull

      - name: Commit changes
        run: |
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Action"
          git add locales/
          git diff --staged --quiet || git commit -m "Update translations"
          git push

Contributing

Contributor-focused guides (architecture, local setup, testing, CI/publish) live in the docs/ folder.

License

MIT