Content translate

Overview

Translate documents, code comments, UI strings, and structured content between languages while preserving original formatting, adapting terminology to the target domain, and maintaining consistency across large files. This skill handles everything from single paragraphs to multi-file projects by splitting work into coherent batches, tracking terminology across segments, and validating output quality.

Use this skill when:

• Translating documentation, READMEs, or technical guides
• Localizing UI strings, error messages, or API docs
• Translating code comments or inline documentation
• Working with large files that exceed context-window limits
• Adapting content for a specific domain (medical, legal, technical, marketing)

Instructions

1. Pre-Translation Analysis

Before translating any content, analyze the source to determine:

Factor	What to Identify	How to Record
Source language	Detect from content or ask user	Note in translation log
Target language	User-specified or inferred from context	Note in translation log
Domain	technical, legal, medical, marketing, academic, casual	Determine from vocabulary and context
Tone	formal, informal, instructional, persuasive, neutral	Match in target language
Audience	developers, end-users, experts, general public	Adjust complexity accordingly
Format constraints	markdown, code blocks, frontmatter, tables, HTML	Preserve exactly
Key terminology	Domain-specific words that must translate consistently	Build a glossary BEFORE translating

Rule: If the user does not specify source/target language or domain, ASK before proceeding. Do not guess languages or domains.

2. Terminology Glossary (Mandatory for Multi-File or Domain Work)

For any translation involving domain-specific language or multiple batches:

1. Extract key terms from the source before translating
2. Research equivalents in the target language for the identified domain
3. Record decisions in a glossary format:

   TERM (source) → TRANSLATION (target) [domain: X, notes: Y]
   

4. Reference the glossary in every subsequent batch
5. Update the glossary if new terms appear mid-translation

Rule: Never translate the same domain term differently across batches. Consistency trumps literal accuracy.

3. Batching Strategy for Large Files

When a file exceeds safe context-window limits (typically >2000 words or >15000 characters):

1. Split at natural boundaries:

   • Markdown: split at ## or ### headers
   • Code: split at function/class boundaries
   • UI strings: split by screen or feature group
   • Narrative: split at paragraph or scene breaks

2. Never split inside:

   • Code blocks (...)
   • Tables (breaks alignment)
   • Frontmatter blocks (---...---)
   • Numbered lists with cross-references
   • Sentences (split at period + newline, not mid-sentence)

3. Batch size guidelines:

   Content Type	Max Words/Batch	Max Characters/Batch
   Plain text / Markdown	1500	10000
   Technical docs with code	1000	7000
   UI strings / JSON	500	4000
   Legal / Medical	800	6000

4. Overlap strategy: Include the last 1-2 sentences of the previous batch at the start of the next batch to maintain flow and context. Remove duplicates in final assembly.

5. Track batch state:

   Batch X/Y | Section: "Heading Name" | Words: N | Status: translated
   

4. Translation Workflow

Follow this exact sequence for every translation task:

Step 1 — Analyze: Identify language pair, domain, tone, audience, format. Step 2 — Glossary: Extract and define key terminology (skip for trivial <200 word translations). Step 3 — Batch: Split large content into coherent segments. Step 4 — Translate: Process each batch with full context. Step 5 — Assemble: Combine batches, remove overlaps, verify continuity. Step 6 — Validate: Run quality checks (see Section 6). Step 7 — Deliver: Present final translation with glossary if applicable.

5. Format Preservation Rules

Preserve all non-textual elements exactly. Translate ONLY human-readable text.

Element	Rule
Markdown syntax	Keep #, ##, **, *, `, [](url), ![]() unchanged
Code blocks	Do NOT translate code inside ```. Translate ONLY comments (//, #, /* */)
Inline code	Keep `variable_name` unchanged. Translate surrounding text only
Frontmatter (YAML/TOML)	Keep keys unchanged. Translate string values only
HTML tags	Keep <tag attr="value">. Translate text nodes only
URLs	Never translate URLs. Keep https://... as-is
Variables / Placeholders	Keep {name}, %s, {{var}}, $VAR unchanged
Tables	Translate cell contents. Preserve `
Numbered lists	Keep numbers. Translate text. Preserve indentation
Emoji	Preserve emoji. Do not translate to text equivalents unless requested

Rule: If you are unsure whether something should be translated, keep it unchanged and add a translator note [TN: ...].

6. Domain Adaptation

Adapt translation style based on detected domain:

