[Openstack-i18n] Switch to itstool for docs translation?

Andreas Jaeger aj at suse.com
Sun May 4 11:33:29 UTC 2014

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?

> Blueprint and some patches:
> https://blueprints.launchpad.net/openstack-manuals/+spec/itstool-for-docs
> https://review.openstack.org/#/q/topic:bp/itstool-for-docs,n,z

Looking at the patches, I really like what I see and would love to see 
us move forward.

This needs also some documentation in the OpenStack wiki on the 
recommend usage of local ITS attributes like its:translate and 

> 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?

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?

I think we need to ensure with the infra team that itstools are 
installed on our machines.

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?

  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
   SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
    GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

More information about the Openstack-i18n mailing list