Contributing to the OpenBSD Translation Effort

?Nec verbum verbo curabis reddere fidus interpres?

Table Of Contents


This document should contain all the information you need to contribute to the OpenBSD translation effort as described in Translation of the OpenBSD documentation. Please read this document carefully and if you still have questions, don't hesitate to contact the translation coordinators.


The purpose for translating OpenBSD web pages and other documents is to help those who don't speak nor understand English use OpenBSD or, if they do, they might feel more comfortable through reading in their own language. So, by translating you are not only helping the OpenBSD project to expand, but you are also helping people to become hooked to the system.

And of course, you'll gain good knowledge through reading and translating at the same time.

It's important to note that besides OpenBSD, the OpenBSD project has several websites for associated projects that you may want to translate:


Just translating a few web pages, or even translating the whole site including the F.A.Q., is ABSOLUTELY NOT enough. Actually, you could be doing more wrong than good. Maintaining the translation up to date is just as important. Always remember that offering outdated information will just misguide people.

If you are not going to keep your work updated, the translation itself will be pointless. Join us only if you think you're going to commit yourself to your work.

Think first how much time you will be able to dedicate to the translation. If you only have some small spare time, don't go overboard by translating several files you won't be able to maintain later.

Some files are easier to maintain than others, either because they are small, or because they don't get updated too often. For instance, plat.html is a small file, and it doesn't get modified often. On the opposite side, plus.html is a heavy file to translate; it grows bigger and bigger from one release to another, and the technical and slang wording used is very difficult to translate with accuracy.

Needless to say, some files take precedence over others. Such is the case of index.html ... or did you think otherwise?

Joining the Translation Team

Before joining the translation team, you must make sure that you have the proper environment for translation. The required environment consists of the following elements:

Once you have the proper environment, you need commit access to the Steelix CVS repository if you want to commit your work directly. Otherwise, you can send them to another translator or one of the translation coordinators to commit them for you (with due credit of course). See Who is doing this? for more information about the translators and translation coordinators.

The Steelix CVS repository, located at steelix.bsdfrog.org is the CVS repository used for translation. The translation work is not committed directly to the OpenBSD CVS repository. Rather, the translation coordinators synchronize the two repositories on a timely basis after checking the new commits.

To commit on the Steelix CVS repository you will need an account on steelix.bsdfrog.org. To setup your account, contact one of the translation coordinators. If he agrees on giving you an account, you will need to give him the following information by email:

Warning: you are fully responsible for the security of your working environment and your SSH2 DSA key.

Our experience shows that some people request an account, commit some work and then vanish without giving any good reason. Creating your account and maintaining the account database is extra work for the translation coordinators. So they might ask you to send the files to another translator who will validate your work and your commitment to the translation effort. This way, we make sure you are here to stay.

Once a translation coordinator creates your account, he will notify you by email. You will be automatically subscribed to the wwwcvs@arcane-networks.net translation mailing list. This is a mailing list on which all changes made to the Steelix CVS repository along with any translation related discussions are posted.

Using CVS

Now we'll walk you through the basic CVS operations you need to perform as a translator. If you want to have a more in-depth look into CVS usage, please see the cvs manual page and read Open Source Development with CVS, 3rd Edition, a free CVS online book by Karl Fogel and Moshe Bar.

You must have a fresh checkout (CVS download, also called a working copy in CVS terminology) of two CVS modules on your disk. These are:

Note: while the www translation CVS module holds also the English files, they must not be used since they are rarely kept in sync with the English files found on the anonymous OpenBSD CVS mirrors.

The checkouts and later operations are performed using SSH for transport, as you might have guessed after reading the Joining the Translation Team section.

Let's see how the checkouts are performed.

Initial checkout of the 'www translation' CVS module

We will assume that you are going to put all the translation work files and directories under /home/username/devel/openbsd/. Of course, this is absolutely not a requirement. This scheme is solely used for the examples below. Change as needed.

Issue the following commands to checkout the www translation CVS module from steelix.bsdfrog.org:

  $ cd /home/username/devel/openbsd/
  $ cvs -d "username@steelix.bsdfrog.org:/cvs" checkout -d "steelix-www" www

The latter command will connect to steelix.bsdfrog.org using SSH as user username to retrieve a working copy of the www translation CVS module and store it under steelix-www.

The SSH authentication is set up to use your SSH2 key, which requires you to enter your passphrase to proceed. SSH is used for checkout and all other CVS operations. By default, this will ask you everytime for your passphrase. To save some typing, you might want to load your SSH2 private key in ssh-agent using keychain (available in the ports collection) or some home-cooked recipe.

