translate-examples-to-swift

name	translate-examples-to-swift
description	Translates inline JavaScript example code to Swift

Usage

Invoke this skill with /translate-examples-to-swift followed by a description of what to translate.

Examples

/translate-examples-to-swift translate the JavaScript examples in src/pages/docs/ai-transport/streaming.mdx

/translate-examples-to-swift translate all JavaScript code blocks in the src/pages/docs/messages/ directory

/translate-examples-to-swift translate the code block at line 45 of src/pages/docs/channels/index.mdx

What to specify

• File or directory: Which documentation file(s) contain the examples to translate
• Scope (optional): Specific code blocks if you don't want to translate all examples in a file

---

Architecture Overview

This skill uses a three-phase architecture with independent translation, verification, and assembly:

1. Translation phase: Spawn one sub-agent per MDX file. Each translates examples, self-checks compilation (for iteration), inserts into MDX, and writes translation metadata JSON.

2. Verification phase: Spawn one sub-agent per MDX file. Each reads Swift code from the MDX (source of truth), compiles in a fresh harness, assesses faithfulness, and writes verification results JSON.

3. Assembly phase: Run consolidate.sh to merge JSONs and generate review HTML.

Key principle: Verification reads from MDX, not from translation output. This ensures verification tests what actually ships.

Verify-only mode: When translations already exist in MDX but no translation JSONs are available, you can skip the translation phase and run only verification + assembly. See the "Verify-only workflow" section below.

Always delegate: Spawn a sub-agent for each file, even for single-file tasks. This keeps behavior consistent and context isolated.

---

Orchestrator Constraints

The orchestrator (you, when running this skill) coordinates subagents but does NOT directly modify:

