os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

A new chapter, explaining how to translate the documentation

Browse source 
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.
This commit is contained in:
Nik Clayton 1999-07-14 22:30:26 +00:00
parent 53b2194d39
commit f8c9ffdd22
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=5217
3 changed files with 1422 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

474
en/tutorials/docproj-primer/translations/chapter.sgml Normal file
View file

@ -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:
-->

474
en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml Normal file
View file

@ -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:
-->

474
en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml Normal file
View file

@ -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:
-->