colibri/docs/guide/localization/how-it-works.md

title	description
How the Pipeline Works	Step-by-step flow from locale markdown in git to a Starlight build and cms-jail deploy.

How the Pipeline Works

Localization is Astro/Starlight-native: translations are markdown in git, and the normal docs build renders every locale. No external service sits in the live path.

Stage 1: locale markdown in git

All content lives under docs/guide/:

• English (default locale) at the tree root, e.g. docs/guide/operate/terminal-capture.md
• each other locale mirrored under a BCP-47 directory, e.g. docs/guide/sl/operate/terminal-capture.md

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

Stage 2: add or update a translation

Copy the English page to the matching path under the locale directory, then translate the body and the title / description frontmatter:

mkdir -p docs/guide/sl/operate
cp docs/guide/operate/terminal-capture.md docs/guide/sl/operate/terminal-capture.md
# translate the copy, then commit it

Keep the relative path identical to the English page — Starlight pairs a translation with its source by matching the path under the locale directory.

Stage 3: sync docs into the Astro project

Inside the cms jail docs project:

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

The deploy flow copies the canonical docs content from the host repo into the Astro docs content tree before the build.

Stage 4: build localized static output

The same deploy flow runs:

astro build

Astro/Starlight then:

• reads the synchronized docs content
• applies locale routing from the directory layout
• renders static HTML for each locale present

Stage 5: publish through the cms webroot

The built output is deployed into the cms jail webroot and served through the configured docs surface.

For operators, the important point is:

• localization does not have its own deploy path
• it rides on the normal docs deployment path; building the docs builds every locale

Summary

docs/guide/*          -> English source (default locale)
docs/guide/<lang>/*   -> translated markdown in git
cms jail Astro app    -> sync + build + deploy (all locales)
docs.clawdie.si       -> live localized output

Future plan: if hand-editing locale files becomes too much, Crowdin can be reintroduced to manage strings — it would push the English source and pull completed translations back into the same docs/guide/<lang>/ layout, leaving these build/deploy stages unchanged. It is not part of the current flow.