1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
.. _flatxml:
Flat XML
********
The Translate Toolkit is able to process flat XML files using the
:doc:`flatxml2po </commands/flatxml2po>` converter.
Flat XML (:wp:`eXtensible Markup Language <XML>`) is a simple monolingual
file format similar to a very basic form of the :doc:`android` format.
Flat in this context means a single level of elements wrapped in the
root-element with no other structuring.
.. _flatxml#conformance:
Conformance
===========
* Single-level XML with attributes identifying a resource:
.. code-block:: xml
<root>
<str key="hello_world">Hello World!</str>
<str key="resource_key">Translated value.</str>
</root>
* Customizable element- and attribute-names (including namespaces):
.. code-block:: xml
<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"``):
.. code-block:: xml
<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):
.. code-block:: 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:
.. code-block:: xml
<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
:wp:`Version control systems <Version_control_system>`
(such as :wp:`Git`).
.. _flatxml#non-conformance:
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 :wp:`XSLT`).
* Comments are preserved on roundtrips, but are not carried over into
the resulting :doc:`po`.
* XML Fragments and non-wellformed XML.
.. _flatxml#references:
References
==========
* `XML specification <http://www.w3.org/TR/REC-xml/>`_
|