• MDX documentation files
• Translation JSON files (swift-translations/translations/*.json)
• Verification JSON files (swift-translations/verifications/*.json)

All modifications to these files must go through the appropriate subagent. The orchestrator may:

• Read files to understand state
• Run validation commands
• Run the consolidation script
• Spawn and coordinate subagents
• Report results to the user

This separation ensures that all code changes are tested before being written, and all verification results reflect actual verification.

---

Output Directory Structure

All intermediate files go in swift-translations/ at the repo root:

swift-translations/
    harness-{filename}/       # Test harness per translation subagent
    verify-{filename}/        # Test harness per verification subagent
    translations/
        {filename}.json       # One per MDX file
    verifications/
        {filename}.json       # One per MDX file
    consolidated.json         # Merged data for review app (generated by script)
    review.html               # Human review interface (generated by script)

The {filename} is derived from the MDX filename without path or extension:

• src/pages/docs/ai-transport/messaging/citations.mdx → citations
• src/pages/docs/ai-transport/token-streaming/message-per-token.mdx → message-per-token

---

Workflow

Step 1: Spawn translation subagents

For each MDX file to translate, spawn a translation subagent.

Get the prompt from the file .claude/skills/translate-examples-to-swift/prompts/translation-subagent.md:

1. Read the file
2. Replace {FILEPATH} with the full path to the MDX file being translated
3. Replace {FILENAME} with the MDX filename without path or extension
4. Pass the result as the subagent prompt

Do not paraphrase or rewrite the prompt. Use the file contents with only the placeholders replaced. Launch a general-purpose subagent with the resulting prompt.

Validate translation output

After each translation subagent completes, validate its JSON output:

npx ajv-cli validate \
  -s .claude/skills/translate-examples-to-swift/schemas/translation.schema.json \
  -d swift-translations/translations/{filename}.json

If validation fails, report the error.

Step 2: Spawn verification subagents

After translation subagents complete, spawn verification subagents for each file that was translated.

Important: Spawn a verification subagent for EVERY file that had a translation subagent, even if that file had no examples. This ensures 1:1 matching between translation and verification outputs, avoiding special-case handling in the consolidation phase.

Get the prompt from the file .claude/skills/translate-examples-to-swift/prompts/verification-subagent.md:

1. Read the file
2. Replace {FILEPATH} with the full path to the MDX file being verified
3. Replace {FILENAME} with the MDX filename without path or extension
4. Pass the result as the subagent prompt

Do not paraphrase or rewrite the prompt. Use the file contents with only the placeholders replaced. Launch a general-purpose subagent with the resulting prompt.

Why independent verification?

• Fresh perspective: The verifier has no memory of translation decisions, so it approaches the code without bias
• Catches copy-paste errors: Ensures the code in documentation matches what was actually tested
• Validates harness comments: Confirms the test harness comments are complete and usable
• Faithfulness check: Compares translations against originals with fresh eyes

Validate verification output

After the verification subagent completes, validate its JSON output:

npx ajv-cli validate \
  -s .claude/skills/translate-examples-to-swift/schemas/verification.schema.json \
  -d swift-translations/verifications/{filename}.json

If validation fails, report the error.

Handling verification results

When the verification subagent returns:

1. All passed: Proceed to Step 3 (generate review file)
2. Compilation failures or faithfulness concerns:
   • Report the failures to the user with details
   • Ask if they want you to attempt a fix
   • If yes, spawn a new translation subagent (or resume the original one) to fix the issue
   • After the fix subagent completes, spawn a new verification subagent to re-verify
   • Repeat until verification passes or the user decides to skip

Important: The orchestrator must NEVER directly edit MDX files or verification JSON files. All changes to translations must go through a translation subagent. All verification results must come from a verification subagent.

Step 3: Generate review file

Run the consolidation script to merge JSONs and generate the review HTML:

.claude/skills/translate-examples-to-swift/scripts/consolidate.sh

This reads from swift-translations/translations/ and swift-translations/verifications/, then produces:

• swift-translations/consolidated.json - merged data
• swift-translations/review.html - human review interface

The review HTML provides:

• Side-by-side comparison of JavaScript and Swift code
• Syntax highlighting
• Translation notes and decisions (collapsible)
• Test harness context (collapsible)
• Verification results (compilation status, faithfulness rating)
• Interactive review controls (approve/flag/skip with comments)
• Export functionality for review summary

Step 4: Report back to the user

Report back to the user, explaining:

• any important decisions that were made, such as deviations from the JavaScript code
• the verification results summary
• any issues that require human attention
• the location of the review file for human review

Example:

Translation complete.

## Summary
- Files processed: 2
- Examples translated: 5
- Compilation: 4 passed, 1 failed

## Review file
Open the review file to examine translations:
  swift-translations/review.html

## Issues requiring attention
- src/pages/docs/messages/updates-deletes.mdx:78 - Compilation failed: `updateSerial` property not found

---

Handling user feedback

When the user reviews the generated review file and provides feedback:

1. Spawn a translation subagent (or resume the original one) to make the requested changes
   • The subagent will update the test harness, verify compilation, and update the MDX
2. Spawn a verification subagent to independently verify the changes
3. Regenerate the review file with updated data
4. Report back to the user

Important: The orchestrator must NEVER directly edit MDX files, translation JSON, or verification JSON. All file modifications must go through the appropriate subagent. This ensures:

• Every change is tested before being written
• The verification JSON always reflects actual verification results
• There's a clear audit trail of what each agent did

This is not optional. Any change to a translation—whether from user feedback, verification comments, or your own corrections—must go through the full verify-and-review cycle before being considered complete.

---

Verify-only workflow

Use this workflow when Swift translations already exist in the MDX files but no translation JSON files are available. This happens when:

• Re-verifying translations from a previous session
• Manual edits were made directly to MDX files
• Translation JSON output was discarded or lost

Step 1: Spawn verification subagents

Same as the normal workflow Step 2 — spawn a verification subagent for each MDX file. Use the prompt from .claude/skills/translate-examples-to-swift/prompts/verification-subagent.md with placeholders replaced.

Step 2: Generate translation stubs

After verification subagents complete, generate stub translation JSONs from the verification data:

.claude/skills/translate-examples-to-swift/scripts/generate-translation-stubs.sh

This reads each verification JSON and creates a matching translation JSON with a "verify-only" info note. It skips files that already have a translation JSON, so it's safe to run even if some real translations exist.

Step 3: Run consolidation

Run consolidate.sh as normal:

.claude/skills/translate-examples-to-swift/scripts/consolidate.sh

Step 4: Report back

Report as normal, but note that translation notes are unavailable since the translation phase was skipped. The review HTML will show a "verify-only" info note in place of translation decision notes.

---

The verification invariant

Never output code that hasn't been verified. This is the core principle of the skill:

• Every Swift code block inserted into documentation must have passed swift build in a test harness
• Every change to existing Swift code must be re-verified before the task is complete
• The review file must always reflect the current state of the translations

If you find yourself about to report completion without having verified recent changes, stop and run verification first.

---

Scripts

Scripts are in .claude/skills/translate-examples-to-swift/scripts/:

• consolidate.sh - Merges translation and verification JSONs, validates, generates review HTML
• generate-translation-stubs.sh - Generates stub translation JSONs from verification data (for verify-only mode)

Review app scripts are in .claude/skills/translate-examples-to-swift/review-app/:

• generate-review.sh - Generates review HTML from consolidated JSON (called by consolidate.sh)

JSON Schemas

Schemas are in .claude/skills/translate-examples-to-swift/schemas/:

• translation.schema.json - Translation sub-agent output (notes and metadata)
• verification.schema.json - Verification sub-agent output (code, harness, results)
• consolidated.schema.json - Final merged data for review app

Validate with:

npx ajv-cli validate -s {schema} -d {data}