clawdie-ai/CROWDIN.md

Crowdin Translation Workflow

Project: Clawdie-AI Documentation Status: Phase 3.5 (Active) Crowdin URL: https://crowdin.com/project/clawdie-ai Last Updated: 24.mar.2026

---

Overview

Crowdin manages multi-language translations for Clawdie-AI documentation. The workflow is:

1. Authors write English markdown in docs/public/install/install.md, etc.
2. Crowdin webhook detects commits and pulls new English strings
3. Translators work on translations in Crowdin UI (German, French, Spanish, Slovenian)
4. Crowdin bot commits translated markdown to language-specific directories (docs/public/de/, docs/public/fr/, etc.)
5. Daily sync @ 05:00 UTC compiles all languages to HTML and deploys zero-downtime

---

Language Configuration

Language	Code	Region	Status	Translators
English	en	—	Source	—
Slovenian	sl	Balkans	Active	Community
German	de	Central Europe	Active	Community
Croatian	hr	Balkans	Active	Community
Serbian (Cyrillic)	sr	Balkans	Active	Community
Russian	ru	Eastern Europe	Active	Community

v0.9.0 Languages:

• Source: English
• Primary target: Slovenian (prototype default)
• Regional focus: Central Europe (German) + Balkans (Croatian, Serbian) + Eastern Europe (Russian)

Future additions (v0.9.1+):

• French, Spanish, Greek, Macedonian, others

---

Workflow: Author Writes, Crowdin Translates

Step 1: Author Commits English Docs (clawdie-ai repo)

cd /home/clawdie/clawdie-ai

# Write or update English docs
vim docs/public/install/install.md
git add docs/public/install/install.md
git commit -m "docs: Add installation guide"
git push origin main

What happens automatically:

• GitHub webhook triggers Crowdin webhook
• Crowdin fetches new English strings from docs/public/**/*.md
• New strings appear in Crowdin UI for translation

Step 2: Translators Work (Crowdin Web UI)

Translators access: https://crowdin.com/project/clawdie-ai

• View new English strings (source)
• Translate to German, French, Spanish, Slovenian
• Typically 24-48 hours for community translations
• Crowdin marks translations 100% complete

Step 3: Crowdin Bot Commits Translations (Automated)

When translations reach 100%, Crowdin bot auto-commits:

docs/public/de/install/install.md   ← German translation
docs/public/fr/install/install.md   ← French translation
docs/public/es/install/install.md   ← Spanish translation
docs/public/sl/install/install.md   ← Slovenian translation

Branch: main (direct commit, or PR if configured) Commit message: "translations: update {language} translations from Crowdin"

Step 4: Daily Sync @ 05:00 UTC (docs-sync.cron.sh)

Runs automatically on deployed host:

# Host: /home/clawdie/clawdie-ai (on FreeBSD)
# Time: 05:00 UTC daily

1. git pull
   ✓ Fetches new translations from Crowdin bot commits

2. docs-compile.sh --languages sl,en,de,hr,sr,ru
   ✓ Compiles English + all translations to HTML

3. Symlink swap (zero-downtime)
   ✓ Swaps docs-current → new versioned directory

4. nginx reload
   ✓ Serves updated documentation in all languages

5. Cleanup old versions (30-day retention)

---

File Structure

Source (English)

docs/public/
├── install/install.md           (English — source)
├── architecture/bastille.md     (English — source)
└── [other markdown files]

Translations (Auto-created by Crowdin)

docs/public/
├── de/                  (German — Crowdin bot creates these)
│   ├── install/install.md
│   └── [translated files]
├── hr/                  (Croatian)
│   ├── install/install.md
│   └── [translated files]
├── sr/                  (Serbian Cyrillic)
│   └── ...
├── ru/                  (Russian)
│   └── ...
└── sl/                  (Slovenian)
    └── ...

Compiled Output (Daily @ 05:00 UTC)

