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.

References