en-US/building-translation.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>

<!-- Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<section id="building-translation">
    <title>Translating &PRODUCT; Documentation</title>
    <para>Now that you know how to build the documentation with Publican, let's move on to building it in different languages. Publican helps us
          build the documentation in various languages by using Portable Object Template (POT) files and Portable Objects (PO) files for each language.
    </para>
    <para>The POT files are generated by parsing all the DocBook files in the language of origin, en-US for us, and creating a long list of strings 
          for each file that needs to be translated. The translation can be done by hand directly in the PO files of each target language or via the 
          transifex service.
     </para>
    <note>
        <para><ulink url="http://www.transifex.com">Transifex</ulink> is a free service to help translate documents and organize distributed teams
              of translators. Anyone interested in helping with the translation should get an account on Transifex
        </para>
        <para>
              Three &PRODUCT; projects exist on Transifex. It is recommended to tour those projects to become familiar with Transifex:
              <itemizedlist>
                  <listitem><para><ulink url="https://www.transifex.com/projects/p/ACS_DOCS/">https://www.transifex.com/projects/p/ACS_DOCS/</ulink></para></listitem>
                  <listitem><para><ulink url="https://www.transifex.com/projects/p/ACS_Runbook/">https://www.transifex.com/projects/p/ACS_Runbook/</ulink></para></listitem>
                  <listitem><para><ulink url="https://www.transifex.com/projects/p/CloudStack_UI/">https://www.transifex.com/projects/p/CloudStackUI/</ulink></para></listitem>
              </itemizedlist> 
        </para>
    </note>
    <warning>
        <para>The pot directory should already exist in the source tree. If you want to build an up to date translation, you might have to update it to include any pot file that was not previously generated.</para>
        <para>To register new resources on transifex, you will need to be an admin of the transifex &PRODUCT; site. Send an email to the developer list if you want access.</para>
    </warning>
    <para>First we need to generate the .pot files for all the DocBook xml files needed for a particular guide. This is well explained at the publican website in a section on 
    how to <ulink url="http://rlandmann.fedorapeople.org/pug/sect-Users_Guide-Preparing_a_document_for_translation.html">prepare</ulink> a document for translation.</para>
    <para>The basic command to execute to build the pot files for the developer guide is:</para>
    <programlisting>publican update_pot --config=publican-devguide.cfg</programlisting>
    <para>This will create a pot directory with pot files in it, one for each corresponding xml files needed to build the guide. Once generated, all pots files need to be configured for translation using transifex this is best done by using the transifex client that you can install with the following command (For RHEL and its derivatives):</para>
    <programlisting>yum install transifex-client</programlisting>
    <para>The transifex client is also available via PyPi and you can install it like this:</para>
    <programlisting>easy_install transifex-client</programlisting>
    <para>Once you have installed the transifex client you can run the <emphasis>settx.sh</emphasis> script in the <emphasis>docs</emphasis> directory. This will create the <emphasis>.tx/config</emphasis> file used by transifex to push and pull all translation strings.</para>
    <para>All the resource files need to be uploaded to transifex, this is done with the transifex client like so:</para>
    <programlisting>tx push -s</programlisting>
    <para>Once the translators have completed translation of the documentation, the translated strings can be pulled from transifex like so:</para>
    <programlisting>tx pull -a</programlisting>
    <para>If you wish to push specific resource files or pull specific languages translation strings, you can do so with the transifex client. A complete documentation of
    the client is available on the <ulink url="http://help.transifex.com/features/client/">client</ulink> website</para>
    <para>When you pull new translation strings a directory will be created corresponding to the language of the translation. This directory will contain PO files that will be used by Publican to create the documentation in that specific language. For example assuming that you pull the French translation whose language code is fr-FR, you will build the documentation with publican:</para>
    <programlisting>publican build --config=publican-devguide.cfg --formats=html --langs=fr-FR</programlisting>
    <warning>
       <para>
            Some languages like Chinese or Japanese will not render well in pdf format and html should be used.
       </para>
    </warning>
    <xi:include href="translating-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

</section>