/usr/local/www/docs.clawdie.si/
├── docs-v0.9.0_24.mar.2026/   (versioned build)
│   ├── en/                      (English HTML)
│   │   ├── INSTALL.html
│   │   └── [other HTML]
│   ├── de/                      (German HTML)
│   ├── hr/                      (Croatian HTML)
│   ├── sr/                      (Serbian HTML)
│   ├── ru/                      (Russian HTML)
│   └── sl/                      (Slovenian HTML)
│
├── en-current → docs-v0.9.0_24.mar.2026/en/
├── de-current → docs-v0.9.0_24.mar.2026/de/
├── hr-current → docs-v0.9.0_24.mar.2026/hr/
├── sr-current → docs-v0.9.0_24.mar.2026/sr/
├── ru-current → docs-v0.9.0_24.mar.2026/ru/
└── sl-current → docs-v0.9.0_24.mar.2026/sl/

---

Adding a New Language

Step 1: Admin Adds to Crowdin Project

1. Log in to Crowdin: https://crowdin.com/project/clawdie-ai
2. Project settings → Languages → Add language
3. Set target language (e.g., Italian: it)
4. Enable language for all files

Step 2: Update clawdie-ai Codebase

In scripts/docs-sync.cron.sh:

LANGUAGES="sl,en,de,hr,sr,ru,it"  # Add new language to the list

In setup/onboarding.ts (if needed):

// Add to supported display locales
import { enumerateFreeBSDLocales } from './freebsd-locales.js';
// Already generic, will auto-detect if FreeBSD has locale

Step 3: Commit & Push

git add scripts/docs-sync.cron.sh
git commit -m "docs: Add Italian (it) to supported languages"
git push origin main

Step 4: Next Daily Sync

At 05:00 UTC, the cron job will:

• Check for docs/public/it/ directory
• Compile Italian to HTML
• Create symlink: it-current
• Nginx automatically serves new language

---

Configuration Files

crowdin.yml

Located at: .crowdin.yml (git root)

Tells Crowdin which files to sync and language mappings:

project_id: <PROJECT_ID>
api_token: <API_TOKEN>
base_path: /
preserve_hierarchy: true

files:
  - source: /docs/public/**.md
    dest: /docs/public/{two_letters_code}
    translation_update: crowdin_move
    languages_mapping:
      two_letters_code:
        sl: sl
        de: de
        fr: fr
        es: es

Where:

• project_id — From Crowdin project settings
• api_token — Personal API token (secrets, not in git)
• source — English markdown files
• dest — Where translations land (docs/public/de/, docs/public/fr/, etc.)

GitHub Actions (Optional)

If using GitHub Actions for sync (instead of hosted cron):

# .github/workflows/crowdin-sync.yml
name: Crowdin Sync
on:
  schedule:
    - cron: '0 5 * * *'  # 05:00 UTC

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: crowdin/github-action@v1
        with:
          upload_sources: true
          download_translations: true
        env:
          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

---

Troubleshooting

Translations Not Appearing

Problem: Crowdin committed translations, but they're not showing up in compiled docs.

Checklist:

1. ✓ Check docs/public/de/, docs/public/fr/, etc. exist and have markdown files
2. ✓ Verify LANGUAGES in docs-sync.cron.sh includes the language code
3. ✓ Check daily sync log: /var/log/clawdie-docs-sync.log
4. ✓ Verify docs-compile.sh --language de runs without error

Manual test:

cd /home/clawdie/clawdie-ai
./scripts/docs-compile.sh --language de /tmp/test-output/
ls /tmp/test-output/docs-v*/de/
# Should see HTML files

Webhook Not Firing

Problem: Authors commit English docs, but Crowdin doesn't pull them.

Checklist:

1. ✓ Verify Crowdin webhook URL in GitHub repo settings
2. ✓ Check Crowdin project is active (not disabled)
3. ✓ Check GitHub organization has Crowdin app authorized
4. ✓ Review Crowdin webhook logs: Project → Integrations → GitHub → Logs

Manual trigger (testing):

# If needed, manually upload to Crowdin using API:
curl -X POST https://api.crowdin.com/api/v2/storages \
  -H "Authorization: Bearer $CROWDIN_API_TOKEN" \
  -F "file=@docs/public/install/install.md"

