Translate XLIFF files with Hyperlocalise

​

Source file

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2">
    <file source-language="en-US" target-language="es-ES" datatype="plaintext" original="messages">
        <body>
            <trans-unit id="welcome">
                <source>Welcome</source>
                <target></target>
            </trans-unit>
        </body>
    </file>
</xliff>

​

Configure your files

locales:
    source: en-US
    targets:
        - es-ES

buckets:
    messages:
        files:
            - from: locales/en-US/messages.xlf
              to: locales/{{target}}/messages.xlf

llm:
    profiles:
        default:
            provider: openai
            model: gpt-5.2

​

Translate

hyperlocalise run --dry-run
hyperlocalise run

​

Behavior and limitations

• You can translate XLIFF 1.2 trans-unit elements, including segmented seg-source markers, and XLIFF 2.x segment elements inside unit. Hyperlocalise leaves XLIFF 2.x ignorable content unchanged.
• A single-segment unit keeps its unit key: id, then name, then resname. For multiple segments, you get unit-key#segment=segment-id keys with a URL-escaped segment ID. In XLIFF 1.2, Hyperlocalise uses each marker’s mid. For XLIFF 2.x segments without IDs, you get unit-key#segment-index=1, unit-key#segment-index=2, and so on.
• Assign stable segment IDs so your keys stay consistent when you reorder segments. Hyperlocalise CLI reuses a target template only when its keys still refer to the same source content. It aligns existing anonymous-segment translations by source within their unit and reports an error when a match is ambiguous.
• Hyperlocalise reads a non-empty target for each segment and falls back to that segment’s source. For a first translation, use source catalogs with empty targets.
• When Hyperlocalise writes translations, it updates existing targets or creates missing ones and keeps your source text. It preserves untouched XML bytes, namespace prefixes, target attributes, comments, and metadata. If a segmented XLIFF 1.2 unit has no target, Hyperlocalise copies the seg-source structure and updates the translated markers. If an existing target lacks matching markers, you get an error instead of guessed segment boundaries.
• Keep inline code identities, attributes, and native code payloads the same as the source. You can move standalone codes and complete opening/closing pairs, but each opening code must stay before its matching closing code. You cannot make pairs overlap unless they already overlap in the source. You cannot add inline elements when the source contains only text. If you send malformed or changed inline codes, you get an error. Hyperlocalise escapes plain-text replacements with XML-special characters when they are not valid XML fragments.
• If your file has duplicate unit or segment keys, you get an error. You also get an error when you send a unit-level value for a multi-segment unit. Translate each segment independently.
• Multi-segment keys differ from the previous combined unit key. Your first run after upgrading may translate those segments again and write new segment-level lockfile entries.

​

Next steps

• Check translations before committing generated files.
• Local translation workflow explains repeat runs.
• Browse all file formats.

​

Related formats

• gettext PO
• Qt Linguist TS
• XML localization