colibri/docs/guide/localization/index.md

title	description
Documentation Localization	Astro/Starlight-native localized docs for Clawdie, with translations versioned in git.

Documentation Localization

Clawdie localizes documentation natively in Astro/Starlight: every locale is plain markdown versioned in the git repo, and Starlight's built-in i18n routing renders one static site with per-locale pages. There is no external translation service in the live path.

Source of truth

All docs — source and translations — live under docs/guide/:

• English is the default locale and lives at the tree root, e.g. docs/guide/operate/terminal-capture.md
• each other locale mirrors that structure under a BCP-47 directory, e.g. docs/guide/sl/operate/terminal-capture.md (Slovenian)

The repo is the editorial source of truth for every language.

docs/guide/
├── operate/terminal-capture.md         # en (default)
├── architecture/control-plane-bridge.md
└── sl/                                 # Slovenian mirror
    ├── operate/terminal-capture.md
    └── architecture/control-plane-bridge.md

Build & deploy

The shared Astro/Starlight docs project reads docs/guide/, applies Starlight locale routing, and builds per-locale static output. It is deployed through the cms jail:

• repo source: bootstrap/cms/clawdie-docs/
• cms jail runtime path: /usr/home/<tenant>/<tenant>-docs/

cd /usr/home/<tenant>/<tenant>-docs
npm run deploy

That single deploy path runs the content sync + Astro build for all locales — localization has no separate deploy path; it rides the normal docs build. For the complete operator workflow, see Docs and tenant-site publishing.

Adding or updating a translation

1. Copy the English page to the locale mirror (same relative path under docs/guide/<lang>/).
2. Translate the body, and the title / description frontmatter.
3. Commit it to the repo.
4. Deploy via the cms jail (npm run deploy).

See How the pipeline works and Setup instructions for the details.

Future plan: Crowdin

Hand-editing locale markdown is fine while the translated surface is small. When translation volume outgrows that, Crowdin can be reintroduced to manage translation strings — pushing English source up and pulling completed translations back into the same docs/guide/<lang>/ layout, with no change to how Astro builds or deploys. Crowdin is not wired up today; it is a future scaling option, not a current dependency.

Pages in this section

• How the pipeline works
• Setup instructions
• Troubleshooting