This is the crude working draft of the new infrastructure for translations.

TODO

• Get the existing Italian translation into the .po file
• Get the existing French translation into the .po file
• Document the new process in README.md
• Possibly use the Makefile instead of build.sh? Done, we can revert the commit if we decide otherwise
• Integrate with the deploy at docs.italia.it
• Squash all

Shortcomings

• Sphinx defaults to creating a new pot/po file for every source file and there is no way (AFAIK) to make it use a single .pot. This is bad because:

  • Translators would rather prefer a single .po file.
  • Translators would need to translate the same shared string over and over again (ie "Presence: optional") because strings are not shared across different documents.
  • include works in an annoying way. Consider:

       .. file.rst 
    
       .. include:: included.rst

    the strings in included.rst are now part of file.rst as well, and you have to translate them twice. This is most likely a bug.

  IMHO, this is both a wrong default and a missing feature on Sphinx side. I'll open a bug and take care with that upstream, but in the meantime I had to resort to violence and monkey patched Sphinx to create just publiccode.yml.pot. I think this is worth doing and it's a temporary solution anyway.

• Looks like the .. code:: directive gets lost and doesn't end up in the generated files. I gotta try and fix that up. Fixed in the Sphinx extension (Preserve code blocks. davidfritzsche/sphinx-rst-builder#2), package with the patch available on pypi.

• Some string must not be translated, like enumerators (ie. tags in categories-list.rst). Excluding those would mean less work for the translators and a lower chance for errors. Unfortunately it's not possible at the moment, but we can always add it later.

• Some string need to be translated, but should be handled with care, like "Key" strings in schema.core.rst. If the fix to Syntax to exclude words from i18n / gettext sphinx-doc/sphinx#1608 will allow to mark only certain words within a paragraph, it would fix this issue for us as well. Again, this can be a future enhancement.

Fixes #75.