After successfully entering your passphrase, CVS will proceed with checking out your working copy. Depending on your connection speed, this operation may take some time to complete.

Once the checkout terminates, you will have a working copy of the www translation CVS module.

Initial checkout of the 'www' CVS module

To obtain a working copy of the www CVS module, you need to find an OpenBSD anonymous CVS mirror near you that is updated frequently. Suppose you are located in Germany. According to the OpenBSD AnonCVS page, anoncvs.de.openbsd.org looks like a good candidate. It is maintained by one of the OpenBSD developers (Alexander von Gernler) and updated every 2 hours. Moreover, it offers CVS through SSH. Let's use it to obtain the working copy of the www CVS module:
  $ cd /home/username/devel/openbsd
  $ cvs -d "anoncvs@anoncvs.de.openbsd.org:/cvs" checkout -d "openbsd-www" www

The latter command will connect to anoncvs@anoncvs.de.openbsd.org using SSH as user anoncvs to retrieve a working copy of the www CVS module and store it under openbsd-www. SSH won't ask for authentication since we are using an anonymous CVS account. Depending on your connection speed, this operation may take some time to complete.

Once the checkout terminates, you will have a working copy of the www CVS module.

Organization of the 'www' CVS module

The www CVS module that the OpenBSD and associated projects' websites are made of is constituted of ten sections. The table below lists all these sections and what they represent.

[base] http://www.openbsd.org/ and everything under it except for the FAQ available at http://www.openbsd.org/faq/.
[faq] http://www.openbsd.org/faq/ and everything under it except for the PF User Guide available at http://www.openbsd.org/faq/pf/.
[openbgpd] http://www.openbgpd.org/ and the associated subdirectories.
[opencvs] http://www.opencvs.org/ and the associated subdirectories.
[openntpd] http://www.openntpd.org/ and the associated subdirectories.
[openssh] http://www.openssh.com/ and the associated subdirectories except the usage subdirectory.
[openssh-usage] http://www.openssh.com/usage/.
[papers] http://www.openbsd.org/papers/ and the associated subdirectories.
[pf] http://www.openbsd.org/faq/pf/ and everything under it.
[porting] http://www.openbsd.org/porting/ and the associated subdirectories.

Translated pages in a given language for a given section are located under a subdirectory in that section. The subdirectory name is the two-letter ISO 639-1 language code of the language. For example, french [faq] pages are located under http://www.openbsd.org/faq/fr/.

The www translation CVS module is organized in an identical fashion. While the www CVS module is your source for the English original files that you need to translate or sync against, the www translation CVS module will host all your translation work as we mentioned earlier.

Working on the 'www translation' module

You must not touch any file within the first level of any section of the www translation CVS module. If, by mistake, you edited and modified one of the files in the first level, don't edit it back to reverse those changes, the timestamps will have changed and you will mess the remote repository next time you 'cvs up -PAd' followed by 'cvs commit'. Instead, just rm -f that file and follow the instructions to update. An update from the CVS repository will restore that file in your working copy. Likewise, avoid changing the files from languages other than yours.

You must do your work within your language directory. If it doesn't exist yet, you can read how to add a new directory or file in the next section.

Thus, for a given language such as Spanish, the language directory will be denoted by the two-letter ISO 639-1 language code, es/ in this case, and files will be organized as follows:

This is important to remember as far as relative links go.

Adding directories and files

Suppose that there was no Spanish directory as yet under the [pf] section. We would create it first on our local repository:
  $ cd ~/devel/openbsd/steelix-www/faq/pf
  $ mkdir es
and then we would have to add it to the CVS repository:
  $ cvs add es

That was easy. Next we would copy an English original file that we would like to translate from the www module (e.g. openbsd-www/faq/pf/index.html) into the es/ directory and would add it as well:

  $ cd  ~/devel/openbsd
  $ cp -p openbsd-www/faq/pf/index.html steelix-www/faq/pf/es/
  $ cd steelix-www/faq/pf/es
  $ cvs add index.html

Note(1): while cvs add'ing a directory will change the remote repository straight away, it won't do so if we were adding a file until we run the commit command.

Note(2): see the rm command in the CVS manual page to know how to remove a file or directory.

Updating files

If, while in the steelix-www/ directory, we ran the command and options:
  $ cd  ~/devel/openbsd/steelix-www
  $ cvs up -PAd
