Localize static content

Map translated documents and catalogs to the files your site or renderer consumes, then verify structure, links, and delivered output.

Your site's source tree already connects articles to routes, metadata, navigation, and a renderer. Add translated files where that system can load them. The first useful result is one complete target-language page at its intended route, with working links and the same code examples as the source.

Inventory files by the system that consumes them #

Separate long-form documents from structured catalogs and specialized resources. Markdown, MDX, and Markdoc need a renderer and schema. JSON, YAML, TypeScript, and PHP catalogs need a loader. PO and XLIFF connect to their own message systems. SRT belongs to a timed-media workflow.

Choose one representative source from each group and identify the output path and loader that will consume it. Keep generated targets outside source patterns. Preserve document IDs, URLs, code examples, catalog keys, and component attributes whose values control behavior.

Use Formats to select the actual handler. Ordinary YAML differs from locale-root YAML and OpenAPI YAML. .xml does not identify an Android resource automatically. A shared extension is not proof that a handler understands your document's structure.

Match the site's directory convention #

These are layout choices to confirm against your project's loader:

SiteWhat to establish before translation
DocusaurusWhich source docs become files under i18n/<locale>/docusaurus-plugin-content-docs/current/, and which versioned docs or theme strings have separate inputs.
NextraWhether the installed setup loads per-locale pages, dictionaries, or another content tree; map each input separately.
HugoWhich files under content/<locale>/ belong to the same translated content identity and how language links are resolved.
AstroWhich locale-specific content collections and UI dictionaries feed each route.
VitePressWhich locale directory prefix and navigation configuration generate the translated pages.
MkDocsWhich i18n plugin and per-locale docs layout the installed project uses.

For a Docusaurus example with source documents under docs/, install and link the CLI from the project root:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo link

Retain the organization and localization engine IDs in .lingo/config.json. Because these source paths contain no locale, replace the file entry with an explicit output template:

json
{
  "pattern": "docs/**/*.md",
  "sourceRoot": "docs",
  "targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}

For docs/setup/install.md, [path] becomes setup/install.md, so Spanish output goes to i18n/es/docusaurus-plugin-content-docs/current/setup/install.md. Confirm that the installed plugin and version consume that directory. Configuration explains template validation and collision rules.

Translate visible document fields deliberately #

For Markdown, select the frontmatter that readers see, such as title and description. Keep identity and publication metadata unchanged. For MDX and Markdoc, also identify reader-facing component props, such as a callout title. Behavioral props and component names belong to the application schema.

Use the proper handler rather than assuming every Markdown-family file is interchangeable. A Markdoc document stored as .md needs an explicit markdoc format to receive Markdoc handling. Check Markdown, MDX, and Markdoc for selection and reconstruction limits. Preserve code fences as executable evidence; translate the explanation around them instead of changing commands.

Run a missing-file backfill:

sh
lingo push --backfill-missing --wait

After completion, build the site and open the generated target route. Check the title, description, body, custom components, code block, and a link. If heading IDs derive from text, follow translated fragment links explicitly. A preserved URL still needs an existing destination. The Markdoc with Next.js guide gives a locale-specific loading example.

Keep structured catalogs within their contracts #

Translate JSON and generic YAML string values while protecting IDs, endpoints, and other non-language data with the handler's key controls. Set format: "yaml" explicitly for generic YAML in the current CLI's source configuration: extension inference alone does not make an unconfigured YAML source eligible for push. Use yaml-root-key when the locale is the root key, and yaml-openapi when the structure is an OpenAPI document. Keep TypeScript and PHP within their supported catalog forms; translating a file does not evaluate arbitrary source code safely.

For PO, retain message identities, context, plural structure, and the compilation step the destination uses. For XLIFF, preserve the supported variant's source/target and placeholder structure. Verify the actual consumer's import or build rather than only checking that an output file exists.

Plain .txt files, such as app store descriptions, are translated line by line and keep the source's lines. Name .txt in the files pattern, as in metadata/en/*.txt, or set "format": "txt": a broad pattern such as docs/en/**/* does not select them. See Plain text. A CSV table with one column per locale is translated in place: name .csv in the pattern or set "format": "csv", as CSV describes. The current CLI does not expose one CSV file per locale, WebVTT, or Java .properties as configurable formats. The CLI v0 format reference serves installed users of those older workflows; its commands and configuration are version-specific. Use the migration reference to choose a supported path without silently dropping those resources.

Inspect subtitles with the media #

For SRT, translate the cue text and compare cue indices and timing against the source. Play representative scenes with the target subtitles. Verify reading length, line breaks, speaker context, and formatting tags through the actual player. Preserved timestamps do not prove a translated cue is readable within its interval. See SubRip for the file contract; do not substitute WebVTT because both are subtitle formats.

Scale from the proven delivery path #

Keep configuration, sources, accepted targets, and the CLI lockfile together. After changing a paragraph, use lingo push --wait for the normal delta, then compare that paragraph and an unchanged section in the target. Keep the previous source paired with its target; reorganized document structures can make reuse ambiguous. A positional pattern uses different scoped-planning semantics. Use the estimate workflow before broad retranslation, treating estimates as planning information rather than price quotes.

When local target corrections need divergence protection, submit without --wait and inspect lingo pull --dry-run before retrieval; direct waiting writeback lacks that gate. Follow Preserve reviewed translations.

Choose the GitHub App or CI recipes once one group builds correctly. Keep the site's build, schema validation, link checks, and content review in that cycle; lingo check does not establish document completeness. Each update should leave a readable target page and a source revision the team can use for the next change.