Useful Translation Suggestions

Please see the pages about working on the web pages which describe some general things to observe, not strictly limited to translations.

What to translate?

See the instructions for starting a new translation for an introduction.

Once you start translating pages, we recommend you start with pages that users are most likely to visit. Here are some guidelines; also note that the lists of pages in the translation statistics are ordered by popularity.

Most important:
  • the main directory: index.wml, contact.wml, donations.wml, social_contract.wml, support.wml
  • the intro/ directory: about.wml, cn.wml, free.wml, why_debian.wml
  • the releases/ directory: index.wml
  • the releases/bookworm/ directory: index.wml, installmanual.wml, releasenotes.wml
  • the distrib/ directory: index.wml, packages.wml, netinst.wml, ftplist.wml
  • the mirror/ directory: list.wml
  • the CD/ directory: index.wml
  • the doc/ directory: index.wml
  • the MailingLists/ directory: index.wml
  • the security/ directory: index.wml
Standard:
The remaining files in the aforementioned directories, and these:
  • Bugs/index.wml, Bugs/Reporting.wml
  • banners/index.wml
  • blends/index.wml
  • consultants/index.wml
  • doc/ddp.wml
  • events/index.wml
  • international/index.wml, and create a page (or directory) for your language
  • logos/index.wml
  • mirror/index.wml
  • misc/index.wml
  • News/index.wml
  • News/weekly/index.wml
  • ports/index.wml
  • partners/index.wml
Optional:
All the other files in the previously mentioned directories. This includes the following directories which include subdirectories that are modified frequently, so are harder to keep up to date:
  • MailingLists/desc/
  • News/
  • doc/books.wml
  • events/
  • security/
Least Important:
Files in the devel/ and vote/ directories. Since they are mostly for developers, and the primary language of developers is English, it is only when you have a strong translation team should you attempt to tackle these.

It is important that you only translate files that you have the time to maintain. A few well maintained pages is much more useful than a lot of out of date ones.

How closely should translations follow the original?

There are times when you may want to make a change to the content when you are translating. One example is on the support page; you will probably want to include an example on subscribing to the language specific mailing list, e.g. debian-user-french on the French version of the pages.

If you make more significant changes, please notify debian-www list as it is desired to keep the content as similar as possible between the different versions.

The pages are meant to be useful. If you have information that will help the users of your language, feel free to add it. You can use international/<Language>.wml for all the stuff interesting to Language-speaking visitors.

If you know of information that would be useful to all users, bring it up on debian-www.

How do translators know when files need to be updated?

There is a mechanism that translators can use to keeping web site translations up-to-date.

How do we keep the gettext template translations up to date?

After the English files have been updated, run make update-po in the po/ subdirectory of your translation to update your .po files with the originals. Watching the log messages on the debian-www-cvs mailing list can be helpful to find out when this should be done; or you can simply run it at regular intervals.

Use the make stats command to see an overview of the changes. Gettext will mark the tags whose value it had to guess with "#, fuzzy", and newly introduced tags will simply have an empty string after msgstr.

How do users know if a translated page is out of date?

The translation-check template which is used to keep translations up-to-date will make a note in translations which are outdated.

Things to observe when translating

The following is a list of pages and directories that may require special attention when translating:

News/
You can translate as many or as few pieces of news as you wish. The indices are created automatically from the titles of the items. If an item has been translated, then the translated title will be used in the index.
security/
This is set up similar to the News/ directory. There's one difference, there are .data files that you should not translate.
CD/vendors/
Only the *.wml files in CD/vendors/ should be translated. Translations for tags are added via gettext in the po/vendors.xy.po file.
intro/organization.wml
Tags are translated via gettext in the po/organization.xy.po file.
MailingLists/{un,}subscribe.wml
These two files are generated by the mklist script, so you can't edit them directly. You can translate the files in the desc/ subdirectory, they contain the descriptions of mailing lists. Tags are translated via gettext in the po/mailinglists.xy.po file.
consultants/index.wml
Tags are translated via gettext in the po/consultants.xy.po file.
releases/*/{installmanual,releasenotes}.wml
Translate everything but the Perl code (stuff enclosed in <: :>), except for the second argument of permute_as_list.
ports/
Port pages may be volatile. You should only translate these if you are willing to spend the time keeping them up to date.
devel/website/
This is for people editing or translating web pages, so it is probably very low priority.