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, and xubuntu-docs.

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

attachment:IconsPage/IconNote.png 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: "<ulink url="http://www.ubuntu.com">The Ubuntu Website</ulink>"), the tag and anything inside the tag itself should not be translated. In the above example, the words to be translated would be "The Ubuntu Website".

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, click System -> Help -> System Documentation (in Ubuntu Dapper), or simply open Khelpcenter (in Kubuntu Dapper). 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 [https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators ubuntu-translators] mailing list: or the [https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc ubuntu-doc] mailing list.

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

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 with the help of the Rosetta Administrators.
• 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 [https://launchpad.net/distros/ubuntu/dapper/+source/ubuntu-docs/+pots/desktopguide here]).

• The tarball as imported from Rosetta is placed in the relevant document's directory (for example branches/dapper/ubuntu/desktopguide).

• The translation script (translate.sh) is then used to unpack the tarball, and 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.
• Now, we check which translations have been updated, and which are *completely* new:

  • svn status

• If there are completely new translations, these need to be added to the relevant Makefile for building html, and to the packaging for {k}{x}ubuntu-docs.

That's it!

CategoryDocteam