Translating Documentation
Overview
Define the technical-document surface around a translation. Preserve executable examples, identifiers, references, and document topology while exposing explanatory prose with enough technical context for accurate translation.
Capabilities
surface:documentationcode-preservationtechnical-terminology
Input Inspection
Parse the whole document and inventory:
- format, frontmatter, headings, paragraphs, lists, tables, admonitions, footnotes, and generated regions
- code fences, inline code, commands, prompts, output, placeholders, variables, identifiers, API methods/paths, schemas, enums, and example data
- internal/external links, anchors, reference definitions, includes, citations, image/media paths, and cross-references
- diagrams, node IDs, edges, syntax, display labels, captions, and alt text
- source and target locale, audience expertise, product/version scope, technical glossary, protected terms, style guide, and publication constraints
Determine whether a code comment, sample value, diagram label, or inline span is executable, user-facing, or both. When uncertain, protect it and ask the technical owner for its contract.
Translation Surface
Send explanatory prose, headings, table prose, admonitions, captions, meaningful alt text, link labels, and confirmed display-only diagram labels to translating-core. Attach the surrounding section, audience, concept definition, approved technical glossary, protected-token inventory, and reference target.
Translate code comments or display-only sample values only when the brief explicitly authorizes them and their executable effect is understood. This skill does not generate target prose, choose technical terminology beyond approved inputs, or apply language mechanics.
Non-Translatable Elements
Preserve byte-for-byte unless an authoritative technical change is separately approved:
- code fences and language labels, inline code, commands, flags, prompts, environment variables, placeholders, and identifiers
- API methods, paths, versions, parameters, schemas, property names, enum values, response values, and protocol literals
- URLs, link destinations, anchors, reference IDs, include paths, citation identifiers, image paths, and generated markers
- diagram syntax, node IDs, edges, classes, attributes, and identifiers
- product names and protected technical glossary terms
Translate a link label, not its destination. Translate a diagram's confirmed display label, not its node identity or connectivity. Never “fix” an API detail, command, or example because it looks outdated during localization.
Documentation Constraints
- Preserve document topology: heading levels/order, lists, table shape, callout type, code/inline boundaries, references, media, and diagrams.
- Keep each executable example runnable and semantically equivalent. Do not translate a literal token merely because readers can see it.
- Apply the approved technical glossary consistently by concept and context. Record a missing term as a draft terminology decision for core/domain ownership; do not silently coin an approved term.
- Keep references resolvable. A localized link or anchor requires a verified mapping supplied by documentation ownership; otherwise retain the source destination.
- Keep prose and examples aligned: parameter names, return fields, sequence, prerequisites, outcomes, and version scope must agree.
- Preserve deliberately mixed-language technical terms and distinguish them from accidental untranslated prose.
Targeted Research
Research only technical facts that may be current and materially affect the document: the documented product version, endpoint, CLI flag, schema, enum, behavior, localized reference mapping, or official component name. Prefer authoritative version-matched product documentation, source code, or release notes and record the source/version/date.
Treat a verified technical correction as a separate documentation change owned by engineering/documentation, not as translation. Do not research ordinary target wording, infer API migrations, or rewrite an example before that change is approved in the source.
Authority and Conflict Boundary
Follow explicit user requirements, approved technical/product configuration, core semantic fidelity, domain terminology, and language mechanics before documentation formatting preferences. Engineering owns executable behavior and technical facts; documentation owners own structure, reference maps, examples, and publication configuration.
This skill owns document field classification, protected technical structures, reference/example constraints, and documentation QA. translating-core owns meaning and target prose; installed domain/language specialists own terminology and linguistic mechanics; reviewing-translations owns final review. If natural prose conflicts with an exact identifier, code example, or approved glossary term, preserve the technical contract and report the affected segment.
QA Handoff
Pass source and target documents, locale pair, product/version scope, technical glossary, protected-token inventory, reference map, executable examples, diagram manifest, and these checks to reviewing-translations:
- protected-token diff confirms code fences, inline code, commands, flags, variables, identifiers, API/schema literals, URLs, anchors, paths, diagram IDs, and protected names retain parity
- document parser confirms headings, lists, tables, callouts, links, references, code blocks, media, and generated markers preserve topology
- examples parse, compile, or run using the project's safe documented test method; JSON/YAML/XML and command syntax remain valid
- link and anchor checks confirm internal and external cross-references resolve to approved destinations
- diagram renderer confirms valid syntax, unchanged nodes/edges, and complete translatable display labels
- glossary, concept, parameter, return-value, prerequisite, and version references remain consistent across prose and examples
- no accidental untranslated prose or full-width/localized characters enter protected literals
Block publication for broken executable content, changed technical behavior, corrupted identifiers, unverified version/API correction, broken cross-reference, altered diagram connectivity, glossary conflict, or accidental mixed-language prose. Route the exact affected span or enclosing example to its responsible installed skill.
1---2name: translating-documentation3description: Use when localizing technical documentation while preserving code, commands, identifiers, diagrams, references, and technical terminology for guides, API references, READMEs, and developer documentation.4---56# Translating Documentation78## Overview910Define the technical-document surface around a translation. Preserve executable examples, identifiers, references, and document topology while exposing explanatory prose with enough technical context for accurate translation.1112## Capabilities1314- `surface:documentation`15- `code-preservation`16- `technical-terminology`1718## Input Inspection1920Parse the whole document and inventory:2122- format, frontmatter, headings, paragraphs, lists, tables, admonitions, footnotes, and generated regions23- code fences, inline code, commands, prompts, output, placeholders, variables, identifiers, API methods/paths, schemas, enums, and example data24- internal/external links, anchors, reference definitions, includes, citations, image/media paths, and cross-references25- diagrams, node IDs, edges, syntax, display labels, captions, and alt text26- source and target locale, audience expertise, product/version scope, technical glossary, protected terms, style guide, and publication constraints2728Determine whether a code comment, sample value, diagram label, or inline span is executable, user-facing, or both. When uncertain, protect it and ask the technical owner for its contract.2930## Translation Surface3132Send explanatory prose, headings, table prose, admonitions, captions, meaningful alt text, link labels, and confirmed display-only diagram labels to `translating-core`. Attach the surrounding section, audience, concept definition, approved technical glossary, protected-token inventory, and reference target.3334Translate code comments or display-only sample values only when the brief explicitly authorizes them and their executable effect is understood. This skill does not generate target prose, choose technical terminology beyond approved inputs, or apply language mechanics.3536## Non-Translatable Elements3738Preserve byte-for-byte unless an authoritative technical change is separately approved:3940- code fences and language labels, inline code, commands, flags, prompts, environment variables, placeholders, and identifiers41- API methods, paths, versions, parameters, schemas, property names, enum values, response values, and protocol literals42- URLs, link destinations, anchors, reference IDs, include paths, citation identifiers, image paths, and generated markers43- diagram syntax, node IDs, edges, classes, attributes, and identifiers44- product names and protected technical glossary terms4546Translate a link label, not its destination. Translate a diagram's confirmed display label, not its node identity or connectivity. Never “fix” an API detail, command, or example because it looks outdated during localization.4748## Documentation Constraints4950- Preserve document topology: heading levels/order, lists, table shape, callout type, code/inline boundaries, references, media, and diagrams.51- Keep each executable example runnable and semantically equivalent. Do not translate a literal token merely because readers can see it.52- Apply the approved technical glossary consistently by concept and context. Record a missing term as a draft terminology decision for core/domain ownership; do not silently coin an approved term.53- Keep references resolvable. A localized link or anchor requires a verified mapping supplied by documentation ownership; otherwise retain the source destination.54- Keep prose and examples aligned: parameter names, return fields, sequence, prerequisites, outcomes, and version scope must agree.55- Preserve deliberately mixed-language technical terms and distinguish them from accidental untranslated prose.5657## Targeted Research5859Research only technical facts that may be current and materially affect the document: the documented product version, endpoint, CLI flag, schema, enum, behavior, localized reference mapping, or official component name. Prefer authoritative version-matched product documentation, source code, or release notes and record the source/version/date.6061Treat a verified technical correction as a separate documentation change owned by engineering/documentation, not as translation. Do not research ordinary target wording, infer API migrations, or rewrite an example before that change is approved in the source.6263## Authority and Conflict Boundary6465Follow explicit user requirements, approved technical/product configuration, core semantic fidelity, domain terminology, and language mechanics before documentation formatting preferences. Engineering owns executable behavior and technical facts; documentation owners own structure, reference maps, examples, and publication configuration.6667This skill owns document field classification, protected technical structures, reference/example constraints, and documentation QA. `translating-core` owns meaning and target prose; installed domain/language specialists own terminology and linguistic mechanics; `reviewing-translations` owns final review. If natural prose conflicts with an exact identifier, code example, or approved glossary term, preserve the technical contract and report the affected segment.6869## QA Handoff7071Pass source and target documents, locale pair, product/version scope, technical glossary, protected-token inventory, reference map, executable examples, diagram manifest, and these checks to `reviewing-translations`:7273- protected-token diff confirms code fences, inline code, commands, flags, variables, identifiers, API/schema literals, URLs, anchors, paths, diagram IDs, and protected names retain parity74- document parser confirms headings, lists, tables, callouts, links, references, code blocks, media, and generated markers preserve topology75- examples parse, compile, or run using the project's safe documented test method; JSON/YAML/XML and command syntax remain valid76- link and anchor checks confirm internal and external cross-references resolve to approved destinations77- diagram renderer confirms valid syntax, unchanged nodes/edges, and complete translatable display labels78- glossary, concept, parameter, return-value, prerequisite, and version references remain consistent across prose and examples79- no accidental untranslated prose or full-width/localized characters enter protected literals8081Block publication for broken executable content, changed technical behavior, corrupted identifiers, unverified version/API correction, broken cross-reference, altered diagram connectivity, glossary conflict, or accidental mixed-language prose. Route the exact affected span or enclosing example to its responsible installed skill.
BrunoMiguens