colibri/docs/guide/localization/setup.md

title	description
Setup Instructions	Add a locale and deploy localized docs through the cms-jail Astro workflow.

Setup Instructions

This page covers adding and shipping a translated locale with the Astro/Starlight-native flow. No translation service or API token is required.

What you need

• the Clawdie repo checked out on the host
• a working cms jail with the Astro docs project already provisioned

The docs runtime is not a separate standalone Astro install — it is the shared cms-jail docs project.

Step 1: Create the locale directory

Locales mirror the English tree under a BCP-47 directory. For Slovenian:

cd /home/<agent>/clawdie-ai
mkdir -p docs/guide/sl

Step 2: Add a translated page

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

cp docs/guide/operate/terminal-capture.md \
   docs/guide/sl/operate/terminal-capture.md
# translate docs/guide/sl/operate/terminal-capture.md, then:
git add docs/guide/sl/operate/terminal-capture.md
git commit -m "docs(sl): translate terminal-capture"

Keep the path identical to the English source so Starlight pairs the translation with the right page.

Step 3: Deploy localized docs

Deploy happens through the shared Astro project in the cms jail:

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

That command:

1. syncs host-side docs content into the Astro tree
2. builds the static site for every locale present
3. deploys it into the cms jail webroot

Step 4: Verify

Check the live site:

curl -sI https://docs.clawdie.si/
curl -sI https://docs.clawdie.si/sl/

Then verify the specific locale pages you expected to change.

Notes

• Edit markdown on the host, not inside the jail.
• A locale only needs the pages you have translated; untranslated pages fall back to the default locale.
• Astro deployment is shared with the docs publishing flow, not a separate localization runtime.

Future plan: Crowdin would slot in here as a string-management layer (push source / pull translations into docs/guide/<lang>/) and would add back a token-configuration step. It is not used today.