On Sun, 2014-05-04 at 13:33 +0200, Andreas Jaeger wrote:
On 05/03/2014 02:53 PM, Shaun McCance wrote:
Hi all,
I've been working on switching the docs translation infrastructure over to itstool. This affects openstack-manuals, operations-guide, and api-site. The current tools are based on xml2po, but they don't call xml2po directly. Instead, they import xml2po and mess around with its internals to get some custom behavior.
itstool is designed to handle custom behavior with rules from the W3C Internationalization Tag Set (ITS). You can see the ITS I put together so far here:
https://review.openstack.org/#/c/91869/3/os_doc_tools/resources/openstack.it...
Using ITS also allows us to do local ITS attributes to override the behavior for specific elements. See a simple example here:
https://review.openstack.org/#/c/91872/1/api-quick-start/src/docbkx/api-quic...
Most messages in the PO files will be the same. The one big difference will be in how placeholders are done when there's a block-level element inside a block-level element (a practice I discourage anyway).
Could you give an example, please?
In the user-guide, in section_dashboard_manage_images.xml, there's an itemizedlist inside a para. An itemizedlist is a block-level element, so it starts one or more new PO messages. The message for the para gets a placeholder element so translators know it's there, and can move it around if necessary. With xml2po, it looks like this: #: doc/user-guide/section_dashboard_manage_images.xml:179(para) msgid "" "In the Update Image dialog box, you can perform the following " "actions: <placeholder-1/>" msgstr "" With itstool, it looks like this: #. (itstool) path: step/para #: doc/user-guide/section_dashboard_manage_images.xml:179 msgid "" "In the Update Image dialog box, you can perform the following " "actions: <_:itemizedlist-1/>" msgstr "" itstool puts all its special elements in a namespace using the _ prefix. (It gets mapped to an internal namespace URI during processing.) This helps prevent conflicts, and it allows the local name of the placeholder element to reflect what kind of thing gets put there, which is helpful.
I'd like to get input from translators, as well as any other docs folks who've worked on this. Most of the document translations are incomplete anyway, but it would nevertheless be best to do this at the beginning of a release cycle.
I assume that we can convert the existing translated files in such a way that we do not loose translations? How to do this properly? Download current files from transifex, convert into new format, upload converted files - and then continue translating? Or will it be enough to upload the pot file and let transfix do the translation?
Any translations where the source string is the same will just continue to work. That's the way PO works. I looked into migrating obvious things like the placeholder difference. There are very few translations though. I could maybe fix up 20-30 across all translations of all books. There isn't anything else to migrate.
Did you test a conversation of locale files and reconstructed translated manuals? Is this just working with the updated tools or are additional steps needed?
Yes. My patch includes also using itstool for generating the DocBook from the PO files. I tested it. It works.
I think we need to ensure with the infra team that itstools are installed on our machines.
That's the big question I haven't been able to answer yet. Preferably at least version 2.0.1.
I see that some patches are dependent on each other and we need to do certain steps in a specific order. Is this something you can write down as plan, please?
I did write this: https://wiki.openstack.org/wiki/Documentation/Translation#ItsTool_Conversion It has steps that need to be done (roughly) in order. -- Shaun