Domain	Approach
Technical / Developer	Use established technical terminology in target language. Keep English loanwords if they are standard (e.g., "debug", "commit", "pull request" in many languages). Prefer official documentation translations.
Legal	Use precise legal terminology. When exact equivalents don't exist, use accepted transliterations or add explanatory notes. Never paraphrase.
Medical	Use internationally recognized medical terms (ICD, anatomical). When translating for patients vs. professionals, adjust complexity.
Marketing	Prioritize emotional impact and cultural resonance over literal accuracy. Adapt idioms, metaphors, and cultural references.
Academic	Maintain formal register. Use discipline-standard terminology. Preserve citation formats.
Casual / UI	Use concise, natural phrasing. Respect character limits if specified. Ensure buttons/labels feel native.

7. Quality Validation Checklist

Before delivering any translation, verify:

• Completeness: Every sentence from the source is present in the target
• Consistency: Key terms are translated the same way throughout
• Accuracy: No meaning is added, removed, or distorted
• Fluency: Target text reads naturally to a native speaker
• Format: All markdown, code, frontmatter, and structure is preserved
• Variables: All placeholders, URLs, and code identifiers are intact
• Numbers/Dates: Formatted correctly for target locale (if applicable)
• Gender/Formality: Correctly matches target language conventions

Rule: If any check fails, flag the issue and re-translate the affected section. Do not deliver partial or unverified translations.

8. Handling Ambiguity

When the source is ambiguous:

1. Choose the most likely meaning based on domain and context
2. Add a translator note: [TN: ambiguous source; translated as "X" meaning Y]
3. If the ambiguity significantly affects meaning, ASK the user for clarification instead of guessing

9. Post-Translation Consistency Review

For multi-batch translations, perform a final pass:

1. Read the assembled translation start-to-finish
2. Check for tone shifts between batches
3. Verify that pronouns and references resolve correctly across batch boundaries
4. Ensure the glossary was applied uniformly
5. Confirm formatting is intact across the entire document

Examples

Example 1: Simple Markdown Document

Source:

# Getting Started

Install the package via npm:

```bash
npm install my-package

Then import it in your code:

import { init } from 'my-package';
init({ apiKey: 'your-key' });

**Target (Spanish, technical domain)**:
```markdown
# Primeros pasos

Instala el paquete mediante npm:

```bash
npm install my-package

Luego impórtalo en tu código:

import { init } from 'my-package';
init({ apiKey: 'your-key' });

**Notes**: Code blocks preserved. Comments would be translated if present. `npm install` command kept as-is (standard CLI).

---

### Example 2: Large File Batching

**Source**: 5000-word technical guide with 12 sections.

**Workflow**:

Analysis: EN → DE, domain: technical/software, tone: formal instructional Glossary: 23 terms extracted (API, webhook, endpoint, payload, etc.)

Batch 1/4: Sections 1-3 (Introduction, Setup, Configuration) — 1200 words Batch 2/4: Sections 4-6 (Authentication, Requests, Responses) — 1150 words Batch 3/4: Sections 7-9 (Error Handling, Rate Limits, Webhooks) — 1300 words Batch 4/4: Sections 10-12 (SDKs, Examples, Changelog) — 1350 words

Overlap: Last sentence of Batch 1 included at start of Batch 2 for context. Assembly: Combined, overlaps removed, TOC regenerated. Validation: All 23 glossary terms consistent. All code blocks intact.

---

### Example 3: Domain-Specific UI Strings

**Source** (medical app, English):
```json
{
  "symptom_checker_title": "Check Your Symptoms",
  "disclaimer": "This tool does not provide medical advice. Consult a doctor for diagnosis.",
  "button_start": "Start Assessment"
}

Target (German, medical domain):

{
  "symptom_checker_title": "Symptome überprüfen",
  "disclaimer": "Dieses Tool ersetzt keine medizinische Beratung. Konsultieren Sie einen Arzt für eine Diagnose.",
  "button_start": "Untersuchung starten"
}

Glossary entry: assessment → Untersuchung [domain: medical, notes: NOT "Bewertung" — medical context requires clinical term]

---

Example 4: Frontmatter Preservation

Source:

title: "Deployment Guide"
description: "How to deploy to production"
author: "DevOps Team"
# Deployment Guide

Target (French):

title: "Guide de déploiement"
description: "Comment déployer en production"
author: "DevOps Team"
# Guide de déploiement

Notes: Keys (title, description, author) preserved. Values translated except author (proper noun).

References

• For right-to-left (RTL) languages: ensure bidirectional text markers are preserved if present in source
• For CJK languages: be aware that word boundaries differ; segment by meaning, not spaces