add documentation

docs/commands/flatxml2po.rst

@@ -0,0 +1,137 @@
+.. _flatxml2po:
+.. _po2flatxml:
+
+flatxml2po
+**********
+
+Converts flat XML (.xml) files to Gettext PO format, a simple monolingual and 
+single-level XML.
+
+.. _flatxml2po#usage:
+
+Usage
+=====
+
+::
+
+  flatxml2po [options] <xml> <po>
+  po2flatxml [options] <po> <xml> [-t <base-xml>]
+
+Where:
+
++-------------+--------------------------------------------------------+
+| <xml>       | is a valid .xml file or directory of those files       |
++-------------+--------------------------------------------------------+
+| <po>        | is a directory of PO or POT files                      |
++-------------+--------------------------------------------------------+
+| <base-xml>  | is a template or the original file before translation. |
+|             | required for roundtrips preserving extraneous data.    |
++-------------+--------------------------------------------------------+
+
+Options (flatxml2po):
+
+--version             show program's version number and exit
+-h, --help            show this help message and exit
+--manpage             output a manpage based on the help
+--progress=PROGRESS   show progress as: :doc:`dots, none, bar, names, verbose <option_progress>`
+--errorlevel=ERRORLEVEL
+                      show errorlevel as: :doc:`none, message, exception,
+                      traceback <option_errorlevel>`
+-i INPUT, --input=INPUT
+                      read from INPUT in xml format
+-x EXCLUDE, --exclude=EXCLUDE
+                      exclude names matching EXCLUDE from input paths
+-o OUTPUT, --output=OUTPUT
+                      write to OUTPUT in po, pot formats
+-S, --timestamp       skip conversion if the output file has newer timestamp
+-r ROOT, --root=ROOT  name of the XML root element (default: "root")
+-v VALUE, --value=VALUE
+                      name of the XML value element (default: "str")
+-k KEY, --key=KEY     name of the XML key attribute (default: "key")
+-n NS, --namespace=NS
+                      XML namespace uri (default: None)
+
+
+Options (po2flatxml):
+
+--version             show program's version number and exit
+-h, --help            show this help message and exit
+--manpage             output a manpage based on the help
+--progress=PROGRESS   show progress as: :doc:`dots, none, bar, names, verbose <option_progress>`
+--errorlevel=ERRORLEVEL
+                      show errorlevel as: :doc:`none, message, exception,
+                      traceback <option_errorlevel>`
+-i INPUT, --input=INPUT
+                      read from INPUT in po, pot formats
+-x EXCLUDE, --exclude=EXCLUDE
+                      exclude names matching EXCLUDE from input paths
+-o OUTPUT, --output=OUTPUT
+                      write to OUTPUT in xml format
+-t TEMPLATE, --template=TEMPLATE
+                      read from TEMPLATE in xml format
+-S, --timestamp       skip conversion if the output file has newer timestamp
+-r ROOT, --root=ROOT  name of the XML root element (default: "root")
+-v VALUE, --value=VALUE
+                      name of the XML value element (default: "str")
+-k KEY, --key=KEY     name of the XML key attribute (default: "key")
+-n NS, --namespace=NS
+                      XML namespace uri (default: None)
+-w INDENT, --indent=INDENT
+                      indent width in spaces, 0 for no indent (default: 2)
+
+.. _flatxml2po#formats-supported:
+
+Formats Supported
+=================
+
+Check :doc:`flat XML format </formats/flatxml>` document to see to which extent
+the XML format is supported.
+
+.. _flatxml2po#examples:
+
+Examples
+========
+
+This example looks at roundtrip of flat XML translations as well as recovery of
+existing translations.
+
+First we need to create a set of POT files.::
+
+  flatxml2po -P lang/en pot/
+
+All .xml files found in the ``lang/en`` directory are converted to Gettext POT
+files and placed in the ``pot`` directory.
+
+If you are translating for the first time then you can skip the next step. If
+you need to recover your existing translations then we do the following::
+
+  flatxml2po -t lang/en lang/zu po-zu/
+
+Using the English XML files found in ``lang/en`` and your existing Zulu
+translation in ``lang/zu`` we create a set of PO files in ``po-zu``.  These
+will now have your translations. Please be aware that in order for that to work
+100% you need to have both English and Zulu at the same revision, if they are
+not you will have to review all translations.
+
+You are now in a position to translate your recovered translations or your new
+POT files.
+
+Once translated you can convert back as follows::
+
+  po2flatxml -t lang/en po-zu/ lang/zu
+
+Your translations found in the Zulu PO directory, ``po-zu``, will be converted
+to XML using the files in ``lang/en`` as templates and placing your new
+translations in ``lang/zu``.
+
+To update your translations simply redo the POT creation step and make use of
+:doc:`pot2po` to bring your translation up-to-date.
+
+.. _flatxml2po#limitations:
+
+Limitations
+===========
+
+Indentation only supports spaces (specified with ``--indent`` greater than zero)
+or flattened (no indentation, everything on a single line; specified with
+``--indent`` set to zero). Tabs are not supported using po2flatxml.

docs/commands/index.rst

@@ -24,6 +24,7 @@ Converters
    csv2tbx
    tbx2po
    html2po
+   flatxml2po
    ical2po
    ini2po
    json2po
@@ -72,6 +73,7 @@ understanding that will make the converters much easier to use and understand.
 * :doc:`csv2tbx <csv2tbx>` -- Create TBX (TermBase eXchange) files from Comma
   Separated Value (CSV) files
 * :doc:`html2po <html2po>` -- HTML converter
+* :doc:`flatxml2po <flatxml2po>` -- Flat XML converter
 * :doc:`ical2po <ical2po>` -- iCalendar file converter
 * :doc:`ini2po <ini2po>` -- Windows INI file converter
 * :doc:`json2po <json2po>` -- JSON file converter

docs/formats/flatxml.rst

@@ -0,0 +1,96 @@
+.. _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`.
+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 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/>`_

docs/formats/index.rst

@@ -108,6 +108,7 @@ Formats of translatable documents
    :hidden:
 
    html
+   flatxml
    ical
    json
    yaml
@@ -117,6 +118,7 @@ Formats of translatable documents
    subtitles
 
 * :doc:`html`
+* :doc:`flatxml` (single-level XML)
 * :doc:`ical`
 * :doc:`json`
 * :doc:`yaml`

translate/convert/flatxml2po.py

@@ -19,7 +19,8 @@
 
 """Convert flat XML files to Gettext PO localization files.
 
-TODO: examples/usage
+See: http://docs.translatehouse.org/projects/translate-toolkit/en/latest/commands/flatxml2po.html
+for examples and usage instructions.
 """
 
 from translate.convert import convert

translate/convert/po2flatxml.py

@@ -19,7 +19,8 @@
 
 """Convert Gettext PO localization files to flat XML files.
 
-TODO: examples/usage
+See: http://docs.translatehouse.org/projects/translate-toolkit/en/latest/commands/flatxml2po.html
+for examples and usage instructions.
 """
 
 from translate.convert import convert