Annotation of www/translation-explained.html, Revision 1.29
1.1 saad 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2: "http://www.w3.org/TR/html4/loose.dtd">
3: <html>
4: <head>
5: <title>Contributing to the OpenBSD Translation Effort</title>
6: <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
7: <meta name="resource-type" content="document">
8: <meta name="description" content="Contributing to the OpenBSD Translation effort">
9: <meta name="keywords" content="openbsd,translation,documentation">
10: <meta name="distribution" content="global">
1.19 saad 11: <meta name="copyright" content="This document copyright 2000-2008 by OpenBSD.">
1.1 saad 12: </head>
13:
14: <body bgcolor="#FFFFFF" text="#000000" link="#23238E">
15: <a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>
16: <!-- Passes validator.w3.org, please keep it this way;
17: please, use a max of 72 chars per line -->
18:
1.2 saad 19: <!-- NOTE TO TRANSLATORS
20: As obvious as it may seem, this page must NOT be translated
21: -->
22:
1.5 saad 23: <h2><font color="#e00000">Contributing to the OpenBSD Translation
24: Effort</font></h2>
1.1 saad 25:
26: <hr>
27:
28: <center>
29: <cite>?Nec verbum verbo curabis reddere fidus interpres?</cite>
30: </center>
31:
32: <hr>
33:
34: <h3>Table Of Contents</h3>
35: <ul>
36: <li><a href="#Intro">Introduction</a>
37: <li><a href="#Purpose">Purpose</a>
38: <li><a href="#Maintenance">Maintenance</a>
39: <li><a href="#Joining">Joining the Translation Team</a>
40: <li><a href="#CVS">Using CVS</a>
41: <li><a href="#Guidelines">Translation Guidelines</a>
42: </ul>
43:
44: <hr>
45:
46: <h3><font color="#0000e0"><a name="Intro">Introduction</a></font></h3>
47:
48: <p>
1.6 saad 49: This document should contain all the information you need to
1.1 saad 50: contribute to the OpenBSD translation effort as described in <a
1.3 saad 51: href="translation.html">Translation of the OpenBSD documentation</a>.
52: Please read this document carefully and if you still have questions,
53: don't hesitate to contact <a href="translation.html#WHO">the translation
1.1 saad 54: coordinators</a>.
55:
56: <p>
57:
58: <h3><font color="#0000e0"><a name="Purpose">Purpose</a></font></h3>
59:
60: <p>
61: The purpose for translating
62: <a href="http://www.openbsd.org/">OpenBSD</a> web pages and other
63: documents is to help those who don't speak nor understand English use
64: OpenBSD or, if they do, they might feel more comfortable through reading
65: in their own language. So, by translating you are not only helping the
66: <a href="http://www.openbsd.org/">OpenBSD project</a> to expand, but you
67: are also helping people to become hooked to the system.
68:
69: <p>
70: And of course, you'll gain good knowledge through reading and
71: translating at the same time.
72:
73: <p>
74: It's important to note that besides <a
75: href="http://www.openbsd.org/">OpenBSD</a>, the OpenBSD project has
76: several websites for associated projects that you may want to translate:
77: <ul>
78: <li><a href="http://www.openssh.com/">OpenSSH</a>
79: <li><a href="http://www.openntpd.com/">OpenNTPD</a>
80: <li><a href="http://www.openbgpd.com/">OpenBGPD and OpenOSPFD</a>
81: <li><a href="http://www.opencvs.com/">OpenCVS</a>
82: </ul>
83:
84: <h3><font color="#0000e0"><a name="Maintenance">Maintenance</a></font></h3>
85:
86: <p>
87: Just translating a few web pages, or even translating the whole site
1.3 saad 88: including the <a href="faq/">F.A.Q.</a>, is <strong>ABSOLUTELY
89: NOT</strong> enough. Actually, you could be doing more wrong than good.
90: <strong>Maintaining the translation up to date is just as
91: important</strong>. Always remember that offering outdated information
92: will just misguide people.
1.1 saad 93:
94: <p>
95: If you are not going to keep your work updated, the translation itself
96: will be pointless. Join us only if you think you're going to commit
97: yourself to your work.
98:
99: <p>
100: <strong>Think first how much time you will be able to dedicate to the
101: translation. If you only have some small spare time, don't go overboard
1.6 saad 102: by translating several files you won't be able to maintain
1.1 saad 103: later.</strong>
104:
105: <p>
106: Some files are easier to maintain than others, either because they are
107: small, or because they don't get updated too often. For instance, <a
1.3 saad 108: href="plat.html">plat.html</a> is a small file, and it doesn't get
109: modified often. On the opposite side, <a href="plus.html">plus.html</a>
110: is a heavy file to translate; it grows bigger and bigger from one
1.6 saad 111: release to another, and the technical and slang wording used is
1.3 saad 112: very difficult to translate with accuracy.
1.1 saad 113:
114: <p>
1.6 saad 115: Needless to say, some files take precedence over others. Such is the
1.3 saad 116: case of <a href="index.html">index.html</a> ... or did you think
117: otherwise?
1.1 saad 118:
119: <h3><font color="#0000e0"><a name="Joining">Joining the Translation
120: Team</a></font></h3>
121:
122: <p>
123: Before joining the translation team, you must make sure that you have
1.6 saad 124: the proper environment for translation. The required environment consists
125: of the following elements:
1.1 saad 126: <ul>
1.28 tobias 127: <li>an OpenBSD box running a <strong>stable</strong> release or
128: <strong>current</strong>
1.1 saad 129: <li>OpenSSH
130: <li>CVS
131: <li>a text editor such as vi, vim, mg, etc.
132: <li>an HTML link checker such as linkchecker (available in the ports
133: collection)
134: <li>an HTML validation program such as validate (available in the ports
135: collection)
136: </ul>
137:
138: <p>
139: Once you have the proper environment, you need commit access to the
140: Steelix CVS repository if you want to commit your work directly.
141: Otherwise, you can send them to another translator or one of the
142: translation coordinators to commit them for you (with due credit of
143: course). See <a href="translation.html#WHO">Who is doing this?</a> for
144: more information about the translators and translation coordinators.
145:
146: <p>
1.23 ajacouto 147: The Steelix CVS repository, located at <em>steelix.bsdfrog.org</em> is the
1.1 saad 148: CVS repository used for translation. The translation work is not
149: committed directly to the OpenBSD CVS repository. Rather, the
150: translation coordinators synchronize the two repositories on a timely
151: basis after checking the new commits.
152:
153: <p>
154: To commit on the Steelix CVS repository you will need an account on
1.23 ajacouto 155: <em>steelix.bsdfrog.org</em>. To setup your account, contact one of the
1.1 saad 156: <a href="translation.html#WHO">translation coordinators</a>. If he
157: agrees on giving you an account, you will need to give him the following
158: information by email:
159: <ul>
160: <li>Your full name (first name, last name). No surname/scene name is
161: accepted.
162: <li>A permanent email address on which you can be contacted regarding
163: translation work.
1.6 saad 164: <li>A list of three Unix account names sorted by order of preference.
1.1 saad 165: <li>Your SSH2 DSA public key as an attached file and its SHA-1
166: associated hash. A minimum length of 1024 bits is required for the
167: key.
168: </ul>
169:
170: <p>
171: <strong><font color="#ff0000">Warning:</font></strong> you are fully
172: responsible for the security of your working environment and your SSH2
173: DSA key.
174:
175: <p>
176: Our experience shows that some people request an account, commit some
177: work and then vanish without giving any good reason. Creating your
178: account and maintaining the account database is extra work for the
179: translation coordinators. So they might ask you to send the files to
1.6 saad 180: another translator who will validate your work and your commitment to
1.1 saad 181: the translation effort. This way, we make sure you are here to stay.
182:
183: <p>
184: Once a translation coordinator creates your account, he will notify you
1.25 ajacouto 185: by email. You will be automatically subscribed to the
186: <i>wwwcvs@arcane-networks.net</i> translation mailing list. This is a
187: mailing list on which all changes made to the Steelix CVS repository
188: along with any translation related discussions are posted.
1.1 saad 189:
190: <h3><font color="#0000e0"><a name="CVS">Using CVS</a></font></h3>
191:
192: <p>
193: Now we'll walk you through the basic CVS operations you need to perform
194: as a translator. If you want to have a more in-depth look into CVS
195: usage, please see the
196: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvs&sektion=1">cvs</a>
197: manual page and read
198: <a href="http://cvsbook.red-bean.com/">Open Source Development with CVS,
199: 3rd Edition</a>, a free CVS online book by Karl Fogel and Moshe Bar.
200:
201: <p>
202: You must have a fresh checkout (<em>CVS download</em>, also called a
203: <i>working copy</i> in CVS terminology) of two CVS modules on your disk.
204: These are:
205: <ul>
206: <li>The <i>www translation</i> CVS module. This module must be obtained
1.23 ajacouto 207: from <i>steelix.bsdfrog.org</i>, the OpenBSD translation CVS server.
1.1 saad 208: This is the module on which all translation work happens.
209: <li>The <i>www</i> CVS module. This module must be obtained from one of
210: the many <a href="anoncvs.html"> anonymous OpenBSD CVS mirrors</a>
1.6 saad 211: out there. This will be your source for the original English files
1.1 saad 212: that you need to translate.
213: </ul>
214:
215: <p>
216: <strong><font color="#ff0000">Note:</font></strong> while the <i>www
1.6 saad 217: translation</i> CVS module holds also the English files, they must not
218: be used since they are rarely kept in sync with the English files found
1.1 saad 219: on the anonymous OpenBSD CVS mirrors.
220:
221: <p>
222: The checkouts and later operations are performed using SSH for
223: transport, as you might have guessed after reading the <a
224: href="#Joining">Joining the Translation Team</a> section.
225:
226: <p>
227: Let's see how the checkouts are performed.
228:
229: <h4>Initial checkout of the 'www translation' CVS module</h4>
230: We will assume that you are going to put all the translation work files
231: and directories under <i>/home/username/devel/openbsd/</i>. Of course,
232: this is absolutely not a requirement. This scheme is solely used for the
233: examples below. Change as needed.
234:
235: <p>
236: Issue the following commands to checkout the <i>www translation</i> CVS
1.23 ajacouto 237: module from <i>steelix.bsdfrog.org</i>:
1.1 saad 238:
239: <pre>
240: $ cd /home/username/devel/openbsd/
1.23 ajacouto 241: $ cvs -d "username@steelix.bsdfrog.org:/cvs" checkout -d "steelix-www" www
1.1 saad 242: </pre>
243:
244: <p>
1.23 ajacouto 245: The latter command will connect to <i>steelix.bsdfrog.org</i> using SSH as
1.1 saad 246: user <i>username</i> to retrieve a working copy of the <i>www
247: translation</i> CVS module and store it under <i>steelix-www</i>.
248:
249: <p>
250: The SSH authentication is set up to use your SSH2 key, which requires
251: you to enter your passphrase to proceed. SSH is used for checkout and
252: all other CVS operations. By default, this will ask you everytime for
253: your passphrase. To save some typing, you might want to load your SSH2
254: private key in
255: <i><a
256: href="http://www.openbsd.org/cgi-bin/man.cgi?query=ssh-agent&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html">ssh-agent</a></i> using <i>keychain</i> (available in the ports collection) or some
257: home-cooked recipe.
258:
259: <p>
260: After successfully entering your passphrase, CVS will proceed with
261: checking out your working copy. Depending on your connection speed, this
262: operation may take some time to complete.
263:
264: <p>
265: Once the checkout terminates, you will have a <strong>working copy of
266: the www translation CVS module</strong>.
267:
268: <h4>Initial checkout of the 'www' CVS module</h4>
269: To obtain a working copy of the <i>www</i> CVS module, you need to find
1.7 saad 270: an OpenBSD anonymous CVS mirror near you that is updated frequently.
1.1 saad 271: Suppose you are located in Germany. According to the <a
272: href="anoncvs.html">OpenBSD AnonCVS</a> page,
1.14 grunk 273: <i>anoncvs.de.openbsd.org</i> looks like a good candidate. It is
1.1 saad 274: maintained by one of the OpenBSD developers (Alexander von Gernler) and
275: updated every 2 hours. Moreover, it offers CVS through SSH. Let's use it
276: to obtain the working copy of the <i>www</i> CVS module:
277:
278: <pre>
279: $ cd /home/username/devel/openbsd
1.14 grunk 280: $ cvs -d "anoncvs@anoncvs.de.openbsd.org:/cvs" checkout -d "openbsd-www" www
1.1 saad 281: </pre>
282:
283: <p>
284: The latter command will connect to
1.14 grunk 285: <i>anoncvs@anoncvs.de.openbsd.org</i> using SSH as user <i>anoncvs</i>
1.1 saad 286: to retrieve a working copy of the <i>www </i> CVS module and store it
287: under <i>openbsd-www</i>. SSH won't ask for authentication since we are
288: using an anonymous CVS account. Depending on your connection speed, this
289: operation may take some time to complete.
290:
291: <p>
292: Once the checkout terminates, you will have a <strong>working copy of
293: the www CVS module</strong>.
294:
295: <h4>Organization of the 'www' CVS module</h4>
296: <a name="sections"></a>
297: The <i>www</i> CVS module that the OpenBSD and associated projects'
1.12 steven 298: websites are made of is constituted of ten sections.
299: The table below lists all these sections and what they represent.
1.1 saad 300:
301: <p>
1.12 steven 302: <table border="1">
303: <tr valign="top"><td>
1.1 saad 304: <strong>[base]</strong>
1.12 steven 305: </td><td>
1.1 saad 306: <a href="http://www.openbsd.org/">http://www.openbsd.org/</a> and
307: everything under it <strong>except</strong> for the FAQ available at
1.3 saad 308: <a href="faq/">http://www.openbsd.org/faq/</a>.
1.12 steven 309: </td></tr><tr valign="top"><td>
1.1 saad 310: <strong>[faq]</strong>
1.12 steven 311: </td><td>
1.3 saad 312: <a href="faq/">http://www.openbsd.org/faq/</a>
1.1 saad 313: and everything under it <strong>except</strong> for the PF User Guide
314: available at
1.4 saad 315: <a href="faq/pf/">http://www.openbsd.org/faq/pf/</a>.
1.12 steven 316: </td></tr><tr valign="top"><td>
1.1 saad 317: <strong>[openbgpd]</strong>
1.12 steven 318: </td><td>
1.1 saad 319: <a href="http://www.openbgpd.org/">http://www.openbgpd.org/</a>
320: and the associated subdirectories.
1.12 steven 321: </td></tr><tr valign="top"><td>
1.1 saad 322: <strong>[opencvs]</strong>
1.12 steven 323: </td><td>
1.1 saad 324: <a href="http://www.opencvs.org/">http://www.opencvs.org/</a>
325: and the associated subdirectories.
1.12 steven 326: </td></tr><tr valign="top"><td>
1.1 saad 327: <strong>[openntpd]</strong>
1.12 steven 328: </td><td>
1.1 saad 329: <a href="http://www.openntpd.org/">http://www.openntpd.org/</a>
330: and the associated subdirectories.
1.12 steven 331: </td></tr><tr valign="top"><td>
1.1 saad 332: <strong>[openssh]</strong>
1.12 steven 333: </td><td>
1.1 saad 334: <a href="http://www.openssh.com/">http://www.openssh.com/</a>
335: and the associated subdirectories <strong>except</strong> the usage
336: subdirectory.
1.12 steven 337: </td></tr><tr valign="top"><td nowrap="nowrap">
1.1 saad 338: <strong>[openssh-usage]</strong>
1.12 steven 339: </td><td>
1.1 saad 340: <a href="http://www.openssh.com/usage/">http://www.openssh.com/usage/</a>.
1.12 steven 341: </td></tr><tr valign="top"><td>
1.1 saad 342: <strong>[papers]</strong>
1.12 steven 343: </td><td>
1.3 saad 344: <a href="papers/">http://www.openbsd.org/papers/</a> and the associated
345: subdirectories.
1.12 steven 346: </td></tr><tr valign="top"><td>
1.1 saad 347: <strong>[pf]</strong>
1.12 steven 348: </td><td>
1.3 saad 349: <a href="faq/pf/">http://www.openbsd.org/faq/pf/</a> and everything
350: under it.
1.12 steven 351: </td></tr><tr valign="top"><td>
1.27 sthen 352: <strong>[ports]</strong>
1.12 steven 353: </td><td>
1.27 sthen 354: <a href="faq/ports/">http://www.openbsd.org/faq/ports/</a> and the
1.3 saad 355: associated subdirectories.
1.12 steven 356: </td></tr>
357: </table>
1.1 saad 358:
359: <p>
360: Translated pages in a given language for a given section are located
361: under a subdirectory in that section. The subdirectory name is the
362: two-letter
363: <a href="http://lcweb.loc.gov/standards/iso639-2/englangn.html">ISO 639-1 language code</a>
364: of the language. For example, french [faq] pages are located under
1.3 saad 365: <a href="faq/fr/">http://www.openbsd.org/faq/fr/</a>.
1.1 saad 366:
367: <p>
368: The <i>www translation</i> CVS module is organized in an identical
1.7 saad 369: fashion. While the <i>www</i> CVS module is your source for the English
1.1 saad 370: original files that you need to translate or sync against, the <i>www
371: translation</i> CVS module will host all your translation work as we
372: mentioned earlier.
373:
374: <h4>Working on the 'www translation' module</h4>
375: You <strong>must not</strong> touch any file within the first level of
376: any <a href="#sections">section</a> of the <i>www translation</i> CVS
377: module. If, by mistake, you edited and modified one of the files in the
378: first level, don't edit it back to reverse those changes, the timestamps
379: will have changed and you will mess the remote repository next time you
1.6 saad 380: <kbd>'cvs up -PAd'</kbd> followed by <kbd>'cvs commit'</kbd>. Instead,
1.1 saad 381: just <kbd>rm -f</kbd> that file and follow the instructions to <a
382: href="#update">update</a>. An update from the CVS repository will
1.6 saad 383: restore that file in your working copy. Likewise, avoid changing the
1.1 saad 384: files from languages other than yours.
385:
386: <p>
387: You must do your work within your language directory. If it doesn't
388: exist yet, you can read how to <a href="#add">add</a> a new directory
389: or file in the next section.
390:
391: <p>
392: Thus, for a given language such as Spanish, the language directory will
393: be denoted by the two-letter
394: <a href="http://lcweb.loc.gov/standards/iso639-2/englangn.html">ISO
395: 639-1 language code</a>, <i>es/</i> in this case, and files will be
396: organized as follows:
397: <ul>
398: <li><em>steelix-www/es/</em> - www.openbsd.org/es/ files.
399: <li><em>steelix-www/faq/es/</em> - www.openbsd.org/faq/es/ files.
400: <li><em>steelix-www/openssh/es/</em> - www.openssh.com/es/ files.
401: <li>...
402: </ul>
403:
404: <p>
405: This is important to remember as far as relative <a
406: href="#Links">links</a> go.
407:
408: <a name="add"></a>
409: <h4>Adding directories and files</h4>
410: Suppose that there was no Spanish directory as yet under the
411: <strong>[pf]</strong> section. We would create it first on our local
412: repository:
413:
414: <pre>
415: $ cd ~/devel/openbsd/steelix-www/faq/pf
416: $ mkdir es
417: </pre>
418:
419: and then we would have to <strong>add</strong> it to the CVS repository:
420:
421: <pre>
1.5 saad 422: $ cvs add es
1.1 saad 423: </pre>
424:
425: <p>
1.7 saad 426: That was easy. Next we would copy an English original file that we would
1.1 saad 427: like to translate from the <i>www</i> module (e.g.
428: <i>openbsd-www/faq/pf/index.html</i>) into the es/ directory and would
429: add it as well:
430:
431: <pre>
432: $ cd ~/devel/openbsd
433: $ cp -p openbsd-www/faq/pf/index.html steelix-www/faq/pf/es/
434: $ cd steelix-www/faq/pf/es
435: $ cvs add index.html
436: </pre>
437:
438: <p>
439: <strong>Note<sup>(1)</sup></strong>: while <kbd>cvs add</kbd>'ing a
440: directory will change the remote repository straight away, it won't do
441: so if we were adding a file until we run the <a
442: href="#commit">commit</a> command.
443:
444: <p>
1.26 ajacouto 445: <strong>Note<sup>(2)</sup></strong>: cvs is by default configured to
446: perform special keyword substitution, and this feature is extensively
447: used by the <i>www</i> translation project. So please make sure that
448: your <kbd>cvs add</kbd> does not specify a different substitution mode,
449: e.g. by having an entry like <kbd>add -ko</kbd> in your <i>.cvsrc</i>
450: file.
451:
452: <p>
453: <strong>Note<sup>(3)</sup></strong>: see the <kbd>rm</kbd> command in the
1.6 saad 454: CVS manual page to know how to remove a file or directory.
1.1 saad 455:
456: <a name="update"></a>
457: <h4>Updating files</h4>
1.6 saad 458: If, while in the <em>steelix-www/</em> directory, we ran the command and
459: options:
1.1 saad 460:
461: <pre>
462: $ cd ~/devel/openbsd/steelix-www
463: $ cvs up -PAd
464: </pre>
465:
466: the effect would be twofold:
467:
468: <ul>
469: <li>All changes made by others to the <i>www translation</i> module on
470: the CVS repository would be automatically applied to our working
471: copy. The working copy <strong>will</strong> change.
472: <li>All changes made by us to our working copy <em>would be ready to be
473: "uploaded"</em> to the CVS repository. The <i>www translation</i>
474: module on the CVS repository <strong>will not</strong> change until
475: we run the <a href="#commit">commit</a> command.
476: </ul>
477:
478: <p>
479: <strong>Note:</strong> it is suggested to run this command before we
480: start making changes to our working copy, so we can see what changes
481: have been made by others and avoid conflicts.
482:
483: <a name="commit"></a>
484: <h4>Committing changes</h4>
485: This is the mother of all commands:
486:
487: <pre>
488: $ cd faq/pf/es
489: $ cvs commit
490: </pre>
491:
492: <p>
493: This command will load an editor such as <i>vi</i> so you can enter a
494: commit message. This message will allow others to have an idea of the
495: change(s) that you've made. It is automatically posted to the
496: translation mailing list.
497:
498: <p>
499: Needless to say that you only commit when you feel your changes should
1.6 saad 500: definitely go into the <i>www translation</i> of the CVS repository.
1.1 saad 501:
502: <a name="revert"></a>
503: <h4>Reverting a change</h4>
1.9 saad 504: If you have committed a file and you discover that your commit breaks
505: something, you have to revert the commit as soon as possible. Assume the
506: problem lays in a file called <i>somefile</i>. Follow the procedure
507: below to revert it to an unbroken revision:
1.1 saad 508:
509: <pre>
1.9 saad 510: $ cvs log somefile
1.1 saad 511: </pre>
512:
513: <p>
514: At the top of the output, you can see the latest revision of the file
515: (your latest modifications). For example, <i>1.192</i>. You have to
516: checkout the previous revision and commit it to fix the issue.
517:
518: <pre>
1.9 saad 519: $ cvs update -A somefile
520: $ rm somefile
521: $ cvs update -p -r1.191 somefile > somefile
1.1 saad 522: </pre>
523:
524: <p>
1.9 saad 525: <i>1.191</i> is indeed the previous revision. It is now in your working
526: copy. You should commit it to restore the file to a working state:
1.1 saad 527:
528: <pre>
1.9 saad 529: $ cvs commit -m "restoring previous version" somefile
530: </pre>
531:
532: <a name="wrongdir"></a>
533: <h4>Committing in a bad directory</h4>
534: If you have committed a file in a bad directory, you have to fix things
535: by moving it to the right directory as soon as possible. Assume you have
536: committed <i>somefile</i> to <i>baddir</i> while it should really go
537: into <i>gooddir</i>. Here is the procedure to correct your mistake:
538:
539: <pre>
540: $ pwd
541: ...devel/openbsd/steelix-www/.../baddir
542: $ cvs remove somefile
543: $ mv somefile path/to/gooddir
544: $ cd path/to/gooddir
545: $ pwd
546: ...devel/openbsd/steelix-www/.../gooddir
547: $ cvs add somefile
548: $ cvs commit -m "move file to the right location" somefile
1.1 saad 549: </pre>
550:
551: <h3><font color="#0000e0"><a name="Guidelines">Translation
552: Guidelines</a></font></h3>
553:
554: <p>
1.7 saad 555: The following is a set of general translation guidelines that will help you
1.1 saad 556: get your job as a translator done correctly.
557:
558: <h4>Stick to translating the pages!</h4>
559: <strong>Although we really welcome any help to make the webpages better,
560: your job as a translator is _NOT_ to enhance the pages with pictures,
1.18 aanriot 561: tags, email addresses or anything else that hasn't been in the page
1.5 saad 562: before!</strong>
1.1 saad 563:
564: <h4>Translation Tags</h4>
565: If you have freshly translated a page to your language you would like to
566: see it committed. And it should and will be maintained. To make this
567: easier and let everybody see who committed this page and follow changes
568: using CVS we use some special tags at the end of the page.
569:
570: <p>
571: We simply enhance the original $OpenBSD$ tag with two more
572: lines, in which we document from which version our translated file comes
573: from and which version of the translation it is.
574:
575: <p>
576: A typical OpenBSD ID tag looks like this:
577:
578: <pre><small>
579: $OpenBSD: index.html,v1.330 2001/04/24 07:11:44 jufi Exp $
580: <small>
581: </pre>
582:
583: From this, you must change the opening and closing <tt>$</tt>'s and
584: change them to an opening ``<tt>Originally [</tt>'' and closing
585: ``<tt>]</tt>'', and add a <tt>$Translation$</tt> and an
586: <tt>$OpenBSD$</tt> ID tags. Since the <tt>Originally</tt> and
587: <tt>$Translation$</tt> tags are used by translators only, you
588: must comment them so they don't appear when the pages are displayed on a
589: browser:
590:
591: <pre><small>
592: <!--
1.6 saad 593: Originally [OpenBSD: index.html,v 1.330 ]<br>
1.1 saad 594: $Translation$<br>
595: -->
596: $OpenBSD$
597: </small>
598: </pre>
599:
600: Notice that we've also added the <tt><br></tt> tags here, which
601: are needed to have each ID tag on a separate line of its own. And we've
602: also stripped off part of the original OpenBSD ID tag, as that bit is
603: not really needed.
604:
605: <p>
606: As for the <tt>$Translation$</tt> and
607: <tt>$OpenBSD$</tt> tags, the Steelix and OpenBSD CVS servers
608: will take care of each respectively. So, next time you modify that file,
609: all you will have to do is to replace the content within the
610: <tt>Originally [blah... ]</tt> ID tag again.
611:
612: <p>
1.7 saad 613: But you should check from file to file whether everything is correct
614: and compare to other files, your own or even those from other languages.
1.1 saad 615:
616: <p>
617: <strong><font color="#ff0000">Note:</font></strong> the amount and
1.7 saad 618: positions of spaces and words in the tags are absolutely precise and not
619: to be changed!
1.1 saad 620: Otherwise you will find your file not recognized correctly by the
1.17 saad 621: scripts which build the
1.22 tobias 622: <a href="http://steelix.bsdfrog.org/status/makereport.html">status page</a>!
1.1 saad 623:
624: <p>
625: It is really helpful to have a look at the pages of the other
626: translators, and watch how they did it.
627:
1.13 saad 628: <h4>Meta tags</h4>
629: Meta tags must not be translated or modified, save for the
630: <strong>title</strong> tag which must be translated of course.
631:
1.1 saad 632: <a name="Links"></a>
633: <h4>Links</h4>
634: When translating a file from the original English html file to another
635: language, we also need to change the relative links to have them point
636: to the right file they reference.
637:
638: <p>
639: As a first example, let's suppose you are translating the
640: <i>index.html</i> file, and you find a link to the orders.html file like
641: this:<br> <tt><strong><a href="orders.html">orders.html</a></strong></tt>.
642:
643: <p>
644: This means that it will link <em>index.html</em> to
645: <em>orders.html</em> <strong>if they are in the same directory
646: level!</strong>. So, if you dont have an <em>orders.html</em> file
647: translated yet in your language directory, it will point to a non-
648: existent file. Just go one directory back to link it to the file in the
649: English directory for this example case:<br> <tt><strong><a
650: href="../orders.html">orders.html</a></strong></tt>.
651:
652: <p>
653: When you have the <em>orders.html</em> file translated and already in
654: your language directory, you can then strip the
1.7 saad 655: <tt><strong>../</strong></tt> off and let it point to the file in your
656: directory.
1.1 saad 657:
658: <p>
659: For a file in the <em>faq/</em> directory, this is a bit different,
660: since your language directory will be something like <em>faq/de/</em>.
661: So, if you were translating <em>faq1.html</em> and found a link to the
662: <em>faq2.html</em> like this:<br>
663: <tt><strong><a href="faq2.html">faq2.html</a></strong></tt>
664:
665: <p>
666: you would have to go back one level as in the previous example to link
667: to the English file (or none if you already have faq2.html translated in
668: your language directory).<br> BUT, if you had to link from your faq
669: language directory to a file, say, in the first level directory (e.g.
670: <em>orders.html</em>), you would have to go back <strong>2
671: levels</strong>:<br> <tt><strong><a
672: href="../../orders.html">orders.html</a></strong></tt>.
673:
674: <p>
675: AND, if <em>orders.html</em> were a translated file, then you would have
1.6 saad 676: to go back two levels and then one level forward to your language
1.1 saad 677: directory:<br> <tt><strong><a
678: href="../../de/orders.html">orders.html</a></strong></tt>.
679:
680: <p>
1.6 saad 681: We know this looks messy, but you will get used to it and the best you
1.1 saad 682: can do to avoid errors is to check links before you commit (and as you
683: are at it, also check the id tags).
684:
685: <p>
686: One final note on links: links must *always* be relative, except for
687: external links and links from www.OpenBSD.org to www.OpenSSH.com and
688: vice versa.
689:
690: <h4>Links to images</h4>
1.29 ! deraadt 691: You'll find most images inside the <em>images/</em> directory.
1.1 saad 692:
693: <p>
694: This means that when a file is translated and goes into its language
695: directory, the links to the images <i>must</i> be changed too. So, the
696: most commonly used image on the website looks like this on any original
697: file:
698:
699: <pre><a href="index.html"><img height="24" width="24" src=<strong>"back.gif"</strong> alt="OpenBSD"></a>
700: </pre>
701:
702: <p>
703: For the remaining cases, where images are kept in the <em>images/</em>
704: directory:
705:
706: <pre><a href="art1.html"><img border="0" src=<strong>"images/openbsd-logo.gif"</strong> height="195"
1.6 saad 707: width="520" alt="[OpenBSD 3.7]"></a>
1.1 saad 708: </pre>
709:
710: <p>
711: should be changed to:
712:
713: <pre><a href="art1.html"><img border="0" src=<strong>"../images/openbsd-logo.gif"</strong> height="195"
1.6 saad 714: width="520" alt="[OpenBSD 3.7]"></a>
1.1 saad 715: </pre>
716:
717: <p>
718: This is easy when dealing with normal web pages, but if the file is in
719: the <em>faq</em> or <em>openssh</em> directories, then you have to use
720: something like:
721:
722: <pre><a href="art1.html"><img border="0" src=<strong>"../../images/openbsd-logo.gif"</strong> height="195"
1.6 saad 723: width="520" alt="[OpenBSD 3.7]"></a>
1.1 saad 724: </pre>
725:
726: <h4>Accentuated letters</h4>
1.7 saad 727: Since some languages such as French make extensive use of accentuated
1.1 saad 728: letters, a translator must make sure that the accents on the letters are
1.7 saad 729: put in the right places and in the right styles (è not é
1.1 saad 730: in a word such as "problème"). The HTML code must not
1.6 saad 731: contain the accentuated letters in HTML codification format (such as
1.1 saad 732: "&eacute;" for "é").
733:
734: <h4>Punctuation</h4>
735: There are also differences in punctuation between English and other
1.7 saad 736: languages, and you need to respect them. Take French for example. The
1.1 saad 737: "!", "?", ":" signs always take a space
738: before and a space after as in "Le français est une
739: sacrée langue ! n'est-ce pas ?".
740:
741: <h4>Line wrapping</h4>
1.6 saad 742: Verify that your HTML editor wraps lines correctly at 80 columns. If your
1.1 saad 743: editor can't do that, there are other ways to do this such as using the
744: Text::Autoformat Perl module. We won't be accepting uncorrectly wrapped
745: files anymore since it requires non-wanted extra work from the
746: coordinators.
747:
748: <h4>English words</h4>
749: English words that cannot be easily translated or that should be kept
750: as-is for clarity must be double-quoted.
751:
1.13 saad 752: <h4>Quotes</h4>
753: Quotes from users, developers, and other people must not be translated.
754: Translating them, without changing meaning, is extremely difficult.
755:
1.1 saad 756: <h4>Spell checking</h4>
757: It is highly recommended to use a spell checker in order to validate
758: your work.
759:
760: <h4>Link checking</h4>
761: It is highly recommended to use a link checker such as the
762: <a href="http://linkchecker.sourceforge.net/">linkchecker</a> program
763: (available in the ports collection) to verify the links in the
764: translated files.
765:
766: <h4>Mistakes and typos in the original versions</h4>
767: As in any translation work, you may notice mistakes and/or typos in the
1.6 saad 768: original English version of the file that you are currently translating.
1.1 saad 769:
1.24 tobias 770: <h4>Mailing list archive of wwwcvs</h4>
771: Although the <i>www translation</i> CVS module is only accessable by
772: translators, the
773: <a href="http://smtp0a.arcane-networks.net/pipermail/wwwcvs/">mailing
774: list archive</a> of <i>wwwcvs</i>, which is quite comparable with
775: <i>source-changes</i>, can be accessed by everyone. Due to the
776: synchronization between Steelix and OpenBSD by using simple CVS actions,
777: the commit logs on Steelix are not accessable in OpenBSD's repository.
778: With the <i>wwwcvs</i> mailing list archive, you are still able to give
779: public credit in your commit logs where credit is due.
780:
1.1 saad 781: <h4>Translation status</h4>
1.17 saad 782: The
1.22 tobias 783: <a href="http://steelix.bsdfrog.org/status/makereport.html">OpenBSD
1.19 saad 784: Translation Status</a>
1.1 saad 785: status. It is generated hourly using <i>makereport</i>, a Perl script
786: that you can find in the <i>trtools</i> module on the Steelix CVS
787: repository. You can run <i>makereport</i> by yourself if you want to
788: have more frequent status updates or want to generate a status page only
789: for your language.
790:
1.11 steven 791: <h4>HTML tag differences report</h4>
1.21 tobias 792: The
1.22 tobias 793: <a href="http://steelix.bsdfrog.org/status/tagdiff.html"
1.11 steven 794: >OpenBSD Translation Tag Report</a> page helps translators keep their
795: pages correct with respect to the original versions. It reports any
796: differences found in HTML tags, except allowed differences such as
797: hyperlinks as explained above.
798: The report page contains more instructions on how you can use this tool.
799: A complete tag differences report is generated daily using <i>tagdiff</i>,
800: a Perl script that you can find in the <i>trtools</i> module on the
801: Steelix CVS repository. You can run <i>tagdiff</i> by yourself if you
802: want to have more frequent updates or want to generate a tag report only
803: for your language.
804: Please try to keep the percentage of problem pages as low as possible!
1.1 saad 805: <p>
806:
807: </body>
808: </html>
![[BACK]](/icons/back.gif){kind=icon}
Return to translation-explained.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / www