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