Old Versions Not Cleaning Up

Problem: /usr/local/www/docs.clawdie.si/ is full of old version directories.

Checklist:

1. ✓ Check RETENTION_DAYS in docs-sync.cron.sh (default: 30)
2. ✓ Verify cleanup step ran: /var/log/clawdie-docs-sync.log should show removals
3. ✓ Check permissions: cleanup step needs write access to /usr/local/www/docs.clawdie.si/

Manual cleanup:

find /usr/local/www/docs.clawdie.si -maxdepth 1 -name "docs-v*" -type d \
  -mtime +30 -exec rm -rf {} \;

---

Deployment Integration

How Docs Get Deployed

1. Authors write English → push to GitHub
2. Crowdin fetches → new strings in UI (webhook)
3. Translators translate → Crowdin marks 100% complete
4. Crowdin bot commits → translations to docs/public/de/, docs/public/fr/, etc.
5. Daily cron @ 05:00 UTC → pulls translations, compiles to HTML, swaps symlinks

Users Access Docs

Browser: https://docs.clawdie.si/
  ↓
Language selector (generated by nginx)
  ↓
User picks language: /sl/, /en/, /de/, /fr/, /es/
  ↓
Nginx resolves: sl-current → docs-v0.9.0_24.mar.2026/sl/
  ↓
User sees Slovenian documentation (in their preferred language)

---

Best Practices

For Authors

• ✅ Commit only English markdown to docs/public/**/*.md (Crowdin handles translations)
• ✅ Use clear, simple English — easier for translators to understand
• ✅ Avoid screenshots of text — text in images can't be translated
• ✅ Use markdown consistently — helps Crowdin segment correctly
• ❌ Don't manually edit docs/public/de/, docs/public/fr/, etc. (Crowdin bot will overwrite)

For Translators

• ✅ Work in Crowdin UI (https://crowdin.com/project/clawdie-ai)
• ✅ Mark translations complete when done (signals Crowdin bot to commit)
• ✅ Ask for context in Crowdin comments if unclear
• ✅ Test translations in local HTML output after commit
• ❌ Don't commit translations directly to GitHub (Crowdin bot does this)

For Operators (Deployment)

• ✅ Monitor cron logs daily: /var/log/clawdie-docs-sync.log
• ✅ Test manual sync if something seems stuck:

  /home/clawdie/clawdie-ai/scripts/docs-sync.cron.sh
  

• ✅ Verify symlinks after each sync:

  ls -la /usr/local/www/docs.clawdie.si/ | grep current
  

• ✅ Check nginx is serving correct version:

  curl -I https://docs.clawdie.si/en/ | grep -i version
  

---

FAQ

Q: Can I translate without Crowdin?

A: Not recommended. Crowdin ensures consistent terminology, translation memory, and automation. Manual translations would require Git commits per translator.

Q: What if a translator wants to edit English?

A: They can't in Crowdin (view-only). If they spot an error, they should file an issue on GitHub or comment in Crowdin, and the author will fix English source.

Q: How long until translations appear on the live site?

A: Typically 24-48 hours after 100% translation + next daily sync (05:00 UTC). So worst case: request submitted Monday afternoon → live by Wednesday morning.

Q: Can I use machine translation?

A: Crowdin offers machine translation (Microsoft Translator, Google, etc.) as a starting point. Translators can then improve. Good for rapid initial coverage of new languages.

Q: What about RTL languages (Arabic, Hebrew)?

A: Crowdin supports RTL, but HTML/CSS would need updates. Not currently in scope (Phase 3.5). Plan for Phase 4 (CMS migration).

---

Resources

• Crowdin Project: https://crowdin.com/project/clawdie-ai
• Crowdin API Docs: https://developer.crowdin.com/
• GitHub Crowdin App: https://github.com/apps/crowdin
• Local Sync Runbook: docs/internal/DOCUMENTATION-SYNC-RUNBOOK.md
• Integration Guide: .agent/skills/docs-deployment/INTEGRATION.md

---

Questions? Open an issue on GitHub or contact the project maintainers.