![[OpenBSD]](images/smalltitle.gif){kind=small}
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?
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.kd85.com 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.kd85.com. 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. The final step before starting to use the CVS repository is to join wwwcvs@docisland.org, the translation mailing list. This is a closed mailing list on which all changes made to the Steelix CVS repository along with any translation related discussions are posted. To join, please send an email to wwwcvs-request@docisland.org with a body containing subscribe.
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.
Issue the following commands to checkout the www translation CVS module from steelix.kd85.com:
$ cd /home/username/devel/openbsd/ $ cvs -d "username@steelix.kd85.com:/cvs" checkout -d "steelix-www" www
The latter command will connect to steelix.kd85.com 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.
$ 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.
| [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.
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.
$ cd ~/devel/openbsd/steelix-www/faq/pf $ mkdir esand 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.
$ cd ~/devel/openbsd/steelix-www $ cvs up -PAdthe 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.
$ 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.
$ 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
$ pwd ...devel/openbsd/steelix-www/.../baddir $ cvs remove somefile $ mv somefile path/to/gooddir $ cd path/to/gooddir $ pwd ...devel/openbsd/steelix-www/.../gooddir $ cvs add somefile $ cvs commit -m "move file to the right location" somefile
The following is a set of general translation guidelines that will help you get your job as a translator done correctly.
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.
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:
<small> $OpenBSD: index.html,v1.330 2001/04/24 07:11:44 jufi Exp $ <small>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:
<small> <!-- Originally [OpenBSD: index.html,v 1.330 ]<br> $Translation$<br> --> $OpenBSD$ </small>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.
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.
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>
www@openbsd.org