How to Translate Technical Docs Without Breaking Code

TABLE OF CONTENTS

Technical documentation is unforgiving: a single broken code fence, placeholder, or anchor can break builds, confuse readers, or cause copy‑paste failures. This guide gives you a repeatable, safe workflow to translate tech docs with confidence—while keeping code intact and docs shippable.

Who this is for: technical writers, dev advocates, and translators working on developer docs, API guides, and README‑style content.

At a glance:

Understand what must never be translated (code, keys, tokens)
Preserve syntax that tools parse (fences, braces, anchors)
Validate structured data and links after edits
Use automation to catch issues before release

Pre‑Translation Prep

Inventory content types

Markdown (headings, links, tables), code blocks, inline code
Structured data: JSON/YAML/TOML snippets and config files
Screenshots, diagrams, and embedded visuals

Define non‑translatable tokens

File paths, package names, imports, API names, CLI flags, env vars
Placeholders and variables: {count}, %s, $HOME, {{token}}
Filenames and extensions: config.yaml, .env, .md, .json

Establish consistency guardrails

Glossary/termbase for domain terms and product names
Style guide: tone, formality, punctuation, casing, headline rules
Anchor/slug strategy per locale (stable vs localized)

Set up safe validation

Staging build to validate Markdown/links after each batch
Parsers/linters for JSON/YAML/TOML
Link checker and anchor validator in CI

Core Safeguards

Do not translate code, identifiers, keys, filenames, env vars, or flags.
Preserve punctuation and syntax that tools parse (backticks, braces, pipes).
Keep significant whitespace: indentation for code and list structure.
Use fenced code blocks with a language tag consistently (js, bash, etc.).
Prefer translator notes over “fixing” code logic—flag issues to maintainers instead.

Code Blocks and Inline Code

Keep code fences, language hints, and content intact. Translate only comments and human‑readable strings if required.

Example—safe vs unsafe:

// SAFE: Only the comment is localized
// Obtains a user token
import { getToken } from "@acme/sdk";
const token = await getToken();

// UNSAFE: Do not translate identifiers/imports/package names
// import { obtenirJeton } from "@acme/sdk"; // ❌

Inline code must stay verbatim:

Good: “Run npm install -g acme-cli and then acme login.”
Bad: “Run npm install -g acme-cli and then acme connexion.” ❌

Validate copy‑pasteability: If a reader copies any snippet, it should run as in the source.

Placeholders and ICU MessageFormat

Preserve placeholders exactly, including spacing and punctuation around them.

# Do not alter tokens or spacing
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ adds spaces inside braces

ICU example:

{count, plural,
  =0 {No messages}
  one {# message}
  other {# messages}
}

Do not change keys (count, one, other).
Translate only the human‑readable parts (“message”, “messages”).
Do not introduce or remove plural categories without product guidance.

Links, Anchors, and Slugs

Keep Markdown link syntax and resolve strategy consistent.

[Read the API guide](/api/getting-started)  
[See the config section](#configuration)

Translate link text if needed; be cautious with URLs and anchors.
Anchors: either keep stable anchors across locales or generate per‑locale anchors and update references accordingly.
Verify relative paths and hash anchors still resolve after translation.
Do not translate file extensions or query params.

Structured Data (JSON/YAML/TOML)

Translate values only—never keys, types, or structure. Always re‑parse after editing.

JSON:

{
  "title": "User Guide",
  "cta": "Get Started",
  "limits": { "max": 5, "unit": "requests/second" }
}

Keys like title, cta, limits, max must remain unchanged.
Numbers, booleans, and nulls stay as types, not words.

YAML (watch folded scalars):

note: >
  Lines are folded into a single paragraph.
  Keep indentation and markers intact.

Preserve quoting, escapes, indentation, and trailing commas (where applicable).

Filenames, CLI, and API Names

Do not translate filenames, package names, endpoints, or CLI flags.
Keep case sensitivity exactly as in source (e.g., --DryRun vs --dry-run).
Maintain commands verbatim; add callouts if locale‑specific differences exist.

# Correct
kubectl get pods --namespace default

# Wrong (flag translated) ❌
kubectl get pods --nom-espace defaut

Markdown Gotchas

Tables: keep pipes and alignment; do not break columns.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

Admonitions/notes: retain markers used by your tooling.
Inline HTML: avoid touching tags/attributes.
Footnotes: keep ids and order.
Smart quotes: prefer straight quotes inside code contexts.

Visuals and Accessibility

Localize alt text for meaning, not pixel content.
Prefer locale‑agnostic screenshots (highlight UI not language), or provide per‑locale sets.
Keep diagram source files (e.g., Mermaid) in sync across locales.
Avoid embedded text in images; externalize captions and labels.

SEO and Metadata

Translate titles, descriptions, and headings using locale‑appropriate keywords.
Keep canonical URLs and hreflang consistent with site rules.
Do not translate meta/property keys or JSON‑LD keys.
Align slugs with your anchor strategy to avoid 404s.

Workflow and Automation

Use a CAT/LLM workflow that preserves code spans and tags.
Lock terminology with a glossary and a do‑not‑translate list.
Add pre‑commit hooks to lint Markdown and validate JSON/YAML.
Run a link checker and anchor validator on every PR.
Batch changes in small, reviewable chunks and track diffs.

Suggested tooling (adapt to your stack):

Markdown linting and link check in CI
JSON/YAML parsing step to catch syntax regressions
Regex packs to scan placeholders and numeric formats

QA and Validation

Run these checks before merge:

Build the site to catch syntax issues: pnpm build
Type/content checks (Astro content collections): pnpm astro check
Preview and spot‑test key pages: pnpm preview
Validate code samples compile or run (where applicable)
Run a link and anchor checker; fix any 404s or broken hashes

Common Pitfalls

Translating keys/placeholders by accident.
Breaking code fences or table pipes.
Localizing file paths, flags, or API names.
Changing headings without updating anchor links.
Introducing smart quotes inside code or JSON.

Appendix: Quick Checklists

Pre‑flight (5 items)

Glossary and do‑not‑translate list ready
Tokens/placeholders defined and protected
Anchor/slug strategy confirmed
Link targets mapped (internal vs external)
Staging build available

Code sample safety (5 items)

Fences and language hints intact
Identifiers/imports untouched; comments localized only
Placeholders and quoting preserved
Copy‑paste test passes
Outdated snippets flagged to maintainers

Structured data (5 items)

Keys and types untouched
Quotes/escapes/indentation preserved
Numbers and booleans remain as types
Parser/linter passes locally
Diffs reviewed for accidental key changes