Translating Debian web pages

To make the job of the translators as easy as possible the pages are generated a bit differently than many of you will be used to. The web pages are actually generated using source that is marked up with wml. There are separate directories for each language.

If you plan to start an entirely new translation of the Debian web site, please see the section on starting a new translation.

Translating individual pages

We use WML to separate the specific content of a page from the elements common to multiple pages. This means that one needs to edit certain WML source files instead of HTML files. Please use CVS to acquire the current sources. You'll need to check out at least two directories: webwml/english/ and webwml/<language>/.

To translate a single page from English into your language, the original .wml file needs to be translated and placed within the other language's directory. The relative path and name need to be the same as in the English directory in order for the links to continue to work.

Translation headers

It is strongly recommended that the translator adds an additional line to the headers after the last #use statement to record the exact revision of the original file that was translated, so that updating is easier. The line looks like this: #use wml::debian::translation-check translation="x.y"

Some translation teams also use this line to mark the official translator of each web page. Doing so, you will get automatic mails when the pages you maintain are updated in English, and need your attention to update the translation. For that, simply add your name as maintainer at the end of the #use line to make it look like this: #use wml::debian::translation-check translation="x.y" maintainer="your name"

You also need to explain to the robot who you are, how often you want to get automatic mails and their content. For that, edit (or let your coordinator edit) the file webwml/language/international/language/translator.db.pl in the CVS. The syntax should be quite understandable, and you can use the file of the French team as template if it does not exist for your language yet. The robot can send several kinds of information, and for each of them, you can choose the frequency at which it will be sent to you. The different kinds of information are:

summary: a summary of which documents are outdated
logs: the "cvs log" between the translated and current versions
diff: "cvs diff"
tdiff: the script will try to find the part of the translated text modified by the English patch
file: add the current version of the file to translate

Then, for each of them, the value should be one of: 0 (never), 1 (monthly), 2 (weekly) or 3 (daily).

An example could be:

                'Martin Quinson' => {
                        email       => 'martin.quinson@tuxfamily.org',
                        summary     => 3,
                        logs        => 3,
                        diff        => 3,
                        tdiff       => 0,
                        file        => 0
                },

The header of the web page can be easily produced by using the copypage.pl script in the webwml root directory. The script will copy the page to the right place, create directories and makefiles if necessary, and add the required header automatically.

After you have run e.g. ./copypage.pl file.wml, translate the original text within the file. Comments in files will indicate if there are items that should not be translated; respect them. Don't do any unnecessary changes to the formatting; if something needs to be fixed, it should likely be done in the original file.

Page building and publishing

Since we use content negotiation, HTML files are not named file.html but file.<lang>.html, where <lang> is the two letter code of the language, according to ISO 639 (e.g. fr for French).

You can build HTML from WML by running make file.<lang>.html. If that works, check if the syntax is fully valid with weblint file.<lang>.html.

The web pages will get rebuilt from CVS on the www-master server, and this process is for the most part impervious to errors. However, if you commit a broken file in the top level of your translation (e.g. the top-level index.wml file), it will break the build process and stall all the other updates to the web site. Please pay special attention to these files.

Once the page is good to go, you can commit it into CVS. If you have the permissions to do this yourself, run cvs commit; if not, send it to somebody with write access to the repository.

Starting a new translation

If you would like to start translation of the Debian web pages into a new language, send us e-mail (in English) at webmaster@debian.org.

First of all, make sure you have made a proper checkout of our source tree, as described on our CVS introduction page.

After you have checked out the webwml/ directory and (at least) webwml/english/, start by creating a new directory for your translation, next to english/ and others. The name of the translation directory must be in English and entirely lowercase (e.g. "german", not "Deutsch").

Copy the Make.lang and .wmlrc files from the english/ directory to the new translation directory. These files are essential for building your translation from WML files. They have been designed so that after you copy them to the new language directory, you only have to change these things:

The variable LANGUAGE must be changed in the file Make.lang.
The variables CUR_LANG, CUR_ISO_LANG and CHARSET must be changed in the .wmlrc file. Add CUR_LOCALE to that, if you need it for sorting.
Some languages may need extra processing to handle the charset. This can be done using the --prolog and --epilog options to wml. Use the WMLPROLOG and WMLEPILOG variables in Make.lang to do this.
The variable LANGUAGES must be changed in top-level webwml/Makefile file so that your language will get built along with the other ones, on www.debian.org. We would prefer if you left this particular change up to the webmasters, because you may not be aware that your translation is broken when checked out of CVS afresh, which could break the building process of the rest of our web site.

After that is done, put the following line in a new file called "Makefile" in that directory:

include $(subst webwml/yourlanguagedir,webwml/english,$(CURDIR))/Makefile

(Replace yourlanguagedir with the name of your language's directory, of course.)

Now create a subdirectory inside your language's directory called "po", and copy the same Makefile to that subdirectory (cp ../Makefile .).

In the po/ directory, run make init-po to generate the initial set of *.po files.

Now that you have the skeleton set up, you can start adding your translations in our shared WML tags used in templates. The first templates that you should translate are those that appear on all of the web pages, like the header keywords, the entries in the navigation bar, and the footer.

Start translating in the po/templates.xy.po file (where xy is your language's two-letter code). For every msgid "something" there is initially a msgstr "" where you should fill in the translation of something in the double quotes after msgstr.

You don't have to translate all of the strings in all of the .po files, just those that your currently translated pages actually need. To see if you need to translate a string, see the comments in the .po file just above each msgid statement. If the referenced file is in english/template/debian, then you should most likely translate it. If not, you can postpone it for later, when you actually translate the relevant section of the web pages that require it.

If you aren't sure if you did something properly, ask on the debian-www mailing list before committing.

Note: if you find you need to make any other changes, send mail to debian-www saying what you changed and why, so the problem can be corrected.

After the template skeleton is done, you can start with translating the front page and the other *.wml files. For a list of files that should be translated first, check the hints page. Translate *.wml pages as described at the top of this page.

The rest of the story

The description above will probably be enough to get you started. Afterwards, you will want to refer to the following documents which provide more detailed explanations and additional useful information.

A number of examples are provided to give you a clearer idea of how to get started.
A number of common questions are answered and helpful hints provided in the translation hints page.
We have mechanisms in place to aid in keeping the translations up to date.
To see how your translation compares to others in the amount of files translated, check the statistics.

We hope you find the work we've done will make translating the pages as easy as possible. As has already been mentioned, if you have any questions, you can ask them on the debian-www mailing list.