Community Translation SDK

Overview

The Translation SDK lets community developers translate the entire zero2claude.dev platform — UI strings and lesson content — via a simple REST API. Translations go through automated QA checks and admin review before being merged as a GitHub PR.

Authentication

All endpoints require an API key. Keys are created by the platform admin and start with trn_. Include it as a Bearer token:

curl -H "Authorization: Bearer trn_your_api_key_here" \
  https://zero2claude.dev/api/translate/base/manifest

API Reference

Base URL: https://zero2claude.dev/api/translate

Download Content

// Response
{
  "namespaces": ["achievements", "auth", "common", ...],
  "lessons": [
    { "key": "level0/lesson-0.1", "title": "What Is a File?", ... }
  ],
  "lessonCount": 148,
  "namespaceCount": 13,
  "contentHash": "90b822d2..."
}

// Response
{
  "common": { "loading": "Loading...", "save": "Save", ... },
  "nav": { "home": "Home", "dashboard": "Dashboard", ... },
  ...
}

Validate & Submit

// Response
{
  "score": 97,
  "passesReview": true,
  "summary": "0 errors, 1 warning",
  "checks": [
    { "name": "completeness", "status": "pass", "severity": "error", ... },
    ...
  ]
}

// Request body — see Payload Format section below

// Response (201 Created)
{
  "id": "uuid-here",
  "status": "qa_passed",
  "qaScore": 97,
  "qaSummary": "0 errors, 1 warning",
  "createdAt": "2026-05-25T..."
}

Check Status

// Response
{
  "id": "uuid-here",
  "status": "approved",
  "qaResults": { ... },
  "adminFeedback": null,
  "githubPrUrl": "https://github.com/...",
  "reviewedAt": "2026-05-25T..."
}

Payload Format

Both /validate and /submit accept the same JSON payload:

{
  "languageCode": "fr",          // ISO 639-1 (2-3 letter code, optional region)
  "languageName": "Français",     // Native name of the language
  "isRtl": false,                // Right-to-left layout
  "uiNamespaces": {
    "achievements": { ... },     // All 13 namespaces required
    "auth": { ... },
    "common": { ... },
    "dashboard": { ... },
    "errors": { ... },
    "feedback": { ... },
    "forum": { ... },
    "help": { ... },
    "home": { ... },
    "lesson": { ... },
    "maintenance": { ... },
    "nav": { ... },
    "onboarding": { ... }
  },
  "lessonOverlays": {
    "level0/lesson-0.1": {      // Key from manifest
      "title": "Qu'est-ce qu'un fichier ?",
      "subtitle": "...",
      "sections": [
        { "content": "..." },
        { "instruction": "...", "explanation": "..." }
      ]
    },
    ...                            // All 148 lessons required
  }
}

Translation Rules

• Translate all UI string values and lesson text fields (title, subtitle, content, instruction, explanation)
• Preserve all {{placeholder}} markers exactly as they appear in English
• Preserve all HTML tags (<strong>, <code>, <br>, etc.)
• Preserve all backtick-wrapped terminal commands (e.g., `cd Documents`)
• Do not translate UNIX commands (cat, ls, cd, grep, etc.)
• Do not include protected fields (game logic, answers, validation) in overlays
• Keep pluralization keys if the English source uses them (e.g., _one, _other)

QA Checks

Every submission runs through 10 automated quality checks. Errors block approval; warnings are informational.

Check	Severity	What It Validates
completeness	error	All English UI keys are present in the translation
extra_keys	warning	No keys exist in translation that don't exist in English
placeholders	error	All {{variable}} placeholders preserved exactly
html_tags	error	HTML tags (<strong>, <code>, etc.) preserved
terminal_commands	error	Backtick-wrapped commands (`ls -la`) not translated
overlay_structure	error	No protected fields (answers, validation, game logic) in overlays
length_ratio	warning	Translated strings are within reasonable length range (0.5x–3x English)
utf8	error	Clean UTF-8 encoding, no invisible characters or control bytes
pluralization	warning	Pluralization keys (_one, _other) are present when English uses them
untranslated_content	error	Detects lessons or UI strings that are still identical to English (not actually translated)

A score of 90+ with zero errors means passesReview: true and the submission can be approved by the admin.

Full Workflow Example

1. Download the manifest

curl -H "Authorization: Bearer trn_..." \
  https://zero2claude.dev/api/translate/base/manifest

2. Download English content

# UI namespaces
curl -H "Authorization: Bearer trn_..." \
  https://zero2claude.dev/api/translate/base/ui -o english_ui.json

# Lesson content
curl -H "Authorization: Bearer trn_..." \
  https://zero2claude.dev/api/translate/base/lessons -o english_lessons.json

3. Build your translation

Use the downloaded files as templates. Translate every string value while preserving placeholders, HTML, and terminal commands.

4. Validate (dry-run)

curl -X POST \
  -H "Authorization: Bearer trn_..." \
  -H "Content-Type: application/json" \
  -d @payload.json \
  https://zero2claude.dev/api/translate/validate

Fix any errors reported and re-validate until passesReview: true.

5. Submit

curl -X POST \
  -H "Authorization: Bearer trn_..." \
  -H "Content-Type: application/json" \
  -d @payload.json \
  https://zero2claude.dev/api/translate/submit

6. Check status

curl -H "Authorization: Bearer trn_..." \
  https://zero2claude.dev/api/translate/submissions/YOUR_SUBMISSION_ID

When approved, the response includes the GitHub PR URL with all your translation files.

Submission Statuses

• qa_passed — QA checks passed (score 90+, zero errors). Awaiting admin review.
• qa_failed — QA checks found errors. Fix issues and submit again.
• approved — Admin approved. A GitHub PR has been created with your translation files.
• rejected — Admin rejected with feedback. Check adminFeedback for details, fix, and resubmit.

Rate Limits

• API requests: 60 per hour per key (configurable by admin)
• Submissions: 2 per hour per key
• Payload size: 50 MB max
• Language code: ISO 639-1 format (fr, ja, pt-BR)
• Duplicate guard: Only one active submission per language at a time