colibri/docs/guide/localization/setup.md

---
title: Setup Instructions
description: 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.