Skill: Translate Sync

Objective

Synchronize content from English (en) across all active languages — pages, methodology/spec/kit docs, and translation strings. Ensures multilingual parity across the entire site. (The site is N-language ready; to add a brand-new locale use the add-language skill.)

Non-Goals

• Does NOT create new pages from scratch (use add-page)
• Does NOT modify the translation system architecture
• Does NOT add new languages to src/lib/i18n.ts (only syncs existing active languages)
• Does NOT change Content Collection schemas or content.config.ts

Tier Classification

Tier: 1 - Light/Cheap

Reasoning: Translation follows established patterns, is content-focused, and has low risk. The source content already exists; this skill produces the counterpart.

Inputs

Required Parameters

• $SOURCE_FILE: The file that was recently created or modified (en or es version)

Optional Parameters

• $TARGET_LANG: Target language to sync to (default: auto-detect the opposite language from source path)
• $CONTENT_TYPE: Type of content: page, content-doc (methodology/spec/kit), translation-strings (default: auto-detect from file path)

Prerequisites

• Source file exists and is valid
• For content docs: understand the relevant Content Collection schema in content.config.ts
• For translation strings: understand src/lib/translations/ modular structure

Steps

Step 1: Detect Source Language and Content Type

Determine the source language and content type from the file path. The site ships 17 active languages today (en, es, pt, zh, ja, de, fr, ko, ru, it, tr, id, vi, hi, pl, uk, th); <lang> below is any of those codes:

Page wrappers under src/pages/ are NOT translated content — they are 3-line routing shells. The default-language wrapper lives at src/pages/<name>.astro and the single dynamic wrapper at src/pages/[lang]/<name>.astro covers every other active language. Page wrappers do not need per-language duplication for translation.

Step 2: Find or Create Target File(s)

Translation fans out from the source to every other active language (not just one target). Use src/lib/i18n.ts getActiveLanguages() as the source of truth.

Map source to target paths:

When invoked for a single content change, prioritize the source-lang → en path first (if the source isn't English), then en → all other active languages, so the canonical English version is correct before downstream propagation. If a target file does not exist, create it using the source as the template; if it exists, update it to match the source structure.

Translation strings ↔ Markdown endpoints: a rendered page and its src/content/pages/<lang>/<page>.md mirror are two views of one surface — the page renders from src/lib/translations/<lang>.ts, the endpoint mirrors it for agents. When a change originates in a <lang>.ts file (for example a faqPage item edit or insertion), update the matching endpoint by deriving it from the already-edited ts file — read the final ts strings and write the endpoint sections to match — rather than translating the markdown in parallel. Derivation guarantees md↔ts parity by construction; parallel translation invites drift. For edits to existing endpoint text, recover the pre-edit version with git show HEAD:<endpoint> and apply a longest-common prefix/suffix diff so only the true delta changes. Match the endpoint's own bytes for locale quirks (for example, the tr endpoint historically uses ASCII ' where the ts uses ’). Verify with pnpm run md:check and pnpm run md:content-check.

Step 3: Translate Content

Translate the content following these rules:

For content docs (methodology / spec / kit / page .md):

• Translate: title, description, and body content
• Preserve exactly: order, lang (set to the target language), structural frontmatter fields, code blocks
• Use natural, idiomatic translations (not literal word-for-word)
• Preserve all markdown formatting, headings, lists, links
• Do NOT translate code blocks, terminal commands, or technical identifiers
• Direct quotes in English: When translating to Spanish and the content includes a direct quote originally in English, keep the original English text in italics and add a Spanish translation in parentheses immediately after. Example: "Express my will to my agents." ("Expresar mi voluntad a mis agentes.")

For page wrappers (.astro in src/pages/):

• Pages use the Page wrapper pattern: thin 3-line wrappers that import a shared *Page.astro component
• Set the correct lang string literal: lang="en" or lang="es"
• The shared component in src/components/pages/ handles MainLayout, translations, and content internally
• When syncing a page, verify both the wrapper and the shared component exist

For translation strings (en.ts/es.ts):

• Find keys that exist in one locale file but not the other
• Add the missing translations maintaining the same nested structure
• Ensure both en.ts and es.ts export objects with identical key structures
• Update src/lib/translations/types.ts if new interface fields are needed
• Quote safety: use ONLY straight ASCII single quotes ' as string delimiters — never curly/typographic quotes (‘ ’ “ ”), which break the build. Escape inner apostrophes as \' (e.g. 'd\'installer'). Run pnpm run biome:check after; a parse error means a stray curly delimiter slipped in.

Step 4: Validate Synchronization

# Check both files exist
ls -la {source_file} {target_file}

# Run code quality checks
pnpm run biome:check
pnpm run astro:check
pnpm run build

Step 5: Prove currency, not just existence (all 17 languages)

