Skip to main content

Using kapi with Claude

You keep building with Claude Code as usual. kapi gives Claude a structured, repeatable way to handle localization and brand — so making your product multilingual and keeping its copy on-voice is an engineering pipeline, not a one-off translation. kapi extracts the text from your code and documents, round-trips it back faithfully (structure, formatting, and placeholders intact), reuses translation memory, and enforces your glossary and brand voice — the same way every time, and gate-able in CI.

You install it once. After that you ask Claude in plain language; it decides when to call kapi.

note

kapi also speaks MCP, for assistants that prefer structured tools over a CLI. This page follows the skill (CLI) path — the two work together.

1. Plug kapi into Claude​

Install the skill into a project, or into your user account for every project:

kapi skills install                 # ./.claude/skills/kapi/   (this project)
kapi skills install --target user   # ~/.claude/skills/kapi/   (every project)

Claude Code discovers the skill and invokes it when a task fits its description — you never call it by name. It's one router that loads the relevant section on demand (progressive disclosure), so it covers the whole workflow without crowding the context window.

The only prerequisite is the kapi CLI on your PATH (kapi version — see installation). The rule-based checks need no credential; for provider-backed translation, add one with kapi credentials add (or let the assistant translate within kapi's guardrails — more below).

2. Ship your app in another language​

You're taking a React or Next.js app to a new market. The English text in your JSX stays as it is — no message IDs, no t("...") wrappers. You just ask:

We're launching in Japan. Set up i18n with kapi-react and add a Japanese translation.

Claude adopts the zero-wrapper kapi-react stack and runs a structured pipeline — the same steps every time the UI changes:

npm run extract                                # kapi-react collects the UI strings from the JSX → i18n/
kapi pseudo-translate i18n/  # readiness check: surfaces anything not localizable yet
kapi ai-translate i18n/ --target-lang ja       # translate; interpolation placeholders preserved
npm run compile                                # → public/translations/ja.json (loaded at runtime)

The strings stay in your components as plain JSX; kapi handles the build-time extraction and the round-trip into a runtime dictionary, carrying placeholders like {userName} through untouched. The note data in your components is left alone — only the UI copy is translated. Add the next locale by re-running the same pipeline.

3. Translate documents, structure intact​

Next, a launch one-pager — a Word document. Claude drives kapi for a structured, format-faithful round-trip: kapi parses the .docx, translates the text, and writes it back with the headings, lists, bold runs, and inline fields preserved — applying your glossary and translation memory along the way.

Translate announcement.docx into Japanese.

kapi ai-translate announcement.docx --target-lang ja -o announcement.ja.docx

Only the text changes; the document's structure comes through intact. The same one command works across the office formats, mobile catalogs (Apple .xcstrings, Android strings.xml, Flutter .arb), Markdown, and more — native, offline readers, no plugin. For vendor or human translation, swap ai-translate for a bilingual kapi extract → kapi merge round-trip; see Bilingual Workflow.

4. Keep terminology and brand consistent — automatically​

Bind the things that shouldn't drift between requests once, in your .kapi project:

# myapp.kapi
defaults:
  source_language: en
  target_languages: [ja, fr, de]
  brand_voice:
    profile_file: brand.yaml    # the voice to write in

Now every translation uses the glossary's terms and on-brand checks know your voice — with no flags in the prompt.

The checks aren't something you watch Claude type. They run on their own:

  • In the loop — the Claude Code plugin registers a Stop hook (kapi hook stop) that runs the project's gates when Claude tries to finish. If terminology, placeholders, or brand voice are off, it hands the findings back and keeps Claude working until they pass.

  • In CI — the same gate guards your pull requests:

    kapi verify --json                              # terminology + placeholder QA + brand voice, in one gate
    kapi brand check RELEASE.md --min-score 90 --json

    The exit code distinguishes a failed gate from a crash, so a CI step can tell them apart.

This is the half the videos don't show — by design. Producing the translation is the conversation; verifying it should just happen.

Where to go next​