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