pnpm run i18n:check proves that every file exists and uses the right script. It does not prove that a translation carries the current English content: in PLAN_020 four kit command pages passed it while 8–14 languages still held the pre-v7 text. After an English change, check every language against English:

# Same number of ##/### headings as English (a missing section is a stale translation)
python3 - <<'PY'
import glob, os, re
for en in glob.glob('src/content/<collection>/en/*'):
    h = len(re.findall(r'^#{2,3} ', open(en).read(), re.M))
    for f in glob.glob(en.replace('/en/', '/*/')):
        n = len(re.findall(r'^#{2,3} ', open(f).read(), re.M))
        if n != h: print(f, n, 'vs en', h)
PY

Also confirm that each language's file changed in the same commit range as the English edit (git diff --numstat <base>..HEAD -- src/content/<collection>). The frontmatter description must stay within 130–160 characters (60–90 for zh/ja/ko).

Fan-out for large syncs (Claude Code)

For a change that touches many files in all 16 non-English languages, commit the English change first, then give one helper agent four languages each (for example es/pt/fr/it, de/ru/uk/pl, zh/ja/ko/th, tr/id/vi/hi). Each helper applies git show <en-commit> to its own language folders only. The lead reviews the helpers' self-checks, reruns the checks above, commits, and owns the result.

Output Format

Success Output

## Translation Sync Complete

### Source
- File: {source_file}
- Language: {en|es}
- Type: {page|content-doc|translation-strings}

### Target
- File: {target_file}
- Language: {en|es}
- Action: {created|updated}

### Changes
- {list of specific changes made}

### Validation
- Biome check: {pass/fail}
- Astro check: {pass/fail}
- Build: {pass/fail}

### Commit Message
content: sync {content_type} translation for "{identifier}" ({source_lang} -> {target_lang})

Guardrails

Scope Limits

• Maximum files: 10 per invocation
• Maximum LOC: 500

Translation Quality Rules

• Use natural, idiomatic translations (not literal)
• Preserve technical terminology without translation (code terms, product names, URLs)
• Use informal-professional register for Spanish (Colombian Spanish phrasing, consistent with site voice)
• Maintain the same markdown structure and formatting
• CRITICAL — Spanish orthography: ALL Spanish text MUST use correct diacritical marks (ñ, á, é, í, ó, ú). Never write pequeno (→ pequeño), tamano (→ tamaño), analisis (→ análisis), numero (→ número), codigo (→ código), pagina (→ página), ejecucion (→ ejecución), version (→ versión), etc. Run a quick grep check before committing.

Stop Conditions

Stop and ask if:

• Translation quality is uncertain for domain-specific or technical content
• Source file has validation errors or malformed frontmatter
• Content type cannot be determined from the file path
• More than 10 files need synchronization (break into batches)
• Source file contains content that seems incomplete or draft-quality

Definition of Done

• Target file exists with translated content
• Frontmatter structure matches source (for content docs)
• All user-visible text is translated
• Code blocks, commands, and technical content are preserved untranslated
• lang value is correct in target page files
• Spanish text has correct diacritical marks (ñ, accents — no pequeno, tamano, numero, codigo)
• pnpm run biome:check passes
• pnpm run astro:check passes
• pnpm run build passes

Escalation Conditions

Escalate to higher tier if:

• Content requires domain-specific terminology review -> use i18n-guardian agent
• More than 10 files need synchronization -> break into multiple invocations
• Structural changes are needed (new components, new routes) -> escalate to Tier 2
• Translation system architecture needs modification -> escalate to architect agent

Examples

Example 1: Sync a New English Methodology Doc to Spanish

Input:

$SOURCE_FILE: src/content/methodology/en/introduction.md

Actions:

1. Detect: English methodology doc
2. Target: src/content/methodology/es/introduction.md
3. Translate title, description, and body to Spanish
4. Preserve order, set lang: es, keep frontmatter structure
5. Validate and report

Creates: src/content/methodology/es/introduction.md

Example 2: Sync a Modified Spanish Page to English

Input:

$SOURCE_FILE: src/pages/es/about.astro

Actions:

1. Detect: Spanish page
2. Target: src/pages/about.astro
3. Update English page content to match Spanish changes
4. Ensure lang = 'en' in target
5. Validate and report

Updates: src/pages/about.astro

Example 3: Add Missing Translation Strings

Input:

$SOURCE_FILE: src/lib/translations/en.ts
$CONTENT_TYPE: translation-strings

Actions:

1. Detect: English translation file
2. Compare with src/lib/translations/es.ts
3. Find keys present in en.ts but missing in es.ts
4. Add missing translations to es.ts
5. Validate and report

Updates: src/lib/translations/es.ts

Related

• add-page - Create multilingual pages
• add-component - Create components with i18n support
• i18n-guardian agent - Translation quality specialist