Skip to content
Back to top
View this page
Edit this page

# 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

- XML specification