colibri/.agent/skills/docs-localization-pipeline

Docs Localization Pipeline Skill

Codifies the three-bird documentation architecture for Pi/Aider automation.

Overview

This skill automates the complete documentation localization and deployment pipeline:

English Docs (docs/public/)
    ↓
Crowdin (Project 883714)
    ↓ [Push source, Pull translations]
Translated Docs (docs/public/{lang}/)
    ↓
Astro Starlight Build
    ↓ [npm run build]
Static Site (dist/)
    ↓
Deploy to nginx
    ↓
Public: https://docs.clawdie.si

Quick Start

1. Initial Setup (First Time Only)

# Setup Astro Starlight project
./.agent/skills/docs-localization-pipeline/setup-clawdie-docs.sh

# Verify setup
ls -la /home/clawdie/clawdie-docs/
cd /home/clawdie/clawdie-docs && npm run dev
# Browse: http://localhost:4321

2. Manual Pipeline Execution

# Full pipeline (all stages)
./.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --all

# Individual stages
./.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --push      # Push sources to Crowdin
./.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --pull      # Pull translations
./.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --build     # Pull + Build
./.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --deploy    # Deploy built site
./.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --status    # Check Crowdin status

3. Pi/Aider Commands

# Via Pi TUI
pi "sync and rebuild documentation site"
pi "publish docs translations"
pi "check documentation translation progress"

# Via Aider
aider --auto-commits --message "Sync translations and rebuild docs" docs/

File Structure

.agent/skills/docs-localization-pipeline/
├── SKILL.md                    # Architecture & detailed reference
├── README.md                   # This file
├── setup-clawdie-docs.sh         # Bootstrap Astro Starlight project
└── orchestrate-pipeline.sh     # Orchestrate full Crowdin→Astro→Deploy pipeline

Scripts

setup-clawdie-docs.sh

Purpose: Bootstrap the Astro Starlight documentation site.

Usage:

./setup-clawdie-docs.sh                 # Default: /home/clawdie/clawdie-docs
./setup-clawdie-docs.sh /custom/path    # Custom path

What it does:

1. Creates Astro project structure
2. Installs dependencies (npm install)
3. Generates astro.config.mjs with multi-language configuration
4. Sets up content collections config
5. Creates symlinks to docs/public/{lang}/ for translations
6. Creates i18n UI translation JSON files

Prerequisites:

• Node.js >=20
• npm
• Docs source at /home/clawdie/clawdie-ai/docs/public/

Output:

/home/clawdie/clawdie-docs/
├── package.json
├── astro.config.mjs
├── tsconfig.json
├── src/
│   ├── content/config.ts
│   ├── docs/
│   │   ├── en → /home/clawdie/clawdie-ai/docs/public/en
│   │   ├── de → /home/clawdie/clawdie-ai/docs/public/de
│   │   └── [other languages]
│   └── i18n/
│       ├── en.json
│       ├── de.json
│       └── sl.json
└── dist/ (after npm run build)

orchestrate-pipeline.sh

Purpose: Automate the full Crowdin→Astro→Deploy pipeline.

Usage:

./orchestrate-pipeline.sh --all              # Full pipeline
./orchestrate-pipeline.sh --push             # Stage 1: Push English sources
./orchestrate-pipeline.sh --pull             # Stage 2: Pull translations
./orchestrate-pipeline.sh --build            # Stages 2+3: Pull + Build
./orchestrate-pipeline.sh --build-only       # Stage 3: Build only
./orchestrate-pipeline.sh --deploy-only      # Stage 4: Deploy
./orchestrate-pipeline.sh --status           # Check Crowdin status
./orchestrate-pipeline.sh --help             # Show help

Stages:

Stage	Command	What It Does
1	--push	Upload English docs/public/*.md to Crowdin
2	--pull	Download translations into docs/public/{lang}/
3	--build	Run npm run build to generate static site
4	--deploy	Copy dist/ to nginx webroot

Environment Variables:

# Set in .env or export before running
CROWDIN_PERSONAL_TOKEN=tskey-xxx      # Crowdin API token (required for push/pull)
CMS_DOCS_SITE_PATH=/home/clawdie/clawdie-docs   # Astro project path
DOCS_DEPLOY_TARGET=/usr/local/www/clawdie/docs  # nginx webroot
DOCS_MIN_COMPLETION=80                # Min % translation completion before deploy

Output Example:

=== Stage 1: Push English Sources to Crowdin ===
[INFO] Uploading English sources to Crowdin...
  [1] Uploading: install/index.md
  [2] Uploading: install/requirements.md
  ...
[INFO] Upload complete: 42 files processed, 0 failed

=== Stage 2: Pull Translations from Crowdin ===
[INFO] Downloading translations from Crowdin...
[INFO] Translation completion: 85% ✓
Language: sl
  Downloaded: /tmp/crowdin-sl-1712951234.zip
  ✓ Extracted 42 files to sl/

=== Stage 3: Build Astro Site ===
[INFO] Building Astro site...
✓ Site built: 217 files

=== Stage 4: Deploy to Nginx ===
[INFO] Copying files to /usr/local/www/clawdie/docs
✓ Nginx reloaded
✓ Deploy complete: https://docs.clawdie.si

Configuration

.env Setup

# Crowdin API token (https://crowdin.com/settings/api/tokens)
CROWDIN_PERSONAL_TOKEN=tskey-your-token-here

# Astro project path (optional, defaults to /home/clawdie/clawdie-docs)
CMS_DOCS_SITE_PATH=/home/clawdie/clawdie-docs

# nginx deployment target (optional, defaults to /usr/local/www/clawdie/docs)
DOCS_DEPLOY_TARGET=/usr/local/www/clawdie/docs

# Minimum translation completion % before deploying (default: 80)
DOCS_MIN_COMPLETION=80

Crowdin Project

• Project ID: 883714
• Configuration: .crowdin.yml (repo root)
• Languages: SL (default), EN, DE, HR, SR, RU, EL, IT, MK, SK, BS
• Source: docs/public/**.md
• Output: docs/public/{lang}/

Workflows

Weekly Sync (Recommended)

# Add to crontab (runs Monday 9am)
0 9 * * MON /path/to/.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --pull && \
  cd /path/to && \
  /path/to/.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --build-only && \
  /path/to/.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --deploy-only

On-Demand via Pi

# Pi will interpret natural language and call orchestrate-pipeline.sh
pi "sync docs translations and rebuild site"
# → Executes: orchestrate-pipeline.sh --all

GitHub Actions (Optional)

See .github/workflows/crowdin-sync.yml for automated CI/CD setup.

Troubleshooting

"Crowdin token not found"

Fix:

# Option A: Create token file
mkdir -p ~/.config/clawdie
echo "tskey-your-token" > ~/.config/clawdie/crowdin-token
chmod 600 ~/.config/clawdie/crowdin-token

# Option B: Set env var
export CROWDIN_PERSONAL_TOKEN=tskey-your-token

# Option C: Add to .env
echo 'CROWDIN_PERSONAL_TOKEN=tskey-your-token' >> .env

"Astro project not found"

Fix:

# Run setup script
./.agent/skills/docs-localization-pipeline/setup-clawdie-docs.sh

"npm: command not found"

Fix: Install Node.js and npm for FreeBSD:

sudo pkg install node24 npm-node24

"Translation completion too low"

Fix: Adjust DOCS_MIN_COMPLETION or wait for translators:

DOCS_MIN_COMPLETION=50 ./orchestrate-pipeline.sh --all

"Astro build fails with missing locale"

Fix: Ensure translations are pulled before build:

# Manual steps
./scripts/crowdin-sync.sh --pull
cd /home/clawdie/clawdie-docs && npm run build

"Deploy fails: permission denied"

Fix: Ensure sudo access to webroot:

# Add to sudoers (FreeBSD):
sudo visudo
# Add line: clawdie ALL=(ALL) NOPASSWD: /bin/cp -r, /usr/sbin/service nginx

Next Steps

1. Crowdin Setup → Create translators and assign languages
2. First Push → ./orchestrate-pipeline.sh --push to seed English sources
3. Translation → Wait for translators to complete milestone (80%+)
4. First Build → ./orchestrate-pipeline.sh --build to test build
5. Deploy → ./orchestrate-pipeline.sh --deploy to go live
6. Automate → Setup cron or GitHub Actions for weekly syncs

References

• Crowdin Project: https://crowdin.com/project/clawdie-ai
• Crowdin API: https://developer.crowdin.com/api/
• Astro Docs: https://docs.astro.build/
• Starlight Docs: https://starlight.astro.build/
• Skill Architecture: SKILL.md (in this directory)