Flat XML¶
The Translate Toolkit is able to process flat XML files using the flatxml2po converter.
Flat XML (eXtensible Markup Language) is a simple monolingual file format similar to a very basic form of the Android string resources format. Flat in this context means a single level of elements wrapped in the root-element with no other structuring.
Conformance¶
Single-level XML with attributes identifying a resource:
<root> <str key="hello_world">Hello World!</str> <str key="resource_key">Translated value.</str> </root>
Customizable element- and attribute-names (including namespaces):
<dictionary xmlns="urn:translate-toolkit:flat-xml-dictionary"> <entry name="hello_world">Hello World!</entry> <entry name="resource_key">Translated value.</entry> </dictionary>
Value whitespace is assumed to be significant (equivalent to setting
xml:space="preserve"
):<root> <str key="multiline">The format assumes xml:space="preserve". There is no need to specify it explicitly. This assumption only applies to the value element; not the root element.</str> </root>
Non-resource elements and attributes are preserved (assuming the same file is also used when converting back to XML):
<root> <str key="translate_me">This needs to be translated</str> <const name="the_answer" hint="this isn't translated">42</const> <str key="important" priority="100">Some important string</str> </root>
Indentation can be customized to match an existing and consistent style:
<root> <str key="indent">This file uses 8 spaces for indent</str> <str key="tab_works">Tabs can also be used; but this is limited to the Python API at this point</str> <str key="linerized">No indent (all in one line) is also supported</str> <str key="note_on_eof">End-of-file *always* has a LF to satisfy VCS</str> </root>
Note
To avoid potential issues and extraneous changes in diffs, this format always forces an ending linefeed by default for compatibility with various Version control systems (such as Git).
Non-Conformance¶
While the format is flexible, not all features are supported:
- Mixed element/attribute names (as well as different namespaces for root- and value-element) and nested structures additional child elements. This format intentionally focuses on a simple structure that can be used by other languages (such as XSLT).
- Comments are preserved on roundtrips, but are not carried over into the resulting PO Files.
- XML Fragments and non-wellformed XML.