Import translations
On this page
You can import translations from a file. A translation agency can work on an export and send the file back.
Formats you can read#
JSON, XLIFF 1.2, XLIFF 2.x, PO, POT, CSV and TMX 1.4. Read-only importers also exist for Android strings.xml, WebExtension messages.json and simple key-value JSON. Those three need a file in your source language as a reference, so the importer knows which text each key stands for.
How strings are matched#
- By the key in the file, if it is one of ours.
- Otherwise by the text itself. The importer works out the key from the source text, in three spellings of the escapes.
What is checked#
- Language codes are mapped to your site's languages.
- Every tag and placeholder must survive. See Tags and placeholders.
- Duplicates are resolved by a clear rule.
- You get a report with counts and a list of issues.
- If there are errors, nothing is imported. All or nothing.
Imported translations get a state from the file where it has one, otherwise they are saved as manual.
Try first#
Use the dry run. It reads the file and tells you what would change without changing anything. With the command-line tool: rl import fr.xlf --lang fr --dry-run.
Safe by design#
The importer does not follow external entities in XML, limits file size, count, length and depth, accepts only valid text encoding, and removes control characters.
Known gaps#
- Plural forms in PO and Android, translator notes in XLIFF and alternative translations are not modelled. They are skipped or flattened with a note in the report.
- Variables in other formats, like
%1$sor{0}, are not converted into our placeholders. Such strings match only if your source text has the same form. - Import through the web API accepts a file upload (multipart form, field
file, andreferencefor the formats that need one) or the JSON export as a plain JSON body. Import needs thetranslations:writescope.