# CLI

Source: https://verbaly.dev/docs/reference/cli

The `verbaly` command lives in `@verbaly/compiler`. Add it to your dev dependencies so `npx verbaly` resolves: package managers link a command only for a package you installed yourself, and the plugins depend on the compiler without installing it for you.

## Commands

14 commands, in the order the cycle uses them. Each one links to its section.

**1. Set up**

- [`init`](#init): Scaffolds the config and your catalogs, and names the plugin to wire.
- [`doctor`](#doctor): Checks the whole setup and prints the fix for each finding.
- [`wrap`](#wrap): Finds hardcoded text in your JSX and wraps it for you.
- [`migrate`](#migrate): Ports catalogs from another i18n library, and flags what it will not guess.

**2. Write**

- [`extract`](#extract): Syncs your catalogs and types with your source.
- [`typegen`](#typegen): Writes the TypeScript types alone, for CI before tsc.
- [`status`](#status): Coverage per language at a glance. It never fails.
- [`pseudo`](#pseudo): A fake language that exposes hardcoded text and clipped layouts.

**3. Translate**

- [`translate`](#translate): Fills missing translations with a provider, marked as drafts.
- [`review`](#review): Lists drafts and outdated translations, each with its source text, for a person to approve.
- [`export`](#translators): Files for translators: XLIFF, CSV, PO, Android or iOS.
- [`import`](#translators): Brings translated files back, validated before they land.

**4. Ship**

- [`check`](#gate): The CI gate: fails on missing keys, unknown keys and broken translations.
- [`render`](#render): Writes your static site in every language.

## Scaffolding

`verbaly init` sets a project up in one command. You get a typed config (`.ts` if you have a `tsconfig`, `.mjs` otherwise) and your catalogs: the source one, plus one for every language you pass in `--locales`. Then it tells you what to wire next. Astro, Nuxt, Next.js, SvelteKit and Vite each have their own integration; any other bundler uses `@verbaly/unplugin`. On Vite and every other bundler, the install line also names the package for the UI library you use: `@verbaly/react`, `@verbaly/vue` or `@verbaly/svelte`.

```console
$ npx verbaly init --locales es,pt
created: verbaly.config.ts, locales/en.json, locales/es.json, locales/pt.json
detected: vite
  next steps: 1. pnpm add verbaly @verbaly/react @verbaly/vite
  2. add verbaly() to the plugins in vite.config
```

Re-running is safe: an existing config or catalog is reported as “kept” and left byte-identical.

## Health check

`verbaly doctor` is `init`'s sibling for projects already running: it inspects the whole setup and reports every finding with the exact command that fixes it. Green means healthy; problems exit `1`.

```console
$ npx verbaly doctor
Passed config: verbaly.config.ts found
Passed catalogs: 3 locales (en, es, pt) in locales/
Passed plugin: @verbaly/vite installed for vite
Warning types: src/verbaly.d.ts is stale fix: run npx verbaly typegen
Warning orphans: 2 catalog keys are no longer referenced (old.title, hero.cta) fix: run npx verbaly extract --prune to drop them
Warning outdated: 1 translation written for an older source text (es: hero.title) fix: update them, or keep them with npx verbaly review --approve
Error imports: 1 file imports t from a verbaly package, which never exports it (src/app.ts) fix: t comes from your instance (React: const t = useT()) or from verbaly/app
Error translations: 1 broken translation (es): present but not rendering what the source renders fix: run npx verbaly check to read what each one lost
```

One command to answer “why isn’t this translating?” It looks at four things.

- **Your setup:** the config, the catalogs and whether every language code is one a browser can read. Also whether the URL mode matches the URLs `render` writes, whether the right integration for your framework is installed, and whether the generated types are up to date where your framework reads them, `tsconfig.json` included in Next.js.
- **Your translations:** the missing ones, the broken ones, the outdated ones, the warnings, keys only a translation has, keys written with two texts, and keys no line of your code asks for any more.
- **What your build cannot see:** `t` imported from a verbaly package, which no bundler can resolve, and a `t` under another name, whose text is never extracted. Also a file outside `include` that writes `` t`…` ``, which no build translates, and a message that kept a plural or format block as plain text, with the spelling that works.
- **Any file it could not read**, as a warning. A source file's text is not extracted, but the file may still build fine in your project. A merge conflict in `verbaly.lock` is a warning too: both sides are read, and `extract` writes them into the file for you to commit with the merge.

A clean report means `check` passes too. `doctor` fails on everything `check` fails on, plus setup faults like that import, and never on something that builds and renders fine.

## Wrapping hardcoded text

`verbaly wrap` finds hardcoded text in your JSX and wraps it in `` t`…` `` for you. It reports first, and `--write` applies. Anything ambiguous is listed for a human instead of guessed, and a file where `t` is not available is left untouched and reported, so the project always still compiles.

```sh
npx verbaly wrap           # report what it would wrap
npx verbaly wrap --write   # apply it
```

## Porting from another library

`verbaly migrate` ports the catalogs you already have. Your file keeps its shape, nested or flat, and the only thing it must rewrite is the interpolation: `{{name}}` becomes `{name}`, because a doubled brace is how Verbaly writes a literal one. It reports first, and `--write` applies.

```sh
npx verbaly migrate             # report what it would port
npx verbaly migrate --write     # apply it
npx verbaly migrate --plurals --write   # and merge _one/_other
```

`--plurals` is the optional half: it merges `_one` and `_other` into one message with variants, which is what buys automatic plural selection, and inside it the count prints itself already localized. It knows the older `key` + `key_plural` spelling too. Without the flag those keys keep working exactly as they are.

What it will not guess is listed instead: an i18next format inside the braces, a `{{- unescaped}}` value, a `$t()` nesting, and a merge that would overwrite a key you already use. Those messages are left exactly as they were, and every run lists the ones still waiting.

## Extraction

`verbaly extract` scans your sources (every JavaScript and TypeScript file, `.jsx`, `.tsx`, `.mjs`, `.cjs`, `.mts` and `.cts` included, plus `.svelte`, `.vue` and `.astro`), writes new messages to the source catalog, adds `""` placeholders to the rest and regenerates the types. It names any file it could not parse instead of stopping on it. Every source text that followed your code gets one line with the text it had before, so an edit you made in the code reads as a change and one made in the catalog shows what it undid. Then it warns, with file and line, about what would otherwise go unnoticed: a key written with two texts, a `t` under another name, a message that kept a plural or format block as literal text, and a value a translator would see as `{_0}`. With `--watch`, each warning is said once, and again only if it comes back.

```sh
npx verbaly extract             # sync catalogs + types
npx verbaly extract --prune     # and drop keys nothing references
npx verbaly extract --dry-run   # say what it would change, write nothing
```

## Type generation

`verbaly typegen` writes the TypeScript types of your messages and nothing else, from the text your build ships, where your framework reads them: `src/verbaly.d.ts` in a Vite or SvelteKit app, `.verbaly/types.d.ts` in Next.js, and Astro's and Nuxt's own types folder. `extract`, the dev servers and the build write the same file, so you only need it where none of them ran: a fresh clone, or a CI job about to run `tsc`.

```sh
npx verbaly typegen && tsc --noEmit   # a fresh clone, or CI
```

## Coverage

`verbaly status` shows translation coverage per language at a glance (`es: 45/48 translated`), how many machine translations still wait for review, how many are broken and how many were written for an older source text. It is informational only and never fails; `--json` gives the same numbers to badges and tooling.

```sh
npx verbaly status          # es: 45/48 translated
npx verbaly status --json   # the same numbers, for badges and tooling
```

## Pseudo-localization

`verbaly pseudo` fills a QA catalog (`en-XA` by default) from the text your build ships in the source language: accented letters, `⟦…⟧` markers and ~33% padding. Text that stays clean in the pseudo build is hardcoded; layouts that clip reveal themselves before a real translation does.

```sh
npx verbaly pseudo                 # locales/en-XA.json
# "Hello {name}" → "⟦Ĥéĺĺó {name} ~⟧"
```

Params, variant blocks and named tags survive verbatim, guaranteed by the same structural validation as `translate`. Re-running regenerates the whole catalog.

## Machine translation

`verbaly translate` closes the loop: write → `extract` → `translate` → `check` green. The default provider uses Claude (`@anthropic-ai/sdk` as an optional peer + `ANTHROPIC_API_KEY`). It sends batches of 20 per request, and each one tells the model which source files the text lives in, so it translates with context. Any current Claude model works through `translate.model` or `--model`, and a batch the model declines goes to a fallback model instead of coming back untranslated.

```sh
npx verbaly translate --dry-run        # list what's missing, write nothing
npx verbaly translate --locales es,pt  # fill only these locales
npx verbaly translate --model claude-opus-4-8  # override the default (claude-sonnet-5-5)
```

Every translation is checked: placeholders and tags must survive verbatim. If one doesn't, the translation is rejected and the entry stays `""`, so `check` keeps flagging it until it's fixed.

No lock-in: plug your own provider in `verbaly.config.ts`. In TypeScript, `TranslateProvider` types it for you, and `origins` tells you which source files each text appears in, so you can translate it for where it is used:

```ts title="verbaly.config.ts"
import type { TranslateProvider } from '@verbaly/compiler';

const provider: TranslateProvider = async ({ sourceLocale, targetLocale, messages, origins }) => ({
  /* key → translation */
});

export default { translate: { provider } };
```

## Review what is waiting

Machine output is a draft, not reviewed work. `translate` records everything it writes in `verbaly.lock`, next to your config (committed with your catalogs, never edited by hand), and `verbaly review` closes the loop: read the drafts, then approve them. The same file remembers which source text each translation was written for, from the moment it is written, so when you change a text, its translations wait in `review` too, as outdated: update them, or approve them if they still hold. Each one is listed with the text that ships next to its translation, so you can judge it right there, and `--approve` followed by keys accepts only those.

```sh
npx verbaly review               # each one with its source text and its translation
npx verbaly review hero.title --approve   # accept only the keys you name
npx verbaly review --approve     # accept everything after reading
npx verbaly check --drafts       # CI gate: fail while drafts remain
npx verbaly check --outdated     # and while a translation is older than its text
```

Want merges blocked until a human signs off? Add `--drafts` to the `check` in your CI: it keeps failing while unreviewed machine translations remain, and `--outdated` does the same for translations written for an older source text. A translator file brought in with `import` counts as review on its own.

## Translators & TMS

Humans in the loop? `verbaly export` writes translator-ready XLIFF 2.0, CSV or gettext PO files per language and `verbaly import` brings them back, structure-validated with the same gate as `translate`. The full flow, TMS options included, lives in [Work with translators](https://verbaly.dev/docs/guide/translators.md).

`verbaly import` validates every entry and rejects and reports the broken ones. PO entries marked fuzzy count as untranslated, and imported keys stop counting as unreviewed drafts, unless you pass `--draft` for a file nobody has read yet. A file's language is read as one of yours, so gettext's `pt_BR` fills your `pt-BR`. A file for a new language starts its catalog under its proper code, unless your config lists its `locales`: then a language outside the list is skipped with a warning and exit code `1`, because your app would never load it.

Export also writes native mobile resources: `--format android-xml` for Android's `res/` layout and `--format ios-strings` for Xcode. Untranslated keys are left out so the app falls back to your source language (`--missing` applies only to the translator formats). Every format writes to `verbaly-export/` unless you point `--out` elsewhere.

## What the gate checks

`check` asks four questions. Is every message translated? Does every key the code writes exist? Does each key have one text, so no place shows words written for another? And can each translation render what the source renders? A filled-in translation is not automatically a working one, so these fail `check` too, wherever they came from: a translator, a machine or a hand edit. Every build lists the same problems and finishes, so run `check` in CI.

| The translation | Why it fails |
| --- | --- |
| lost a `{param}`, or renamed it | the value never reaches the text |
| lost an `<em>`, or gained one | the emphasis or the link marker is gone |
| turned a plural block into plain text | one wording for every count |
| has a plural block with no `other` case | every count it does not list renders *empty* |

Some findings are warnings instead: they print and the exit code stays `0`, because the text still renders.

- A plural set missing forms the language needs: Polish and Arabic ask for more than English.
- A case like `=0` that the source had and the translation dropped, so that count falls back to `other`.
- A key only a translation has. Where your code reads it, the source language shows the key itself; where nothing does, it only adds weight, which `extract --prune` removes.
- A text in your source catalog that differs from the one in your code: the code's text is the one that ships.
- A translation written for an older source text, read against the text in your code. Add `--outdated` to `check` to make it fail, and it is listed with the failures.

A build runs the same gate, and when it finds warnings it prints one line that says how many, then passes.

Whatever fails, the report ends by telling you how to fix it: fill a message that has no translation yet, correct a key no catalog has, give each text its own key where one key has two, or repair a broken message.

## CI example

```yaml title=".github/workflows/ci.yml"
- run: pnpm install
- run: npx verbaly check --reporter github   # each finding becomes a PR annotation
- run: pnpm build
```

With `--reporter github`, every finding shows up as an annotation on the pull request, on the file and line where the text lives. Errors arrive as errors and warnings as warnings, so a warning never turns the job red. Without it you get the plain list, with the same exit code.

## Static rendering (SSG)

`verbaly render` is what removes the flash of untranslated text on a static site. It walks your built HTML and fills in every `data-verbaly` element, once *per language*, using the real runtime: plurals, `Intl` formatting, `data-verbaly-args`, attributes and allowed rich text. Inside a language, links to pages that language also has keep its prefix, so whoever arrives stays there. Getting them there is `--redirect`, below.

```sh
npx vite build              # or astro build, eleventy, …
npx verbaly render          # dist/index.html filled in the source locale
                            # dist/es/index.html, dist/pt/… for the rest
npx verbaly render --site out --locales es  # custom dir / locale filter
```

- Each language gets `<html lang>` and `<html dir>` set (right-to-left languages mirror correctly); the source language is filled in place, the rest mirror to `dist/<locale>/…`. A folder named like the source language, such as `dist/en/` when you write in English, is never mirrored, and the run says so.
- The `data-verbaly` attributes stay in the output, so client-side language switching keeps working on top of the pre-rendered page.
- Messages are HTML-escaped (never injected), missing keys are reported and left untouched, running it again changes nothing, and translated attributes pass the same guards as the runtime: unsafe URLs blocked, `style`/`srcdoc` never written.
- Named links: set `render.links` in `verbaly.config.*` (or `data-verbaly-links` per element) and rich messages pre-render real `<a href>` elements, attribute-escaped, with `javascript:` blocked.
- Multi-language SEO: set `render.baseUrl` (or pass `--base-url`) and every page gets reciprocal `hreflang` alternates; `--sitemap` writes an i18n sitemap, `--clean` drops stale language pages.
- The sitemap lists only pages a search engine should index: one that redirects, or carries `noindex`, is left out. Every page is still translated and published, so a visitor who lands on one gets it in their language. Leave more out by name with `render.exclude`, a list of globs against the path inside your build directory.
- Using a different data attribute? `--attribute` points the renderer at it, the same way the runtime takes one, so both sides stay in step.
- Self-canonical mirrors: `rel="canonical"` and `og:url` are rewritten to each language's own URL, because a cross-language canonical would make search engines ignore the hreflang set.
- Send a visitor to their language. `--redirect` (or `render.redirect`) puts a small script at the top of your home page that moves them before anything is drawn. It only fires there: a search engine asking for a deep page has to get that page, not a detour. A saved choice always wins, the query and the hash come along, and it can never loop, because it does nothing once you are already in that language. Add `{ on: 'all' }` if you want every page of your source language to route too, and `storageKey` to point it at the key you save the choice under.
- Site served from a subfolder? `--base /app` (or `render.base`) tells the renderer where the site starts, so links inside each language read `/app/es/docs` instead of pointing nowhere. The same option exists on `localeFromPath` and `localePath` so the runtime agrees with the build.

## Flags

| Flag | Default | Description |
| --- | --- | --- |
| --root | cwd | Project root |
| --dir | locales | Catalogs directory |
| --source | en | Source language |
| --locales | from files | Run on these languages only, the source always included. One the project does not have is an error (init: the ones to create) |
| --prune | off | Drop keys no longer referenced (extract only) |
| --watch | off | Re-extracts as source files change: live extraction for webpack, Rspack and Rollup setups (extract only) |
| --locale | en-XA | Pseudo-language id (pseudo only) |
| --site | dist | Built site directory (render only) |
| --base | site root | Subpath the site is served under (render only) |
| --redirect | off | Send a visitor on the home page to their language (render only) |

> **Prune and dynamic keys**
>
> `--prune` only sees statically analyzable usage. If you build keys at runtime (`t(someVar)`), keep prune off or those keys will be removed. `extract --prune --dry-run` previews the removals without writing anything. While any source file does not parse, prune removes nothing and names the file, because that file may be the one reading the keys.

Flags are validated per command: a flag that belongs to another command exits with an actionable error instead of being silently ignored: `translate --locale es` tells you it means `--locales`. A language is checked the same way: `review --locale ess` exits with an error that lists the languages your project has and says how to start a new one.

## Config file

Flags win over `verbaly.config.{js,mjs,ts,mts,json}` at the project root. Every option, with its default, lives in [Configuration](https://verbaly.dev/docs/reference/config.md).

## Coding agents

Your coding agent can run this same cycle without touching the shell, through the `@verbaly/mcp` server. That channel has a page of its own. [Coding agents](https://verbaly.dev/docs/guide/agents.md) covers the server, its tools and resources, the installable Agent Skill and the `llms.txt` index this site serves.
