Add languages

Add a target language, and kapi keeps it caught up with the source: it reuses earlier translations, translates the rest, and holds back for review what needs a person. A language that is behind is pending work and never breaks a build.

In Kapi Desktop you add a language with Languages + and click Bring up to date. On the command line you declare it in the recipe and run kapi up. An assistant can do either for you.

In the installed kapi, declaring a target language in the recipe also adds the language commands (translate, pseudo-translate, memory) to kapi --help. Before that, kapi help languages lists them.

Desktop

1. Add the locales. In Project Settings, add the target languages you translate into (for example fr, de). On a project in one language, Languages + in the sidebar opens the same choice, and once you save the first target it becomes Languages, with Review beside it.

2. Bring up to date. Back on the project view, the coverage panel shows one row per locale against the ship gate. Plan… previews the pending work first: content-memory leverage, remaining AI work, a token estimate, nothing written. Then click Bring up to date; kapi runs the default flow over every locale that is short of its gate, looping until each scope ships or a gate holds it back for a person.
3. Review. Click a ship-gate cell to open the Review queue for that locale: inspect each translation, edit if needed, approve or reject. Approvals raise the approved coverage that an { established: … } gate measures; the recipe spells the approved rung established.

▶

Walkthrough videoPending recording

Adding two target locales in Project Settings, pressing Bring up to date, watching coverage climb, and opening the Review queue from a gate cell.

View scene script ↗

Agent (Claude)

Ask for the outcome:

Add French and German to this project and bring both up to date.

Claude adds target_languages to the recipe, runs kapi up, reads kapi status for what is waiting for a person, and goes through the review worklist with you; you approve, it records the decisions with kapi apply. See Use with Claude.

CLI

Declare the locales in the recipe (or pass --target-locale at kapi init time):

kapi.yaml

defaults:
  source_language: en
  target_languages: [fr, de]
collections:
  - path: "src/locales/en/*.json"
    target: "src/locales/{lang}"

The target: says where a translated file goes. kapi add writes it for you (kapi add "src/locales/en/*.json" --target "src/locales/{lang}"), including on a pattern kapi init already added without one. It refuses a target that lands back inside the pattern it comes from, which would make the collection re-track its own output as source, and a pattern whose entry already declares a different target, which you change in the recipe.

A file belongs to the first entry in the recipe whose pattern matches it, so a target applies to the files its entry claims. kapi add counts those, names each other file with the entry that claims it, and refuses a pattern whose every file an earlier entry claims.

Then catch up, inspect, and gate:

kapi up                  # run the default flow; stop where a gate holds content back
kapi status              # per-locale coverage and ship-gate standing (never fails)
kapi status --review     # the worklist: translated blocks awaiting a person
kapi check --ship        # enforce the gates: the pre-release bar, exit 3 when unmet

kapi up needs a translation provider for LLM translation; see Choose a translation model. Approve reviewed blocks with a decide operation through kapi apply; see Review & approve.

How the gate works

Each translation climbs a ladder (draft, translated, approved). A ship gate is a set of coverage thresholds over that ladder, such as { translated: 100, established: 80 }.

kapi up produces translations, review promotes them, and the ship gate releases a language.

The kapi loop explains the model.

Next

• Translate with your AI: the translation loop in depth.
• Ship gates & CI: run kapi check --ship on every PR.
• Review & approve: the human half of the loop.