4. Translating Documentation

4. Translating Documentation
Prev		Next

4. Translating Documentation

To translate Fedora documentation, become a member of the cvsl10n group. For more information on account and subscriptions, refer to Section 2, “Accounts and Subscriptions”.

To translate documentation, you need a Fedora 5 or later system with the following packages installed:

gnome-doc-utils
xmlto
make
w3m

The gnome-doc-utils package provides the xml2po command, and does not require you to install the GNOME desktop environment. The xmlto, make and w3m packages contain tools necessary for testing document builds and translations.

To install these packages, use the following command:

su -c 'yum install gnome-doc-utils xmlto make w3m'

4.1. Getting Started

The Fedora documentation is stored in a CVS repository under the directory docs/. To list the available modules, run the following commands (where username is replaced with your Fedora account username):

export CVSROOT=:ext:username@cvs.fedoraproject.org:/cvs/docs
cvs co -c

To download a module to translate, list the current modules in the repository and then check out that module. You must also check out the docs-common module to work with some modules.

cvs co release-notes docs-common

Some modules are release specific, meaning that they have a branch, or subdirectory, for each release of Fedora:

ls release-notes/
CVS  F-7  FC-5  FC-6  FC3  FC4  devel

The devel/ branch is used for the upcoming release of Fedora. Often translators work on this branch, and port changes back to previous branches as required.

How to get the smallest check out

	How to get the smallest check out
Another method is to use a module alias. Using the alias `release-notes-version` checks out just the `version` specified. This method brings the versioned subdirectory and the `docs-common` module into one directory, `release-notes-version`. For example, to get just the `-devel` version, use this command: `cvs co release-notes-devel` Everything needed to build the document is now in the directory `release-notes-devel/`: `ls release-notes-devel` `CVS docs-common release-notes`

Another method is to use a module alias. Using the alias release-notes-version checks out just the version specified. This method brings the versioned subdirectory and the docs-common module into one directory, release-notes-version. For example, to get just the -devel version, use this command:

cvs co release-notes-devel

Everything needed to build the document is now in the directory release-notes-devel/:

ls release-notes-devel
CVS  docs-common  release-notes

4.2. Creating Common Files

Only if you are creating the first-ever translation for a locale, you must first translate some common files used in all documents for your locale. The common files are located in docs-common/common/.

	Example Locale is `pt_BR`
	The following examples use the locale code `pt_BR`. Substitute your locale code in these commands as necessary.

Read the README.txt file in the docs-common/common/entities and follow the directions to create new entities.
Once you have created common entities for your locale and committed the results to CVS, create locale files for the legal notices:
```
cd docs-common/common/
cp legalnotice-opl-en_US.xml legalnotice-opl-pt_BR.xml
cp legalnotice-relnotes-en_US.xml legalnotice-relnotes-pt_BR.xml	
```
Do Not Translate Legal Notice

To ensure it is legally equivalent in all locales, do not translate the OPL.

	Do Not Translate Legal Notice
To ensure it is legally equivalent in all locales, do not translate the OPL.

Then commit those file to CVS also:

cvs add legalnotice-*-pt_BR.xml
cvs ci -m 'Added legal notices for pt_BR' legalnotice-*-pt_BR.xml

Next, build the draft watermark for your locale in the docs-common/images/ folder:
```
cd docs-common/images/
cp watermark-en_US.svg watermark-pt_BR.svg
```
Translate the text elements in the SVG. Then add your locale's SVG file to the Makefile, produce the PNG and commit the results:
```
make watermark-pt_BR.png
cvs add watermark-pt_BR*
cvs ci -m 'Added pt_BR images' Makefile watermark-pt_BR*
```

	Build Errors
	If you do not create these common entities, building your document may fail.

4.3. Using Translation Applications

The po/ directory contains the .po files used to translate content. It also contains a .pot file, or PO template, which is used to create new .po files when necessary.

If the po/ directory does not exist, you can create it and the translation template file with the following commands:

mkdir po
cvs add po/
make pot

	Do Not Make Manual POT Changes
	Authors and editors generate the POT file from the source XML files, which overwrite any manual changes to a POT file. If you find a problem in the original messages of a POT file, visit Bugzilla at https://bugzilla.redhat.com to file a bug against the document.

To work with a .po editor like KBabel or gtranslator, follow these steps.

	Example Locale is `pt_BR`
	The following examples use the locale code `pt_BR`. Substitute your locale code in these commands as necessary.

Change Directory

In a terminal, go to the directory of the document you want to translate:
```
cd ~/docs/translation-quick-start-guide/
```
Add Locale to List

To add your locale, you must locate and change the appropriate locale list. Some documents are using the po/LINGUAS file, as standardized in the GNOME project, to track locales. Some documents have not been updated to this standard yet. If you find the module you are translating has not been updated, notify the Fedora Documentation Project or file a bug using Bugzilla.

Add your translation language code to the list in the po/LINGUAS file using your preferred editor. For example,
```
vi po/LINGUAS
```
Press 'a' to modify and add your language code. Once added, save it and exit the editor.

Please remember to keep the list in alphabetical order.
Create PO File

Make a new .po file for your locale:
```
make po/pt_BR.po
```
Translate Strings

To translate the file, use the same application used to translate software:
```
kbabel po/pt_BR.po
```

Check Integrity

Before committing your changes, check the integrity of the XML with the following command. This ensures a sane build for all users.

make html-pt_BR

You can read the resulting HTML files with a Web browser. If no HTML is created, the error message(s) can be found in the output. Please resolve them before commit.

	Always Test Your Translation
	Do not go to the next step or commit changes until you test your work in this step. Erroneous changes can break documents for other users, editors, and automated applications.

Commit Work

Before commit your .po file, always make sure that the html has been generated successfully. You may note the percent complete or some other useful message at commit time.
```
cvs ci -m 'Translating... 400/10/126' po/pt_BR.po
```

4.4. What to Translate

The most important docs modules/directories for each release are the following:

docs-common/common/entities
release-notes/devel
homepage/devel
install-guide/devel
about-fedora/devel
readme/devel
readme-burning-isos/devel
readme-live-image/devel

To see all documents available in the documentation repository, run:

export CVSROOT=:ext:username@cvs.fedoraproject.org:/cvs/docs
cvs co -c

Prev		Next
3. Translating Software	Home	Index