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.


  • Single-level XML with attributes identifying a resource:

      <str key="hello_world">Hello World!</str>
      <str key="resource_key">Translated value.</str>
  • 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>
  • Value whitespace is assumed to be significant (equivalent to setting xml:space="preserve"):

      <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>
  • Non-resource elements and attributes are preserved (assuming the same file is also used when converting back to XML):

      <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>
  • Indentation can be customized to match an existing and consistent style:

            <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>


    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).


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.