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