the effect would be twofold:

Note: it is suggested to run this command before we start making changes to our working copy, so we can see what changes have been made by others and avoid conflicts.

Committing changes

This is the mother of all commands:
  $ cd faq/pf/es
  $ cvs commit

This command will load an editor such as vi so you can enter a commit message. This message will allow others to have an idea of the change(s) that you've made. It is automatically posted to the translation mailing list.

Needless to say that you only commit when you feel your changes should definitely go into the www translation of the CVS repository.

Reverting a change

If you have committed a file and you discover that your commit breaks something, you have to revert the commit as soon as possible. Assume the problem lays in a file called somefile. Follow the procedure below to revert it to an unbroken revision:
   $ cvs log somefile

At the top of the output, you can see the latest revision of the file (your latest modifications). For example, 1.192. You have to checkout the previous revision and commit it to fix the issue.

   $ cvs update -A somefile
   $ rm somefile
   $ cvs update -p -r1.191 somefile > somefile

1.191 is indeed the previous revision. It is now in your working copy. You should commit it to restore the file to a working state:

   $ cvs commit -m "restoring previous version" somefile

Committing in a bad directory

If you have committed a file in a bad directory, you have to fix things by moving it to the right directory as soon as possible. Assume you have committed somefile to baddir while it should really go into gooddir. Here is the procedure to correct your mistake:
   $ pwd
   $ cvs remove somefile
   $ mv somefile path/to/gooddir
   $ cd path/to/gooddir
   $ pwd
   $ cvs add somefile
   $ cvs commit -m "move file to the right location" somefile

Translation Guidelines

The following is a set of general translation guidelines that will help you get your job as a translator done correctly.

Stick to translating the pages!

Although we really welcome any help to make the webpages better, your job as a translator is _NOT_ to enhance the pages with pictures, tags, email addresses or anything else that hasn't been in the page before!

If you do have suggestions concerning the content of a page, send them to www@openbsd.org. If they are good, they can be included by one of the developers.

Translation Tags

If you have freshly translated a page to your language you would like to see it committed. And it should and will be maintained. To make this easier and let everybody see who committed this page and follow changes using CVS we use some special tags at the end of the page.

We simply enhance the original $OpenBSD$ tag with two more lines, in which we document from which version our translated file comes from and which version of the translation it is.

A typical OpenBSD ID tag looks like this:

$OpenBSD: index.html,v1.330 2001/04/24 07:11:44 jufi Exp $
From this, you must change the opening and closing $'s and change them to an opening ``Originally ['' and closing ``]'', and add a $Translation$ and an $OpenBSD$ ID tags. Since the Originally and $Translation$ tags are used by translators only, you must comment them so they don't appear when the pages are displayed on a browser:
Originally [OpenBSD: index.html,v 1.330 ]<br>
Notice that we've also added the <br> tags here, which are needed to have each ID tag on a separate line of its own. And we've also stripped off part of the original OpenBSD ID tag, as that bit is not really needed.

As for the $Translation$ and $OpenBSD$ tags, the Steelix and OpenBSD CVS servers will take care of each respectively. So, next time you modify that file, all you will have to do is to replace the content within the Originally [blah... ] ID tag again.

But you should check from file to file whether everything is correct and compare to other files, your own or even those from other languages.

Note: the amount and positions of spaces and words in the tags are absolutely precise and not to be changed! Otherwise you will find your file not recognized correctly by the scripts which build the status page!

It is really helpful to have a look at the pages of the other translators, and watch how they did it.

Meta tags

Meta tags must not be translated or modified, save for the title tag which must be translated of course.


When translating a file from the original English html file to another language, we also need to change the relative links to have them point to the right file they reference.

As a first example, let's suppose you are translating the index.html file, and you find a link to the orders.html file like this:
<a href="orders.html">orders.html</a>.

This means that it will link index.html to orders.html if they are in the same directory level!. So, if you dont have an orders.html file translated yet in your language directory, it will point to a non- existent file. Just go one directory back to link it to the file in the English directory for this example case:
<a href="../orders.html">orders.html</a>.

When you have the orders.html file translated and already in your language directory, you can then strip the ../ off and let it point to the file in your directory.

For a file in the faq/ directory, this is a bit different, since your language directory will be something like faq/de/. So, if you were translating faq1.html and found a link to the faq2.html like this:
<a href="faq2.html">faq2.html</a>

you would have to go back one level as in the previous example to link to the English file (or none if you already have faq2.html translated in your language directory).
BUT, if you had to link from your faq language directory to a file, say, in the first level directory (e.g. orders.html), you would have to go back 2 levels:
<a href="../../orders.html">orders.html</a>.

AND, if orders.html were a translated file, then you would have to go back two levels and then one level forward to your language directory:
<a href="../../de/orders.html">orders.html</a>.

We know this looks messy, but you will get used to it and the best you can do to avoid errors is to check links before you commit (and as you are at it, also check the id tags).

One final note on links: links must *always* be relative, except for external links and links from www.OpenBSD.org to www.OpenSSH.com and vice versa.

Links to images

You'll find most images inside the images/ directory. In fact, all images are kept in there, except for back.gif, which is openbsd-www/back.gif.

This means that when a file is translated and goes into its language directory, the links to the images must be changed too. So, the most commonly used image on the website looks like this on any original file:

<a href="index.html"><img height="24" width="24" src="back.gif" alt="OpenBSD"></a>

but since the translated file will be placed in a different directory, you will have to change the link to back.gif to get it right:

<a href="index.html"><img height="24" width="24" src="../back.gif" alt="OpenBSD"></a>

For the remaining cases, where images are kept in the images/ directory:

<a href="art1.html"><img border="0" src="images/openbsd-logo.gif" height="195"
width="520" alt="[OpenBSD 3.7]"></a>

should be changed to:

<a href="art1.html"><img border="0" src="../images/openbsd-logo.gif" height="195"
width="520" alt="[OpenBSD 3.7]"></a>

This is easy when dealing with normal web pages, but if the file is in the faq or openssh directories, then you have to use something like:

<a href="art1.html"><img border="0" src="../../images/openbsd-logo.gif" height="195"
width="520" alt="[OpenBSD 3.7]"></a>

Accentuated letters

Since some languages such as French make extensive use of accentuated letters, a translator must make sure that the accents on the letters are put in the right places and in the right styles (è not é in a word such as "problème"). The HTML code must not contain the accentuated letters in HTML codification format (such as "&eacute;" for "é").


There are also differences in punctuation between English and other languages, and you need to respect them. Take French for example. The "!", "?", ":" signs always take a space before and a space after as in "Le français est une sacrée langue ! n'est-ce pas ?".

Line wrapping

Verify that your HTML editor wraps lines correctly at 80 columns. If your editor can't do that, there are other ways to do this such as using the Text::Autoformat Perl module. We won't be accepting uncorrectly wrapped files anymore since it requires non-wanted extra work from the coordinators.

English words

English words that cannot be easily translated or that should be kept as-is for clarity must be double-quoted.


Quotes from users, developers, and other people must not be translated. Translating them, without changing meaning, is extremely difficult.

Spell checking

It is highly recommended to use a spell checker in order to validate your work.

Link checking

It is highly recommended to use a link checker such as the linkchecker program (available in the ports collection) to verify the links in the translated files.

Mistakes and typos in the original versions

As in any translation work, you may notice mistakes and/or typos in the original English version of the file that you are currently translating. Please report them back to www@openbsd.org, so they can be fixed by one of the developers. It really helps the project to keep up with the quality standards it strives to maintain.

Mailing list archive of wwwcvs

Although the www translation CVS module is only accessable by translators, the mailing list archive of wwwcvs, which is quite comparable with source-changes, can be accessed by everyone. Due to the synchronization between Steelix and OpenBSD by using simple CVS actions, the commit logs on Steelix are not accessable in OpenBSD's repository. With the wwwcvs mailing list archive, you are still able to give public credit in your commit logs where credit is due.

Translation status

The OpenBSD Translation Status status. It is generated hourly using makereport, a Perl script that you can find in the trtools module on the Steelix CVS repository. You can run makereport by yourself if you want to have more frequent status updates or want to generate a status page only for your language.

HTML tag differences report

The OpenBSD Translation Tag Report page helps translators keep their pages correct with respect to the original versions. It reports any differences found in HTML tags, except allowed differences such as hyperlinks as explained above. The report page contains more instructions on how you can use this tool. A complete tag differences report is generated daily using tagdiff, a Perl script that you can find in the trtools module on the Steelix CVS repository. You can run tagdiff by yourself if you want to have more frequent updates or want to generate a tag report only for your language. Please try to keep the percentage of problem pages as low as possible!

OpenBSD www@openbsd.org
$OpenBSD: translation-explained.html,v 1.25 2010/09/29 12:25:02 ajacoutot Exp $