Skip to main content

Use case: a website in several languages

This guide walks through carrying a website's content into several languages with kapi (with the bowrain plugin) and, optionally, a Bowrain workspace for review. A language is one more coordinate: the same context that governs the source governs each target.

Overview​

  1. CLI: initialize a project and map your website's files
  2. CLI: converge with kapi up: AI drafting, content-memory recycling, and checks against your terms and voice
  3. CLI: review locally, or push to a workspace and review in the session
  4. CLI: keep the project in step with the workspace

Step 1: initialize the project​

Create a project in your website repository:

# Initialize the project with source and target locales
cd my-website/
kapi init --name "Website" --source en-US --targets fr-FR,de-DE,ja-JP

# Check project status and coverage
kapi status

# Configure content collections in kapi.yaml
# Edit to map your local files to formats and target paths

Example kapi.yaml:

version: v1
name: Website

defaults:
  source_language: en-US
  target_languages: [fr-FR, de-DE, ja-JP]
  voice: .kapi/voice.yaml
  terms_source: .kapi/terms.json

collections:
  - path: content/**/*.md
    format: markdown
    target: i18n/{lang}/{path}/{filename}
  - path: src/locales/**/*.json
    format: json

Step 2: converge with kapi up​

kapi up is the convergence verb: it brings every target language up to date against the current source, drafting with AI, recycling from content memory, and running the checks, and is safe to re-run whenever the source changes.

# Bring every target language up to date against the source
kapi up

For finer control, run a single tool with kapi exec, or a custom flow with kapi run:

# Run one tool over the project's collections
kapi exec translate

# Or run a custom flow declared in .kapi/flows/translate-website.yaml
kapi run translate-website

A custom flow composes tools into a pipeline. .kapi/flows/translate-website.yaml:

name: translate-website
description: Draft website content with AI and check it
steps:
  - tool: recycle
  - tool: translate
    config:
      provider: anthropic
      model: claude-sonnet-5
  - tool: term-check
  - tool: qa

Tools and flows​

kapi tools and flows are composable pipelines that run on your local files:

  • kapi exec translate: draft with an AI provider
  • kapi exec recycle: pre-fill targets from content memory
  • kapi exec qa: rule-based quality checks (whitespace, punctuation, placeholders)
  • kapi exec term-check: check the terms in force at each block's point
  • kapi run <flow>: execute a composed or custom multi-tool flow

Tools and flows automatically process all files matching your recipe's collections:.

Step 3: review​

Locally, kapi status --review lists the translated units awaiting a decision, and kapi apply records one; kapi commit publishes the decisions into the committed record under .kapi/state/.

For a reviewer who works in a browser, connect the project to a workspace (step 4) and use the review session: source and draft side by side, the checks and the terms inline, bulk approval of everything that passes, and a per-locale ship state that says what can go out today.

Using terms​

  1. Import terms (TBX, CSV, JSON) with kapi terms import; they land in the project's terms store
  2. Bind the store with defaults.terms_source so every run and check reads it
  3. Add term-check to your flow to check each target against the terms in force
  4. In a workspace, the editor's context panel shows matched terms per block

Step 4: sync with a Bowrain workspace (optional)​

For team collaboration, connect your project to a Bowrain workspace:

# Connect to a workspace
kapi init --server https://app.bowrain.cloud --project abc123

# Check standing
kapi status

# Send local changes up
kapi push

# Fetch results and reviewers' decisions
kapi pull

The push/pull workflow is similar to git:

Gitkapi
git statuskapi status
git diffkapi diff
git pullkapi pull
git pushkapi push

kapi declares its tree on every push, so only changed blocks transfer over the network. On a connected project, kapi up runs the loop on the server and does push, catch up and pull in one command.

Tips​

  • Initialize projects with kapi init to write a kapi.yaml recipe and a committed .kapi/ directory
  • Bind a voice profile and a terms store in defaults: so drafts and checks read the same context
  • Define custom flows in .kapi/flows/ for your specific workflow
  • Put recycle before translate to reuse approved wording before spending credits
  • Run kapi pseudo-translate first to identify potential UI truncation issues
  • Use local automations to run the checks before pushing to a workspace
  • Commit kapi.yaml and .kapi/ to git; the context graph belongs in review, and only .kapi/work/ is gitignored
  • Check kapi status before pushing to see what changed