Docs · Reference
File formats
Localization OS reads 87 file formats under 151 file extensions. Every one goes through the same upload, translate, review and export path, and comes back in its own format.
How formats work#
Every format goes through the same path: the file is parsed into segments, the segments are translated, reviewed and checked like any other, and the export rebuilds the file in its own format. Translation memory, glossaries, workflows, the editor and quality checks behave the same for all of them. The rules that hold for every format:
- Untouched means byte-identical. Exporting a file into a language that has no translation returns your upload exactly as it was. A translated file keeps its line endings, byte-order mark and, where the text fits, its original encoding. See Encodings.
- Structure is never translated. Keys, identifiers, code, placeholders and markup are kept as protected tags or left out of the segment, and a translation that drops or damages one is held for review.
- Vendor work is protected. In bilingual files, a segment that is locked, approved or already confirmed is never overwritten, and an untranslated segment stays empty rather than being filled with source text.
- Refusals are explicit. A file that cannot be handled safely is refused with a plain reason, often with a line number, and nothing is stored. Nothing is ever executed, fetched or expanded from inside a file.
- The target language is declared. Wherever a format carries a language field, the export sets it to the target language.
The live list for a given install is always available from GET /api/formats. The table below is the list for the current release: 87 formats under 151 file extensions.
Office and desktop publishing#
| Format | Extensions | What is translated, and notes |
|---|---|---|
| Microsoft Word | .docm, .docx, .dotm, .dotx | Body text, tables, footnotes and picture alt text, with formatting kept as inline tags. Macro and template variants keep their macros and file type; a file with macros under a macro-free name is refused (rename it .docm). Strict Open XML stays Strict. Comments follow the project's Translate comments option. An Articulate Storyline "Export to Word" file is recognised and only its Translation column is filled. |
| Microsoft Excel | .xlsm, .xlsx, .xltm, .xltx | String cells plus text boxes and shapes, written into your own workbook: formulas, numbers, dates, pictures (EMF and WMF too), charts, data validation and printer settings come back as uploaded, and macros are kept. Notes and threaded comments follow the Translate comments option. A column mapping turns a sheet into source and target columns (see the CSV row). For a right-to-left target every sheet is set right to left. |
| Microsoft PowerPoint | .potm, .potx, .ppsm, .ppsx, .pptm, .pptx | Text boxes, tables, grouped shapes, SmartArt, chart titles, speaker notes and hidden slides, then picture and shape alt text. Slide layouts, masters and chart data labels are not translated. Comments follow the Translate comments option. |
| OpenDocument text | .odt, .ott | Body text, headings, lists, tables, footnotes and endnotes, text boxes, headers and footers. Bold, italic and links are inline tags; fields, bookmarks and images stay in place. Tracked deletions are not translated; annotations follow the Translate comments option. Password-protected files are refused. |
| OpenDocument spreadsheet | .ods, .ots | Text cells only: formulas, numbers and dates are left alone. Sheet names are not translated. For a right-to-left target every sheet is set right to left. |
| OpenDocument presentation | .odp, .otp | Slide text and speaker notes. Slide masters are not translated. |
| OpenDocument drawing | .odg, .otg | Drawing text. Image alt text is not translated. |
| Microsoft Visio | .vsdm, .vsdx | Page names, shape text (group shapes included) and shape data labels; text fields stay where the translation puts them. Master shapes and macros come back untouched. Comments follow the Translate comments option. Legacy .vsd and .vdx are not read. |
| Adobe InDesign Markup | .idml | Every visible story, including table cells, footnotes, endnotes and hyperlink text. Text under a hidden condition, notes, tracked deletions and stories on non-printing layers stay as they are; spreads, styles, images and fonts come back byte for byte. Right-to-left targets get right-to-left paragraphs and the World-Ready composer. Open the result in InDesign to fix overset text. |
| Adobe InCopy (and WoodWing articles) | .icml, .wcml | The story translates exactly like an IDML story; styles, swatches and every untranslated story come back byte for byte. |
| Adobe FrameMaker MIF | .mif | MIF 8 and later. Every paragraph is one segment; variables, cross-references, markers and font changes are protected. Export sets the paragraph and character language. MIF 7 and older and MIF book files are refused. Marker text, variable definitions and text in graphics are not translated yet. |
| QuarkXPress Tags | .tag, .xtg | Each paragraph is one segment; attribute tags, style sheets and special characters are protected. The file is written back in the encoding its header names, switching to UTF-8 only when the translation needs it. Rename a tagged .txt export to .xtg first. |
.pdf | The digital text layer, or vision OCR for scanned pages (any vision-capable engine, including a local model). The translated PDF is rebuilt and tagged with the target language; it is not certified PDF/UA. | |
| AutoCAD DXF | .dxf | ASCII DXF only (binary DXF is refused). TEXT, MTEXT, attribute values and prompts, dimension text overrides and multileader text. Layer and block names, tags, styles and handles never change. Fonts are not changed: pick a text style font that has the target script. |
Web, markup and publishing#
| Format | Extensions | What is translated, and notes |
|---|---|---|
| HTML and XHTML | .htm, .html, .xhtml | Text between tags with full inline-tag fidelity; scripts and styles are untouched. Image alt text, titles and aria-labels are their own segments. Export sets lang and dir to the target language. A translated attribute can never add an event handler. |
| PHP | .php | Read as a page template (code blocks are never translated or run and come back byte for byte) unless the file is a PHP language array (Laravel lang files, CodeIgniter $lang): then every string value is a segment and keys stay. The file is tokenised, never executed; anything that is not a static literal refuses the file with a line number. |
| PHP page template | .phtml | Translated like HTML; code blocks are never translated or run. |
| JavaServer Pages | .jsp, .jspf | Translated like HTML; scriptlets, expressions and ${...} come back byte for byte. |
| ASP.NET pages and controls | .ascx, .aspx | Translated like HTML; <% %> blocks come back byte for byte. |
| Ruby ERB templates | .erb | Translated like HTML; <% %> blocks come back byte for byte. Razor .cshtml is not covered yet. |
| Server-side includes | .shtm, .shtml, .stm | Translated like HTML; <!--#... --> directives come back byte for byte. |
| Markdown | .markdown, .md, .mdown, .mkd | Prose, headings and lists; code stays as it is. In front matter only text keys such as title and description are translated. Link reference labels and URLs are never translated. |
| MDX | .mdx | Markdown rules for prose. Imports, exports and JSX-only lines are left alone; inline components and {expressions} are protected tags. Only a short list of component attributes (alt, aria-label, caption, label, placeholder, title) is translated. |
| AsciiDoc | .adoc, .asc, .asciidoc | Paragraphs, titles, list items, admonitions and table cells. Listing, literal and passthrough blocks and attribute entries stay; include:: lines are kept and never followed. Export sets :lang:. An OpenPGP .asc file is refused. |
| reStructuredText | .rest, .rst | Paragraphs, titles, lists, admonitions, footnotes and table cells; literal blocks and directives stay. Title underlines are resized, and a table cell that cannot fit its column refuses the export with the cell named. Includes are never followed. |
| LaTeX | .latex, .ltx, .tex | Body text, sectioning titles, captions, item labels and the text of common inline commands; the preamble (except the title), math, verbatim blocks and label, ref and cite keys stay. Special characters in a translation are escaped. Includes are never followed. |
| MediaWiki | .mediawiki, .wiki, .wikitext | Headings, paragraphs, lists, table cells and link labels. Link targets, templates, nowiki and code blocks, magic words and categories stay as they are. Template parameters are translated only when the install lists them. |
| DokuWiki | .dokuwiki | Like MediaWiki. A DokuWiki page is a .txt file on disk, so rename it to .dokuwiki before uploading. |
| XML | .xml | Generic XML is translated in place by W3C ITS 2.0 rules, including rules written inside the file. Android strings.xml and Java XML properties are recognised as software resources. A file that holds the same text in several languages as sibling nodes is recognised as multilingual XML: each export fills that language's sibling and leaves the others alone. A DTD internal subset is refused; the DOCTYPE is never resolved. |
| DITA topics and maps | .bookmap, .dita, .ditamap | Bundled DITA rules: code, draft comments and conref elements stay untranslated; navtitles, map titles and image alt text translate. A map is one file; upload its topics separately. |
| DocBook 4.5 and 5 | .dbk, .docbook | Bundled DocBook rules: program listings, screens and remarks stay untranslated. Export declares the target language on the root. |
| XSL and XSLT stylesheets | .xsl, .xslt | The text a stylesheet writes to its output, plus alt, title, placeholder and aria-label attributes of output elements. XPath, variables, messages and xsl:* attributes are never translated. |
| Email messages (MIME) | .eml | The Subject and every text body part that is not an attachment. Other headers, attachments and the multipart structure come back byte for byte. Links and remote images are never fetched. Signed or encrypted mail is refused; Outlook .msg is not supported (save as .eml). |
| EPUB 2 and 3 | .epub | Title, description, every chapter in reading order and the table-of-contents labels; CSS, fonts and images are copied untouched. DRM-encrypted books are refused. |
| Plain text | .text, .txt | Each non-blank line is a segment; line endings come back as they were. |
Help authoring#
| Format | Extensions | What is translated, and notes |
|---|---|---|
| MadCap Flare project | .flprjzip | One upload for the whole project zip: topics, snippets, variable definitions, TOC titles, glossary terms and index keywords. MadCap elements are protected tags; every other file comes back byte for byte in the same zip layout. A zip of the project folder renamed to .flprjzip also works. |
| HTML Help table of contents | .hhc | Only the entry names are translated; links and every other byte are kept. Exported in the target language's Windows code page, which HTML Help 1.x needs. |
| HTML Help index | .hhk | Keywords and the topic titles that follow them; See Also references follow the keyword they name. Exported in the target language's Windows code page. |
| HTML Help project | .hhp | The title and window captions; Language= is set to the target. |
Software resources and localization files#
| Format | Extensions | What is translated, and notes |
|---|---|---|
| gettext PO and POT | .po, .pot | msgid to msgstr with contexts and plural forms. Every plural form the target language needs is filled (see plural forms on the QA checks page). A translated PO is always UTF-8 with a UTF-8 header. |
| Compiled gettext catalogs | .gmo, .mo | Read into the same units as the matching .po. Export writes a valid .mo for the target, or a .po on request. |
| JSON | .json | String values only; keys, numbers and booleans stay. Chrome extension messages.json, FormatJS, Transifex Structured JSON and go-i18n files are recognised and only their messages are translated, with ICU plurals split per branch. |
| Flutter ARB | .arb | Messages only; @ metadata stays. @@locale names the target language, and plurals get the target language's categories. |
| JSON5 and JSON with Comments | .json5, .jsonc | String values; comments, trailing commas, quoting and every untouched byte are kept. A .json file with comments must be renamed .jsonc. |
| YAML | .yaml, .yml | String values only; keys, comments, anchors and quoting are kept. A Rails locale file gets its root key renamed to the target locale. |
| TOML | .toml | String values only; go-i18n message tables translate per plural category. Must be UTF-8. |
| Java properties | .properties | One segment per value; keys and comments never change. ISO-8859-1 files write other characters as \uXXXX escapes. Mozilla-style UTF-8 properties are read too. |
| Apple .strings | .strings | One segment per value; a UTF-16 file keeps its byte-order mark. |
| Apple .stringsdict | .stringsdict | Plural, device and width variants, following the target language's plural rules. |
| Xcode String Catalogs | .xcstrings | Export adds or replaces only the target language and keeps every other language. |
| Property lists | .plist | Info.plist purpose strings and display names, Settings.bundle titles, or every prose string of any other plist; XML or binary. |
| Xcode localization catalogs | .xcloc | Zip the exported .xcloc folder and keep the .xcloc extension. The XLIFF strings translate; every other file keeps its bytes. |
| INI | .ini | Including Joomla language files. One segment per value; comments stay. |
| Windows RESJSON | .resjson | One segment per value; comment keys are never translated. |
| .NET RESX and RESW | .resw, .resx | Text values only; typed entries (images, file references) and the schema are kept. |
| WiX localization | .wxl | Text values; the target Culture is set on export. |
| Qt Linguist | .ts | Messages, with numerus forms following the target language. The .ts extension is shared with TypeScript: an XML .ts file is read as Qt Linguist. |
| XAML resources | .xaml | sys:String and x:String resources of WPF, UWP, WinUI, .NET MAUI and Avalonia dictionaries. View attributes are translated only when the operator turns that on. |
| Windows resource scripts | .rc | String tables, dialog captions and controls, menus and readable version strings. Keyboard accelerators are kept (exactly one & when the source has one). The source encoding is kept when the translation fits. |
| JavaScript and TypeScript locale modules | .cjs, .cts, .js, .mjs, .mts, .ts | Only files whose whole content is a static message object (vue-i18n, i18next and similar). The file is tokenised, never executed; any other code refuses the file with a line number. |
| Mozilla DTD | .dtd | Each entity value is one unit; nothing is expanded or fetched. UTF-8 only. |
| Project Fluent | .ftl | Message values, attributes and each select variant; placeables are kept as written. Terms are not translated unless the operator turns that on. UTF-8 only. |
| Freedesktop desktop entries | .desktop | Name, GenericName, Comment and Keywords; the export adds a localized line (for example Name[fr_FR]) after each source key. UTF-8 only. |
| Haiku catalogs | .catkeys | The translation column of each entry; name the exported file after the locale. |
| Angular XMB | .xmb | Upload the .xmb from ng extract-i18n; every export is an .xtb translation bundle for the target language. |
| Angular XTB | .xtb | Translations and the lang attribute change; every other byte is kept. |
| Salesforce Translation Workbench | .stf | Source, Outdated and untranslated, and Bilingual files. The export is the file Translation Workbench imports; label length limits are reported, never truncated. |
Bilingual and CAT exchange files#
| Format | Extensions | What is translated, and notes |
|---|---|---|
| XLIFF 1.2 and 2.0 | .xlf, .xliff | Including Angular XLIFF and Articulate Storyline and Rise exports. Locked, approved and final targets are never overwritten; untranslated units stay empty. |
| Trados SDLXLIFF | .sdlxlf, .sdlxliff | Each vendor segment is one unit. Locked, approved and confirmed segments are never overwritten; untranslated segments stay empty (never filled with source text). Every other byte is kept. |
| Trados Studio packages | .sdlppx, .sdlrpx | Upload an .sdlppx project package to get one document per target-language file, or create the project straight from the package. Download a return package (.sdlrpx) to open in Trados Studio. |
| memoQ XLIFF | .mqxliff | Same protection as SDLXLIFF; written segments are marked confirmed. |
| memoQ zipped XLIFF | .mqxlz | Every XLIFF inside the package is translated; every other file comes back unchanged. |
| Phrase XLIFF | .mxliff | Same protection as SDLXLIFF; confirmation is left to Phrase. |
| WorldServer packages | .wsxz, .xlz | Every XLIFF inside is translated; locked and finished segments are never overwritten. |
| Wordfast Pro TXLF | .txlf | Locked and confirmed segments are never overwritten; every other byte is kept. |
| Wordfast and GlobalLink TXML | .txml | Inline codes come back with their original bytes; confirmed segments are never overwritten. |
| Trados TagEditor | .ttx | Only a pre-segmented TTX can be translated; existing translations are never overwritten. The file keeps its encoding. |
Tables#
| Format | Extensions | What is translated, and notes |
|---|---|---|
| Comma-separated values | .csv | A column mapping names the source column, one column per target language, and note columns (header names or column numbers). Without one, the header row is read for source, target and language-code columns. Untouched columns keep their exact bytes, and every exported cell that starts with = + - or @ is prefixed with an apostrophe so a spreadsheet cannot run it as a formula. |
| Tab-separated values | .tab, .tsv | Same rules as CSV. |
Subtitles and captions#
| Format | Extensions | What is translated, and notes |
|---|---|---|
| SubRip and WebVTT | .srt, .vtt | Cue text only; numbering and timecodes are kept. |
| YouTube SubViewer | .sbv | Cue text only. |
| SubViewer 2.0 and MicroDVD | .sub | Told apart by content. A file that looks like both, SubViewer 1.0 or a binary VobSub file is refused. |
| SSA and ASS | .ass, .ssa | Dialogue text and the script title; override tags and line-break codes are protected. The script language header is set to the target. |
| TTML and DFXP | .dfxp, .ttml | Each caption paragraph is one segment; timing, styling and layout never change. Export declares the target language. Image subtitles are not translated. |
| Scenarist SCC (CEA-608) | .scc | A translation must fit the format: the CEA-608 Latin character set and 32 characters per row. A caption that cannot fit is not written; the export is refused with a list of problem captions and timecodes. |
| EBU STL | .stl | Rows per subtitle are kept and the character code table switches when the translation needs it. A subtitle that cannot fit refuses the export with its timecode. 3D-model .stl files are refused. |
Images#
| Format | Extensions | What is translated, and notes |
|---|---|---|
| Raster and vector images | .bmp, .gif, .jpeg, .jpg, .png, .svg, .tif, .tiff, .webp | Image localization (Beta): text regions are detected, translated and drawn back. SVG text, titles and descriptions are translated directly. Animated GIF and WebP and multi-page TIFF are refused. See the Images page. |
ZIP batch upload#
Upload a .zip and each supported file inside becomes its own document, named by its folder path. Files that cannot become documents are listed with the reason, never dropped silently: unsupported formats, nested archives (upload them separately), symbolic links, system files and duplicate paths. An archive with an unsafe path, a compression bomb, or more supported files than the install allows (500 by default) is refused whole. To get the translations back, export the batch from the project page, the CLI (project export <id> --batch <batch_id>) or the API: one folder per target language, each with the original folder structure and file names. A .zip is not itself a document format.
Glossary, TM and key imports#
- Glossaries: CSV, TBX (the 2002 default dialect, TBX-Basic and TBX v3), MultiTerm XML exported from MultiTerm (
.xml,.mtf; UTF-16 is fine), the lossless.glossary.json, and spreadsheets (.xlsx,.tsv). Forbidden or deprecated terms are kept as do-not-use terms, never as the required translation. - Translation memory: TMX, Trados Studio file-based memories (
.sdltm, read without being changed; the language pair must match), and two-column spreadsheets (.xlsx,.csv,.tsv). - Key-based projects: JSON (flat or nested) and gettext PO, plus every resource format with a key view: Java properties, Apple .strings, .stringsdict, String Catalogs and property lists, INI, RESJSON, RESX, WiX, Qt Linguist, Android and Java XML resources, YAML, TOML, JSON5, JavaScript and TypeScript locale modules, PHP arrays, desktop entries and Haiku catalogs. Comments become key descriptions and plural forms become plural keys; two entries with the same key are refused, never merged. Exports fill your own source file, so its comments, order and encoding stay.
Format settings#
A few format behaviours are set by the operator in the environment (restart to apply). All are optional.
| Setting | Effect |
|---|---|
WIKI_TEMPLATE_PARAMS | MediaWiki template parameters to translate, as Template:param pairs (for example Quote:text,Note:1). Empty by default. |
HTMLHELP_UTF8_FALLBACK | Set to 1 to write HTML Help files as UTF-8 instead of refusing a translation the target code page cannot hold (HTML Help Workshop will not show those characters correctly). |
XAML_VIEW_ATTRIBUTES | Set to 1 to also translate the Content, Text, ToolTip, Header and Title attributes of plain XAML views. Off by default. |
FTL_TRANSLATE_TERMS | Set to 1 to translate Fluent terms (-brand-name). Off by default. |
LOC_TMS_FRONT_MATTER_KEYS | The Markdown and MDX front-matter keys whose values are translated. |
LOC_TMS_MDX_ATTRS | The MDX component attributes that are translated. |
LATEX_TEXT_COMMANDS | More LaTeX inline commands whose text is translated. |
ZIP_BATCH_MAX_DOCUMENTS | The most supported files one ZIP upload may hold (default 500). |
Upload size, segment count and segment length limits apply to every format; see Deploy.
Not supported#
Current limits
Legacy binary Office files (.doc, .xls, .ppt) and RTF: save them in the newer format first.
Outlook .msg (save as .eml), Razor .cshtml, legacy Visio .vsd and .vdx, binary DXF, FrameMaker MIF 7 and older, SubViewer 1.0 and VobSub image subtitles, and Articulate .story project files.
STAR Transit packages: the format is not public, so support needs real sample packages.
Comments are translated only in Office formats and only when the project's Translate comments option is on. Chart text in Excel is not translated yet.