> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# XLIFF
> Sync XLIFF 1.2 or 2.x files, review units and inline placeholders, and return translated interchange files.
This tutorial uses XLIFF as the localisation boundary for a backend, content pipeline, or vendor interchange. Hyperlocalise supports `.xlf`, `.xlif`, and `.xliff` files in XLIFF 1.2 and 2.x shapes.
## Prerequisites
You need:
* a build or extraction step that produces XLIFF;
* stable IDs for translation units;
* the [Hyperlocalise CLI](/cli/getting-started/install);
* a Cloud project with `en-US` as source and `fr-FR` and `de-DE` as targets; and
* `HYPERLOCALISE_API_KEY` and `HYPERLOCALISE_PROJECT_ID` in your environment.
The example uses one source and one file per target locale:
```text theme={null}
locales/
├── en-US/messages.xliff
├── fr-FR/messages.xliff
└── de-DE/messages.xliff
```
## 1. Produce stable XLIFF units
An XLIFF 1.2 source file can look like:
```xml theme={null}
Saved filtersHeading on the saved filters pageSaved {name}Confirmation after a user saves a filter
```
Use stable `id`, `name`, or `resname` values. Do not derive IDs from array positions or line numbers.
Keep a `` element in each source unit. During reconstruction, Hyperlocalise preserves `` and writes the translated value into ``.
XLIFF 2.x is supported through `` elements. Keep one translatable segment per unit in the current workflow so one stable unit ID maps to one translation value.
## 2. Map source and targets
Create `i18n.yml`:
```yaml theme={null}
locales:
source: en-US
targets:
- fr-FR
- de-DE
buckets:
backend:
files:
- from: locales/{{source}}/messages.xliff
to: locales/{{target}}/messages.xliff
hyperlocalise:
project_id_env: HYPERLOCALISE_PROJECT_ID
api_base_url: https://hyperlocalise.com/api
api_key_env: HYPERLOCALISE_API_KEY
```
XLIFF is already segmented. Hyperlocalise does not apply SRX sentence splitting to it.
## 3. Check generated XLIFF in the source pull request
Regenerate the source file and compare it with git:
```bash theme={null}
./scripts/export-xliff.sh
git diff --exit-code -- locales/en-US/messages.xliff
hl sync push --dry-run
```
Your export check should reject:
* missing or duplicate unit IDs;
* units without source text;
* invalid XML;
* inline placeholder changes;
* generated IDs that churn after unrelated edits; and
* source units without a target element.
Commit the generated XLIFF with the backend change.
## 4. Push source XLIFF
After merge:
```bash theme={null}
hl sync push
```
Start work through a **Source upload** automation or **New Request**. Cloud presents units by their stable IDs while retaining source content and inline markup.
## 5. Review units and inline placeholders
In **Content Editor**, verify:
* ``, ``, or other inline codes remain in the correct semantic position;
* placeholders such as `{name}` stay unchanged;
* notes provide enough product context;
* adjacent units use consistent terminology; and
* target text does not contain escaped placeholder markup.
Approve each target locale after review.
## 6. Pull translated XLIFF
Run:
```bash theme={null}
hl sync pull
hl check --bucket backend --quiet
```
Hyperlocalise reconstructs each target file from the source structure. For XLIFF 1.2 it preserves `source-language`, sets `target-language`, keeps source text, and replaces target text. For XLIFF 2.x it preserves `srcLang` and sets `trgLang`.
Inline XML markup remains inline rather than becoming plain escaped text.
## 7. Validate and import targets
Open a translation pull request, then validate each target against the schema and your importer:
```bash theme={null}
xmllint --noout locales/fr-FR/messages.xliff
xmllint --noout locales/de-DE/messages.xliff
./scripts/import-xliff.sh locales/fr-FR/messages.xliff
./scripts/import-xliff.sh locales/de-DE/messages.xliff
```
If your toolchain ships an XLIFF schema validator, run it in addition to `xmllint`; well-formed XML alone does not prove that the file follows your XLIFF profile.
Test:
* every expected unit imports;
* target locale metadata is correct;
* inline codes survive the import;
* no source-only fallback appears unexpectedly; and
* the importer rejects missing required targets.
## XLIFF 2.x example
Use one `` per ``:
```xml theme={null}
Heading on the saved filters pageSaved filters
```
Avoid multiple independently translated segments under one unit until your export/import profile has been tested against Hyperlocalise's unit-level mapping.
## Troubleshooting
### Source text changes during pull
Ensure every source unit contains a `` element. Without one, reconstruction may update the source element because no target node exists.
### Units disappear in Cloud
Confirm every `` or `` has a non-empty stable identifier and source text.
### Inline placeholders break import
Compare the source and target inline element sequence. Keep IDs and markup intact, then return the unit to review.
## Next
* [GitHub localisation workflow](/platform/tutorials/github-localisation-workflow)
* [Gettext POT and PO](/platform/tutorials/gettext-pot-po)
* [Content Editor](/platform/cat)