ba19a5e2ca
Localization rework: rewrite docs/guide/localization/{index,how-it-works,
setup,troubleshooting}.md to describe Starlight-native i18n — locales mirror
the tree under docs/guide/<lang>/ (default English at root), the cms-jail
Astro deploy builds all locales, no external service in the live path.
Corrects the stale docs/public/ references (docs live in docs/guide/) and
demotes Crowdin to a clearly-labelled Future-plan note (not wired up today).
Slovenian batch 1 under docs/guide/sl/: navigable skeleton across every
section (top index + all six section indexes + the localization index) plus
two fully translated content pages (operate/terminal-capture,
architecture/control-plane-bridge). Literal commands/JSON/env-vars kept in
English; prose, frontmatter, and table headers translated. prettier-clean,
no real tailnet IPs. Content-heavy bodies (install/operate/architecture/
reference/roadmap) are batch 2, recommended after a native review of this set.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2.2 KiB
| 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:
- syncs host-side docs content into the Astro tree
- builds the static site for every locale present
- 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.