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". The copypage.pl will do this automatically if you set the DWWW_MAINT environment variable or use the -m command-line switch.

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:

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. You will be warned if a page to be copied exists in the repository, whether because the page was removed from the repository (due to it being too out of date) or because somebody already commited a translation and your local repository copy is not up to date.

In order to start using the copypage.pl you should first configure the file language.conf which it will use to determine the language you are translating to. That file only needs to have a line with the language name, thats it. You can also set the language through the use of the DWWW_LANG environment variable and use the DWWW_MAINT environment variable to put your name so that it will be added to the header of the wml files generated as the maintainer for the translation. There are other features available in the script, just run it without any arguments to get the help.

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:

  1. The variable LANGUAGE must be changed in the file Make.lang.
  2. 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.
  3. 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.
  4. 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.

The point of po/ files is to make things easier for translators, so that they (almost) never have to edit anything in the english/template/debian directory itself. If you find anything to be wrong with the way something is set up in the template directory, please make sure that the problem is fixed in a general manner (feel free to ask someone else to do it for you), rather than commiting actual translations into the templates, which would (usually) be a major problem.

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.

Reviving outdated translations

As described in how to keep translations up to date, outdated translations of the website might be removed automatically when a long period of time has gone by without an update.

If you use the copypage.pl script with a file that has been removed from CVS it will refuse to copy the page and ask you to revive it instead. You can check the reasons why the file was removed from cvs using cvs log on the removed file (or use the web interface, the deleted files can be found in the "Attic" subdirectory).

In order to revive the out of date translation use cvs status (or cvs log) to note the version number of the deleted version and then do a backwards merge.

For example, if the delete file is "deleted.wml", and the deleted version is 1.7, the version prior to deletion is 1.6 (the deleted version minus one). You can restore the file by running: 

   cvs update -j 1.7 -j 1.6 deleted.wml

Once you do this you have to, of course, update the document before you check it in again. Or it might be otherwise removed.

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.

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.