Overview

A command-line interface for syncing translations between your repo and the api18n dashboard.

@api18n/cli is the bridge between the api18n dashboard and your source tree. It pulls translations into local JSON files in the format next-intl / i18next / react-intl already use, and pushes local edits back to the dashboard as proposals — never silent overwrites.

When to reach for the CLI

Use the CLI when you want any of:

Translations in source control. Your messages/{locale}.json files live in the repo, get reviewed in PRs, and ship as part of your normal deploy.
Type-safe t() calls. Every pull writes a messages.d.ts that augments the @api18n/react SDK's Messages interface — typos in t('button.cancl') fail at compile time.
Programmatic edits. Bots, scripts, or next-intl-style fixer tools can edit messages/en.json and api18n push opens a proposal for a human to review.

If you only ever edit strings inside the dashboard, you don't need the CLI — your translators can manage everything there. The CLI is for teams where some edits happen in code.

Quickstart

cd your-app
npx @api18n/cli init             # creates api18n.config.ts
npx api18n login                 # opens the dashboard, paste a PAT
npx api18n pull                  # writes messages/{locale}.json + types

Then commit the new files and you're done. Continue to Installation for the full walk-through, or jump straight to Commands for the reference.

How it fits with the rest of api18n

   Translator         Designer             Developer
       │                  │                    │
       ▼                  ▼                    ▼
  ┌─────────────────────────────────────────────────┐
  │                  api18n dashboard               │
  └─────────────────────────────────────────────────┘
       ▲                  ▲                    ▲
       │ approves         │ pulls (plugin)     │ pulls / pushes
       │ proposals        ▼                    ▼
       │             ┌────────────┐       ┌────────────┐
       └─────────────│ Figma file │       │  @api18n/  │
                     │ (Variables)│       │    cli     │
                     └────────────┘       └────────────┘
                                                 │
                                                 ▼
                                          messages/en.json
                                          messages/pt.json
                                          messages.d.ts ──► @api18n/react

The CLI is the only surface that writes to the database without going through human review. Every api18n push creates a proposal that a dashboard admin approves or rejects.

PreviousConfiguration NextInstallation