Open Stack

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.its,unified
> >
> > 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-quick-start-intro.xml,unified
> >
> > 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