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 Git 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 commit of the original file that was translated, so that updating is easier. The line looks like this: #use wml::debian::translation-check translation="<git_commit_hash>" Please note that if you generate the translatable file using copypage.pl tool (which is highly recommended), the git commit hash will be generated automatically. The usage of copypage.pl will be explained in the following texts.

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="git_commit_hash" 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.

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 committed 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 in the webwml root directory, which it will use to determine the language you are translating to. That file needs up to two lines: the first line gets the language name (like german) and the second can optionally get the name of the maintaining translator. 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. Or as a third possibility, you can give language and (optionally) maintainer on the commandline via -l german -m "Donald Duck" and not use the language.conf file at all. 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.

NOTE: The web pages are regularly rebuilt automatically on the www-master server, based on the wml source in git. 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 Git. If you have the permissions to do this yourself, please push the commits to the webwml git repository; 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 an e-mail (in English) at [email protected].

First of all, clone our source tree, as described on our Git introduction page.

After you have a git checkout, start by creating a new top level 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 VCS 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 committing 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 find that some files got removed sometime in the past and you would like to checkout the file again for further editing, you may search through the commit history using git's standard commands.

For example, if the delete file is "deleted.wml", you may search the history by running:

   git log --all --full-history -- <path/to/file/deleted.wml>

You may find out the exact commit that removed the file you want, together with the commit's hash string. To display the detail information about the modification made to the file in this commit, you may use git show subcommand:

  git show <COMMIT_HASH_STRING> -- <path/to/file/deleted.wml>

If the commit is exactly the one that deleted the file, you may restore the file to the workspace using git checkout:

  git checkout <COMMIT_HASH_STRING>^ -- <path/to/file/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.