Skip to main content

Use case: a website in several languages

Carry a website's content into several languages from its repository with kapi and the bowrain plugin, and, if you want reviewers in the browser, review the drafts in a Bowrain workspace. A language is one more coordinate, so the context that governs the source governs each target too.

Overview​

  1. Initialize a project and map your website's files.
  2. Catch up with kapi up: AI drafting, content-memory reuse, and checks against your terms and voice profile.
  3. Review locally, or push to a workspace and review in the session.
  4. 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:
    profile: acme-docs

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

Step 2: catch up with kapi up​

kapi up brings every target language up to date with the current source. It reuses content memory, drafts the rest with AI and runs the checks. Re-run it 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 flows/translate-website.yaml
kapi run translate-website

A custom flow composes tools into a pipeline. flows/translate-website.yaml, with flows_dir: flows in kapi.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 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 process every file that matches your recipe's collections:.

Step 3: review​

Locally, kapi status --review lists the translated blocks awaiting a decision, and kapi apply records one in the project's decision ledger, where every checkout reads it.

For a reviewer who works in a browser or in the desktop app, connect the project to a workspace (step 4) and use the review session. It shows source and draft side by side, with the checks and the terms inline. A reviewer can approve everything that passes in one action, and the per-locale ship state shows 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. Every run and check reads the project's terms store with nothing bound; kapi store import reads a terms bundle into 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 the checkout's .kapi/ cache
  • Bind a voice profile and a terms store in defaults: so drafts and checks read the same context
  • Define custom flows in the directory flows_dir: names, 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 to git. kapi init keeps .kapi/, this checkout's cache, out of git
  • Check kapi status before pushing to see what changed