Skip to main content

Use Case: Translating a Website

This guide walks through a complete workflow for translating website content using kapi (with the bowrain plugin) and the Bowrain web editor.

Overview​

  1. CLI: Initialize a Bowrain project and configure file mappings
  2. CLI: Run translation flows (AI, content memory, QA)
  3. Bowrain: Open local project in visual editor for manual review
  4. CLI: Push to Bowrain Server for team collaboration (optional)

Step 1: Initialize Project​

Create a Bowrain project in your website repository:

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

# Check content stats for cost estimation
kapi stats content/**/*.md

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

Example kapi.yaml:

version: v1
name: Website Translation

defaults:
  source_language: en-US
  target_languages: [fr-FR, de-DE, ja-JP]

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

Step 2: Run Translation Tools and Flows​

Execute translation workflows from the CLI:

# List available tools and flows
kapi tools
kapi flows

# Run AI translation (top-level tool command)
kapi translate

# Or create a custom flow with QA checks
# .kapi/flows/translate-website.yaml:
# name: translate-website
# description: Translate website content with AI and QA
# steps:
#   - tool: translate
#     config:
#       provider: anthropic
#       model: claude-sonnet-4.5
#   - tool: qa
#   - tool: term-enforce

kapi run translate-website

Tools and Flows​

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

  • kapi translate: Use LLMs (Anthropic, OpenAI, Ollama) for machine translation
  • kapi exec recycle: Pre-fill translations from content memory
  • kapi exec qa: Rule-based quality checks (whitespace, punctuation, placeholders)
  • kapi run <flow>: Execute a composed or custom multi-tool flow

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

Step 3: Review in Bowrain (Optional)​

For visual review and manual edits, open your project in the Bowrain desktop app or web UI.

# Launch Bowrain desktop app (if installed)
open -a Bowrain .

Editor Views​

Bowrain's editor offers two views for different translation tasks:

ViewBest For
VisualIn-context translation — an inline card over a live preview
TableOverview, scanning, and batch operations across many blocks

Using Terminology​

  1. Import terms (TBX, CSV, JSON) — they are stored in the project terms store
  2. Add term-lookup to your flow to show terminology suggestions
  3. Add term-enforce to validate required terms are used correctly
  4. The Context panel in Bowrain shows matched terms per block

Step 4: Sync with Bowrain Server (Optional)​

For team collaboration, connect your project to a Bowrain Server instance:

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

# Check sync status
kapi status

# Push translations to server
kapi push

# Pull translations from teammates
kapi pull

The push/pull workflow is similar to git:

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

kapi uses content-addressed blocks for efficient incremental sync — only changed blocks transfer over the network.

Tips​

  • Initialize projects with kapi init to write a kapi.yaml recipe and .kapi/ state directory
  • Define custom flows in .kapi/flows/ for your specific translation workflow
  • Use kapi exec recycle to auto-fill translations from content memory
  • Import terminology into the project terms store and add term-lookup to your flow
  • Run kapi pseudo-translate first to identify potential UI truncation issues
  • Use pre-push hooks to enforce quality gates before pushing to server
  • Commit kapi.yaml to git; the whole .kapi/ state directory is gitignored by default
  • Check kapi status before pushing to see what changed