aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>1999-07-14 22:30:26 +0000
committerNik Clayton <nik@FreeBSD.org>1999-07-14 22:30:26 +0000
commitf8c9ffdd226e3c89e584eaccddb1fd93610ca421 (patch)
tree5c782fe248c3c30484254454b051b1de073255cf /en_US.ISO8859-1
parent53b2194d39b951074a86f2470fdc87dc1c4bf5bb (diff)
downloaddoc-f8c9ffdd226e3c89e584eaccddb1fd93610ca421.tar.gz
doc-f8c9ffdd226e3c89e584eaccddb1fd93610ca421.zip
A new chapter, explaining how to translate the documentation
to other languages. Well, not exactly, this is more of a FAQ than a proper tutorial. But (1) it gets it out of the plain text format I've been sending out over the past 4 months, (2) it gets it better publicised than it has been, and (3) it shows anyone that wants to see how to markup a FAQ than a proper tutorial. But (1) it gets it out of the plain text format I've been sending out over the past 4 months, (2) it gets it better publicised than it has been, and (3) it shows anyone that wants to see how to markup a FAQ in DocBook exactly how to do it.
Notes
Notes: svn path=/head/; revision=5217
Diffstat (limited to 'en_US.ISO8859-1')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml474
1 files changed, 474 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml
new file mode 100644
index 0000000000..1b3526ab7c
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-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 &ldquo;i&rdquo; followed by
+ 18 letters, followed by &ldquo;n&rdquo;. Similarly,
+ <phrase>l10n</phrase> is &ldquo;l&rdquo; followed by 10 letters,
+ followed by &ldquo;n&rdquo;.</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 &ldquo;FreeBSD
+ <replaceable>your-language-here</replaceable> Documentation
+ Translation Project&rdquo;. 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&mdash;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 &hellip;) 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 (&amp;), 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>&amp;eacute;</seg>
+ <seg>&eacute;</seg>
+ <seg>Small &ldquo;e&rdquo; with an acute accent</seg>
+ </seglistitem>
+
+ <seglistitem>
+ <seg>&amp;Eacute;</seg>
+ <seg>&Eacute;</seg>
+ <seg>Large &ldquo;E&rdquo; with an acute accent</seg>
+ </seglistitem>
+
+ <seglistitem>
+ <seg>&amp;uuml;</seg>
+ <seg>&uuml;</seg>
+ <seg>Small &ldquo;u&rdquo; 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
+ &ldquo;you&rdquo;, 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
+
+ &dollar;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
+
+ &dollar;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:
+-->