Introduction

Translating documentation requires some special considerations which do not apply when translating programs. This page contains instructions for translators and an explanation of the toolchain used to convert the documentation into translation templates and back again.

For Translators

Ubuntu documentation uses Rosetta as a translation portal, as with the rest of Ubuntu. For explanations of how to use Rosetta, see the Rosetta page.

The documentation can be found in the following packages: ubuntu-docs, kubuntu-docs, edubuntu-docs and xubuntu-docs. In Ubuntu 11.04, the principal Ubuntu help documentation is found in the gnome-user-docs package.

There are a number of specific considerations to bear in mind when translating documentation.

Failure to observe these instructions will result in the translated document breaking.

1. Tags should not be translated. Where you see a tag in the translation (for example: "<xref linkend="free-software"/>"), the tag and anything inside the tag itself should not be translated. It is very important to copy and paste these tags exactly as they appear in this English. The exception to this is where a tag contains a URL where there is an equivalent translated URL. In those cases the translator should use discretion about whether to localise the URL.

2. Entities should not be translated. Where you see a phrase expressed like "&gt;", do not change this.

3. Always maintain the order of tags. When you see different tags nested inside each other (for example: "<menuchoice><guimenu>System</guimenu><guimenuitem>Administration</guimenuitem><guimenuitem>Users and Groups</guimenuitem></menuchoice>"), you must always preserve that order carefully - copying and pasting from the English is the best way to ensure that you do this correctly. Only translate the words inside the tags.

4. For full English copies of the various guides to give you context while translating, open the Help application (yelp) in Ubuntu, or Khelpcenter in Kubuntu. Alternatively, all the guides are available to browse at http://doc.ubuntu.com

5. The documents are not automatically imported into Ubuntu (like the translation of programs). They need to be exported and uploaded manually to the packages. The documentation team will take care of this on occasions.

If you have any questions, please ask on the ubuntu-translators mailing list: or the ubuntu-doc mailing list.

Testing translations

These are instructions for testing translations in the ubuntu-docs package. For instructions on testing translations in the gnome-user-docs package, see below.

You can now test the translations you've done in Rosetta by inserting them into our repository and viewing them in Yelp.

1. Download the LANG.po file for a particular document from Rosetta. For example the relevant templates for Precise can be found here. These instructions use the example of the french (fr) translation of the internet document.

2. Get the Precise branch of our repository:

   sudo apt-get install bzr xmlto gettext gnome-doc-utils
   
   bzr checkout --lightweight lp:ubuntu-doc/precise ubuntu-docs-precise

3. Browse to the documentation directory

   cd ubuntu-docs-precise

4. Insert the new po file in the relevant document folder, under the po subfolder using the naming scheme LANG.po:

   mv ~/Desktop/internet-fr.po internet/po/fr.po

5. Run the translate script and choose the relevant document and language:

   ./scripts/translate.sh -d internet -l fr

6. The script will update the docbook xml for your document and language and will check the file created for validity. It will print any errors as output.

7. Open the file in the GNOME help viewer, called yelp:

   yelp file://${PWD}/internet/fr/internet.xml

Yelp always requires the full path to the xml document.

To build all documents with the latest translation run:

for doc in $(cat libs/shipped-docs); do ./scripts/translate.sh -d $doc -l LANG; done

A html version be created by running:

mkdir -p build/html

for doc in $(cat libs/shipped-docs); do find ${doc}/LANG -name "*.xml" -exec xmlto -o build/html html-nochunks {} \;; done

A nice formated html version (similar to help.ubuntu.com) be created by running:

for doc in $(cat libs/shipped-docs); do
     xsltproc --xinclude -o build/html/$doc/$lang/index.html \
        libs/ubuntu-html-chunk-cust.xsl $doc/$lang/$doc.xml 
done

Create a copy of libs/ubuntu-html-chunk-cust.xsl into libs/ubuntu-html-chunk-cust-$lang.xsl to customize/localise it's content. Also check ubuntu-banner.xsl.

LANG should be replaced by your language code.

NOTE: If you wish to make any changes to the translation, you should do so in Rosetta.

Instructions for gnome-user-docs

1. Download the LANG.po file for the gnome-help template from Rosetta. The relevant templates for Precise can be found here. These instructions use the example of the french (fr) translation.

2. Get the Precise branch of our repository:

   sudo apt-get install bzr xmlto gettext gnome-doc-utils
   
   bzr checkout lp:ubuntu-docs/precise ubuntu-docs-precise

3. Browse to the documentation directory

   cd ubuntu-docs-precise

4. Insert the new po file in the gnome-help folder using the naming scheme LANG/LANG.po:

   mkdir gnome-help/fr
   mv ~/Desktop/gnome-help-fr.po fr/fr.po

5. Update the file gnome-help/Makefile.am so that the DOC_LINGUAS string includes your language code:

   DOC_LINGUAS = fr

6. Ensure that you have the build dependencies for gnome-user-docs installed:

   sudo apt-get build-dep gnome-user-docs

7. From the root folder of the branch, run autogen:

   cd ../
   ./autogen.sh

8. From the gnome-help directory, build the translations using the "make" command:

   cd gnome-help
   make

9. There should now be approximately 240 translated files in your LANG directory. To count them:

   ls fr | wc -l

10. Test the translated files by opening them in yelp and browsing them:

    yelp fr/

11. Check the validity of the xml for each file using the check_validation.sh script in the C/ directory:

    cd C/
    for i in `ls ../fr/` ; do ./check_validation.sh ${i} ; done

12. If the script returns any validity errors, these need to be fixed in the po file which should be uploaded to Launchpad.

HTML version can be created by

1. Move to the folder libs and move yelp-build in your language directory

   cd libs 
   mv yelp-build ../gnome-help/fr/

2. cd /../gnome-help/fr/
   ./yelp-build html -x ../../libs/ubuntu.xsl *.page

You can change the look of created pages by editing ubuntu.xsl in the libs folder.

Adding screenshots to gnome-user-docs

Screenshots cannot be translated using Launchpad.

If you wish to propose the addition of updated screenshots to the package:

1. Get the Precise branch of our repository:

   sudo apt-get install bzr xmlto gettext gnome-doc-utils
   bzr checkout lp:ubuntu-docs/precise ubuntu-docs-precise

2. Browse to the documentation directory

   cd ubuntu-docs-precise

3. The English screenshots for the gnome-help template can be found in gnome-help/C/figures.

4. Add your translated screenshots to the gnome-help/LANG/figures folder:

   mkdir -p gnome-help/fr/figures/
   cp ~/Desktop/path*to*screenshot gnome-help/fr/figures/

5. Add your screenshots to bzr and commit the change:

   bzr add gnome-help/fr/figures/*
   bzr commit -m "Adding screenshots for fr locale"
    1. Push your branch to Launchpad with a descriptive branch name:{{{
   bzr push lp:~username/gnome-user-docs/fr-locale-screenshots

6. Browse to your branch on the Launchpad website and propose your branch to be merged into the ~ubuntu-core-doc/gnome-user-docs/precise branch.

For Documentation Team Members

The rest of this page is a description of how the Documentation Team work gets translated and inserted into Ubuntu. It is primarily intended for reference of the Documentation Team: translators do not need to know all this information.

Package Requirements

To install all packages required to build ubuntu-docs, including translations, run:

• apt-get build-dep ubuntu-docs

Process

There are three steps to getting documentation translated:

1. generating a translation template
2. letting the translators work their magic
3. importing the translations back into our repository

These are taken in turn below.

1. Generating a translation template

• When an English XML document is ready for translation, we make a POT file, which is the template that translators use. To make this, we use the command:

  • xml2po -e -o output.pot input.xml.

• For documents spread over more than one file, these can be included as follows:

  • xml2po -e -o output.pot chapter1.xml chapter2.xml

• IMPORTANT: For documents which have an omf file, these should also be included in the pot file.

• As a result, generally the appropriate command is:

  • xml2po -e -o output.pot C/*.xml C/*.omf

NOTE: We have an automatic script to generate POT files, called get-pot.sh. Running this script refreshes the POT files for all documents.

2. Letting the translators work their magic

• The pot file should then be uploaded to rosetta. This is done automatically if the pot is in a source deb package uploaded into the current version of Ubuntu, if not, it must be done manually at the relevant template page in Rosetta.
• Translators then do the rest!

3. Importing the translations back into our repository

• Automatic exporting from Rosetta into the docteam tree is not implemented. So here is what happens.

• When a good time comes to import the translations, the translations can be downloaded from rosetta (for example, the "Download Translations link here). You can either download translations for all documents or for documents individually.

• The translations from the tarball are placed in the relevant document's directory.

• The translation script (translate.sh) is then used to convert the translations back to xml in the appropriate directory.

• The script also checks the resulting xml for validity, and there are generally errors that must be corrected which are displayed onscreen. This must be done manually.

That's it!

CategoryDocteam CategoryTranslations