diff options
author | Nik Clayton <nik@FreeBSD.org> | 1999-07-14 22:30:26 +0000 |
---|---|---|
committer | Nik Clayton <nik@FreeBSD.org> | 1999-07-14 22:30:26 +0000 |
commit | f8c9ffdd226e3c89e584eaccddb1fd93610ca421 (patch) | |
tree | 5c782fe248c3c30484254454b051b1de073255cf /en/tutorials | |
parent | 53b2194d39b951074a86f2470fdc87dc1c4bf5bb (diff) |
Notes
Diffstat (limited to 'en/tutorials')
-rw-r--r-- | en/tutorials/docproj-primer/translations/chapter.sgml | 474 |
1 files changed, 474 insertions, 0 deletions
diff --git a/en/tutorials/docproj-primer/translations/chapter.sgml b/en/tutorials/docproj-primer/translations/chapter.sgml new file mode 100644 index 0000000000..1b3526ab7c --- /dev/null +++ b/en/tutorials/docproj-primer/translations/chapter.sgml @@ -0,0 +1,474 @@ +<!-- Copyright (c) 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $Id: chapter.sgml,v 1.1 1999-07-14 22:30:26 nik Exp $ +--> + +<chapter id="translations"> + <title>Translations</title> + + <para>This is the FAQ for people translating the FreeBSD documentation + (FAQ, Handbook, tutorials, man pages, and others) to different + languages.</para> + + <para>It is <emphasis>very</emphasis> heavily based on the translation FAQ + from the FreeBSD German Documentation Project, originally written by Frank + Grnder <email>elwood@mc5sys.in-berlin.de</email> and translated back to + English by Bernd Warken <email>bwarken@mayn.de</email>.</para> + + <para>The FAQ maintainer is Nik Clayton + <email>nik@FreeBSD.org</email>.</para> + + <qandaset> + <qandaentry> + <question> + <para>Why a FAQ?</para> + </question> + + <answer> + <para>More and more people are approaching the freebsd-doc mailing + list and volunteering to translate FreeBSD documentation to other + languages. This FAQ aims to answer their questions so they can start + translating documentation as quickly as possible.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase> + mean?</para> + </question> + + <answer> + <para><phrase>i18n</phrase> means + <phrase>internationalisation</phrase> and <phrase>l10n</phrase> + means <phrase>localisation</phrase>. They are just a convenient + shorthand.</para> + + <para><phrase>i18n</phrase> can be read as “i” followed by + 18 letters, followed by “n”. Similarly, + <phrase>l10n</phrase> is “l” followed by 10 letters, + followed by “n”.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Is there a mailing list for translators?</para> + </question> + + <answer> + <para>Yes, <email>freebsd-translate@ngo.org.uk</email>. Subscribe by + sending a message to + <email>freebsd-translate-request@ngo.org.uk</email> with the word + <literal>subscribe</literal> in the body of the message.</para> + + <para>You will receive a reply asking you to confirm your subscription + (in exactly the same manner as the the FreeBSD lists at <hostid + role="domainname">FreeBSD.org</hostid>).</para> + + <para>The primary language of the mailing list is English. However, + posts in other languages will be accepted. The mailing list is not + moderated, but you need to be a member of the list before you can + post to it.</para> + + <para>The mailing list is archived, but they are not currently + searchable. Sending the message <literal>help</literal> to + <email>majordomo@ngo.org.uk</email> will send back instructions on + how to access the archive.</para> + + <para>It is expected that the mailing list will transfer to <hostid + role="domainname">FreeBSD.org</hostid> and therefore become + <emphasis>official</emphasis> in the near future.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Are more translators needed?</para> + </question> + + <answer> + <para>Yes. The more people work on translation the faster it gets + done, and the faster changes to the English documentation are + mirrored in the translated documents.</para> + + <para>You do not have to be a professional translator to be able to + help.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What languages do I need to know?</para> + </question> + + <answer> + <para>Ideally, you will have a good knowledge of written English, and + obviously you will need to be fluent in the language you are + translating to.</para> + + <para>English is not strictly necessary. For example, you could do a + Hungarian translation of the FAQ from the Spanish + translation.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What software do I need to know?</para> + </question> + + <answer> + <para>It is strongly recommended that you maintain a local copy of the + FreeBSD CVS repository (at least the documentation part) either + using <application>CTM</application> or + <application>CVSup</application>. The "Staying current with FreeBSD" + chapter in the Handbook explains how to use these + applications.</para> + + <para>You should be comfortable using <application>CVS</application>. + This will allow you to see what has changed between different + versions of the files that make up the documentation.</para> + + <para>[XXX To Do -- write a tutorial that shows how to use CVSup to + get just the documentation, check it out, and see what's changed + between two arbitrary revisions]</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>How do I find out who else might be translating to the same + language?</para> + </question> + + <answer> + <para>The <ulink + url="http://www.freebsd.org/docproj/translations.html">Documentation + Project translations page</ulink> lists the translation efforts + that are currently known about. If someone else is already working + on translating documentation to your language, please don't + duplicate their efforts. Instead, contact them to see how you can + help.</para> + + <para>If no one is listed on that page as translating for your + language then send a message to + <email>freebsd-doc@freebsd.org</email> in case someone else is + thinking of doing a translation, but hasn't announced it yet.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>No one else is translating to my language. What do I do?</para> + </question> + + <answer> + <para>Congratulations, you have just started the “FreeBSD + <replaceable>your-language-here</replaceable> Documentation + Translation Project”. Welcome aboard.</para> + + <para>First, decide whether or not you've got the time to spare. Since + you are the only person working on your language at the moment it is + going to be your responsibility to publicise your work and + coordinate any volunteers that might want to help you.</para> + + <para>Write an e-mail to the Documentation Project mailing list, + announcing that you are going to translate the documentation, so the + Documentation Project translations page can be maintained.</para> + + <para>You should subscribe to the + <email>freebsd-translate@ngo.org.uk</email> mailing list (as + described earlier).</para> + + <para>If there is already someone in your country providing FreeBSD + mirroring services you should contact them and ask if they can + provide some webspace for your project, and possibly an e-mail + address or mailing list services.</para> + + <para>Then pick a document and start translating. It is best to start + with something fairly small—either the FAQ, or one of the + tutorials.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>I've translated some documentation, where do I send it?</para> + </question> + + <answer> + <para>That depends. If you are already working with a translation team + (such as the Japanese team, or the German team) then they will have + their own procedures for handling submitted documentation, and these + will be outlined on their web pages.</para> + + <para>If you are the only person working on a particular language (or + you are responsible for a translation project and want to submit + your changes back to the FreeBSD project) then you should send your + translation to the FreeBSD project (see the next question).</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>I'm the only person working on translating to this language, how + do I submit my translation?</para> + + <para>or</para> + + <para>We're a translation team, and want to submit documentation that + our members have translated for us?</para> + </question> + + <answer> + <para>First, make sure your translation is organised properly. This + means that it should drop in to the existing documentation tree and + build straight away.</para> + + <para>Currently, the FreeBSD documentation is stored in a top level + directory called <filename>doc/</filename>. Directories below this + are named according to the language code they are written in, as + defined in ISO639 (<filename>/usr/share/misc/iso639</filename> on a + version of FreeBSD newer than 20th January 1999).</para> + + <para>If your language can be encoded in different ways (for example, + Chinese) then there should be directories below this, one for each + encoding format you have provided.</para> + + <para>Finally, you should have directories for each document.</para> + + <para>For example, a hypothetical Swedish translation might look + like</para> + + <programlisting> doc/ + sv/ + Makefile + FAQ/ + Makefile + *.sgml</programlisting> + + <para><literal>sv</literal> is the ISO639 code for Swedish. Note the + two Makefiles, which will be used to build the documentation. There + is no separate language code for Swedish, so there is no + intermittent directory between the "sv" and "FAQ" + directories<footnote> + <para>This directory structure is going to change radically quite + soon. Please see the on-going discussions on the + <email>doc@FreeBSD.org</email> mailing list for more + information.</para> + </footnote>.</para> + + <para>Use &man.tar.1; and &man.gzip.1; to compress up your + documentation, and send it to the project.</para> + + <screen>&prompt.user; <userinput>cd doc</userinput> +&prompt.user; <userinput>tar cf swedish-docs.tar sv</userinput> +&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen> + + <para>Put <filename>swedish-docs.tar.gz</filename> somewhere. If you + do not have access to your own webspace (perhaps your ISP does not + let you have any) then you can e-mail Nik Clayton + <email>nik@FreeBSD.org</email>, and arrange to e-mail the files + when it is convenient.</para> + + <para>Either way, you should use &man.send-pr.1; to submit a report + indicating that you have submitted the documentation. It would be + very helpful if you could get other people to look over your + translation and double check it first, since it is unlikely that the + person committing it will be fluent in the language.</para> + + <para>Someone (probably the Documentation Project Manager, currently + Nik Clayton <email>nik@FreeBSD.org</email>) will then take your + translation and confirm that it builds. In particular, the + following things will be looked at:</para> + + <orderedlist> + <listitem> + <para>Do all your files use RCS strings (such as "ID").</para> + </listitem> + + <listitem> + <para>Does <command>make all</command> in the + <filename>sv</filename> directory work correctly.</para> + </listitem> + + <listitem> + <para>Does <command>make install</command> work correctly.</para> + </listitem> + </orderedlist> + + <para>If there are any problems then whoever is looking at the + submission will get back to you to try and work them out.</para> + + <para>If there are no problems then your translation will be committed + as soon as possible.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can I include language or country specific text in my + translation?</para> + </question> + + <answer> + <para>We would prefer that you did not.</para> + + <para>For example, suppose that you are translating the Handbook to + Korean, and want to include a section about retailers in Korea in + your Handbook.</para> + + <para>There's no real reason why that information should not be in the + English (or German, or Spanish, or Japanese, or …) versions + as well. It is feasible that an English speaker in Korea might try + and pick up a copy of FreeBSD whilst over there. It also helps + increase FreeBSD's perceived presence around the globe, which is not + a bad thing.</para> + + <para>If you have country specific information, please submit it as a + change to the English Handbook (using &man.send-pr.1;) and then + translate the change back to your language in the translated + Handbook.</para> + + <para>Thanks.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>How should language specific characters be included?</para> + + <para>Non-ASCII characters in the documentation should be included + using SGML entities.</para> + + <para>Briefly, these look like an ampersand (&), the name of the + entity, and a semi-colon (;).</para> + + <para>The entity names are defined in ISO8879, which is in the ports + tree as <filename>textproc/iso8879</filename>.</para> + + <para>A few examples include</para> + + <segmentedlist> + <seglistitem> + <seg>&eacute;</seg> + <seg>é</seg> + <seg>Small “e” with an acute accent</seg> + </seglistitem> + + <seglistitem> + <seg>&Eacute;</seg> + <seg>É</seg> + <seg>Large “E” with an acute accent</seg> + </seglistitem> + + <seglistitem> + <seg>&uuml;</seg> + <seg>ü</seg> + <seg>Small “u” with an umlaut</seg> + </seglistitem> + </segmentedlist> + + <para>After you have installed the iso8879 port, the files in + <filename>/usr/local/share/sgml/iso8879</filename> contain the + complete list.</para> + </question> + </qandaentry> + + <qandaentry> + <question> + <para>Addressing the reader</para> + </question> + + <answer> + <para>In the English documents, the reader is addressed as + “you”, there is no formal/informal distinction as there + is in some languages.</para> + + <para>If you are translating to a language which does distinguish, use + whichever form is typically used in other technical documentation in + your language. If in doubt, use a mildly polite form.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Do I need to include any additional information in my + translations?</para> + </question> + + <answer> + <para>Yes.</para> + + <para>The header of the English version of each document will look + something like this;</para> + + <programlisting><![ CDATA [<!-- + The FreeBSD Documentation Project + + $Id: chapter.sgml,v 1.11 1999/06/20 21:18:57 billf Exp $ +-->]]></programlisting> + + <para>The exact boilerplate may change, but it will always include an + Id line and the phrase <literal>The FreeBSD Documentation + Project</literal>.</para> + + <para>Your translated documents should include their own Id line, and change the + <literal>FreeBSD Documentation Project</literal> line to + <literal>The FreeBSD <replaceable>language</replaceable> + Documentation Project</literal>.</para> + + <para>In addition, you should add a third line which indicates which + revision of the English text this is based on.</para> + + <para>So, the Spanish version of this file might start</para> + + <programlisting><![ CDATA [<!-- + The FreeBSD Spanish Documentation Project + + $Id: chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $ + Original revision: 1.11 +-->]]></programlisting> + </answer> + </qandaentry> + </qandaset> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> |