HTML
Translate HTML text and attributes while preserving untouched source and setting the document language to the target locale.
HTML puts readable text inside a structure that also carries links, behavior, and accessibility information. The html handler selects supported text runs and descriptive attributes, then patches their translations into the original source for one target locale. It does not split a multilingual page into separate locale regions.
Keep the input's document shape #
Documents retain their original doctype and explicit elements. Fragments stay fragments: translation does not add <html>, <head>, or <body> wrappers. Comments, untouched attributes, quote styles, and whitespace outside translated spans remain as written in the source.
An explicit <html> element has its existing lang value replaced with the target locale, or receives a lang attribute if it has none. For example, <html lang="en"> becomes <html lang="fr"> for French. A fragment without an explicit <html> element does not receive one just to carry the language.
For example, this fragment contains visible copy and accessibility text:
<section>
<h2>Delivery options</h2>
<p>Read the <a href="/delivery">delivery policy</a>.</p>
<img src="/truck.svg" alt="Delivery truck" />
<input placeholder="Enter your address" aria-label="Delivery address" />
</section>The heading, paragraph, link label, image alternative text, input placeholder, and ARIA label are supported text. The link destination and image source remain structural properties. Translating this fragment does not create localized links or replace image assets.
Attribute and region selection #
Supported built-in attributes include alt and title on images, placeholder and title on inputs and textareas, selected title attributes, meta content, and visible ARIA labels. Audit metadata carefully: selecting an attribute by name does not establish that every value is prose. Configured component-property rules can add attributes for named elements.
Script, style, preformatted code, code, math, template, noscript, and textarea contents stay outside ordinary text extraction. A skipped element can still have a supported descriptive attribute. SVG uses a dedicated selection for supported title, desc, and text content rather than translating arbitrary drawing data.
Inline markup and {{...}} tokens are protected with placeholders during text translation. Reconstruction restores them in the translated spans. Check the result's element structure and render its variables with representative application values.
Reuse and source-preserving output #
The previous source and target must have corresponding text and placeholder structure for reuse. When matching blocks, the handler ignores whitespace between them and spacer blocks that have no translatable content. It can reject an ambiguous pair. Keep the accepted target associated with its source revision rather than comparing unrelated rendered pages.
Only translated spans and the explicit <html> element's language attribute change; untouched source is copied directly into the result. The handler does not sanitize untrusted HTML. Preserve your application's own security and rendering checks.
If malformed nesting makes the parser combine text across unrelated markup, the handler rejects the document instead of writing an ambiguous target. Correct the nesting and retry. Valid omitted HTML tags do not require adding document scaffolding.
Configure HTML files in the CLI or GitHub App #
The CLI and GitHub App infer html from .html and .htm. Select source files in .lingo/config.json, keeping generated targets outside the source patterns:
{
"sourceLocale": "en",
"targetLocales": ["fr"],
"files": [
{ "pattern": "pages/en/**/*.html", "format": "html" },
{ "pattern": "pages/en/**/*.htm", "format": "html" }
]
}The explicit format is optional for these extensions. Link the project to your organization and localization engine using CLI configuration, or supply the engine for the GitHub App. Each target is a separate locale file, such as pages/fr/index.html. HTML does not support key-scoped translation.
After retrieval, render the document or fragment in its consumer. Compare links and non-text attributes, and inspect accessibility text alongside visible copy. If a CMS supplies the HTML, use that connector's field-selection and writeback instructions; connectors can accept different inputs even when HTML processing is part of their implementation.