Whitespace-only fixes. Translators, please ignore.

This commit is contained in:
Warren Block 2012-05-21 14:43:21 +00:00
parent 54e191e028
commit 0fcdcf3172
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=38871

View file

@ -33,13 +33,14 @@
<chapter id="translations">
<title>Translations</title>
<para>This is the FAQ for people translating the FreeBSD documentation
(FAQ, Handbook, tutorials, manual 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
Gr&uuml;nder <email>elwood@mc5sys.in-berlin.de</email> and translated back to
<para>This is the FAQ for people translating the FreeBSD
documentation (FAQ, Handbook, tutorials, manual 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 Gr&uuml;nder
<email>elwood@mc5sys.in-berlin.de</email> and translated back to
English by Bernd Warken <email>bwarken@mayn.de</email>.</para>
<para>The FAQ is maintained by the &a.doceng;.</para>
@ -51,10 +52,11 @@
</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>
<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>
@ -63,17 +65,17 @@
<para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
mean?</para>
</question>
<answer>
<para><phrase>i18n</phrase> means
<phrase>internationalization</phrase> and <phrase>l10n</phrase>
means <phrase>localization</phrase>. They are just a convenient
shorthand.</para>
<phrase>internationalization</phrase> and
<phrase>l10n</phrase> means <phrase>localization</phrase>.
They are just a convenient shorthand.</para>
<para><phrase>i18n</phrase> can be read as <quote>i</quote> followed by
18 letters, followed by <quote>n</quote>. Similarly,
<phrase>l10n</phrase> is <quote>l</quote> followed by 10 letters,
followed by <quote>n</quote>.</para>
<para><phrase>i18n</phrase> can be read as <quote>i</quote>
followed by 18 letters, followed by <quote>n</quote>.
Similarly, <phrase>l10n</phrase> is <quote>l</quote>
followed by 10 letters, followed by <quote>n</quote>.</para>
</answer>
</qandaentry>
@ -83,10 +85,12 @@
</question>
<answer>
<para>Yes. Different translation groups have their own mailing
lists. The <ulink url="http://www.freebsd.org/docproj/translations.html">list
of translation projects</ulink> has more information about the
mailing lists and web sites run by each translation project.</para>
<para>Yes. Different translation groups have their own
mailing lists. The <ulink
url="http://www.freebsd.org/docproj/translations.html">list
of translation projects</ulink> has more information about
the mailing lists and web sites run by each translation
project.</para>
</answer>
</qandaentry>
@ -96,12 +100,13 @@
</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>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>
<para>You do not have to be a professional translator to be
able to help.</para>
</answer>
</qandaentry>
@ -111,139 +116,151 @@
</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>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
<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
<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>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 has changed
between two arbitrary revisions]</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 has 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>
<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 others are already working
on translating documentation to your language, please do not
duplicate their efforts. Instead, contact them to see how you can
help.</para>
Project translations page</ulink> lists the translation
efforts that are currently known about. If others are
already working on translating documentation to your
language, please do not 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 the &a.doc; in case someone else
is thinking of doing a translation, but has not announced it yet.
</para>
language, then send a message to the &a.doc; in case someone
else is thinking of doing a translation, but has not
announced it yet.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>No one else is translating to my language. What do I do?</para>
<para>No one else is translating to my language. What do I
do?</para>
</question>
<answer>
<para>Congratulations, you have just started the <quote>FreeBSD
<replaceable>your-language-here</replaceable> Documentation
Translation Project</quote>. Welcome aboard.</para>
<para>Congratulations, you have just started the
<quote>FreeBSD <replaceable>your-language-here</replaceable>
Documentation Translation Project</quote>. Welcome
aboard.</para>
<para>First, decide whether or not you have 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 publicize your work and
coordinate any volunteers that might want to help you.</para>
<para>First, decide whether or not you have 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 publicize your work and coordinate any volunteers that
might want to help you.</para>
<para>Write an email 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>Write an email 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>If there is already someone in your country providing FreeBSD
mirroring services you should contact them and ask if you can
have some webspace for your project, and possibly an email
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>
<para>If there is already someone in your country providing
FreeBSD mirroring services you should contact them and ask
if you can have some webspace for your project, and possibly
an email 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 have translated some documentation, where do I send it?</para>
<para>I have 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>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>
<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 am the only person working on translating to this language, how
do I submit my translation?</para>
<para>I am the only person working on translating to this
language, how do I submit my translation?</para>
<para>or</para>
<para>We are a translation team, and want to submit documentation that
our members have translated for us?</para>
<para>We are 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 organized properly. This
means that it should drop into the existing documentation tree and
build straight away.</para>
<para>First, make sure your translation is organized properly.
This means that it should drop into 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>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>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>Finally, you should have directories for each
document.</para>
<para>For example, a hypothetical Swedish translation might look
like:</para>
<para>For example, a hypothetical Swedish translation might
look like:</para>
<programlisting>doc/
sv_SE.ISO8859-1/
@ -256,8 +273,8 @@
<para><literal>sv_SE.ISO8859-1</literal> is the name of the
translation, in
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
form. Note the
two Makefiles, which will be used to build the documentation.</para>
form. Note the two Makefiles, which will be used to build
the documentation.</para>
<para>Use &man.tar.1; and &man.gzip.1; to compress up your
documentation, and send it to the project.</para>
@ -266,41 +283,47 @@
&prompt.user; <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</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 email &a.doceng;, and arrange to email
the files when it is convenient.</para>
<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 email
&a.doceng;, and arrange to email 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>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
&a.doceng;) will then take your translation and confirm that it builds.
In particular, the following things will be looked at:</para>
<para>Someone (probably the Documentation Project Manager,
currently &a.doceng;) 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>
<para>Do all your files use RCS strings (such as
"ID")?</para>
</listitem>
<listitem>
<para>Does <command>make all</command> in the
<filename>sv_SE.ISO8859-1</filename> directory work correctly?</para>
<filename>sv_SE.ISO8859-1</filename> directory work
correctly?</para>
</listitem>
<listitem>
<para>Does <command>make install</command> work correctly?</para>
<para>Does <command>make install</command> work
correctly?</para>
</listitem>
</orderedlist>
</orderedlist>
<para>If there are any problems then whoever is looking at the
submission will get back to you to work them out.</para>
<para>If there are no problems your translation will be committed
as soon as possible.</para>
<para>If there are no problems your translation will be
committed as soon as possible.</para>
</answer>
</qandaentry>
@ -313,21 +336,22 @@
<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>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 is 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
to 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>There is 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 to 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>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>
@ -335,27 +359,29 @@
<qandaentry>
<question>
<para>How should language specific characters be included?</para>
<para>How should language specific characters be
included?</para>
</question>
<answer>
<para>Non-ASCII characters in the documentation should be included
using SGML entities.</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>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 role="package">textproc/iso8879</filename>.</para>
<para>The entity names are defined in ISO8879, which is in the
ports tree as <filename
role="package">textproc/iso8879</filename>.</para>
<para>A few examples include:</para>
<segmentedlist>
<segtitle>Entity</segtitle>
<segtitle>Entity</segtitle>
<segtitle>Appearance</segtitle>
<segtitle>Appearance</segtitle>
<segtitle>Description</segtitle>
<segtitle>Description</segtitle>
<seglistitem>
<seg>&amp;eacute;</seg>
@ -377,8 +403,8 @@
</segmentedlist>
<para>After you have installed the iso8879 port, the files in
<filename>/usr/local/share/sgml/iso8879</filename> contain the
complete list.</para>
<filename>/usr/local/share/sgml/iso8879</filename> contain
the complete list.</para>
</answer>
</qandaentry>
@ -389,12 +415,13 @@
<answer>
<para>In the English documents, the reader is addressed as
<quote>you</quote>, there is no formal/informal distinction as there
is in some languages.</para>
<quote>you</quote>, 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>
<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>
@ -407,8 +434,8 @@
<answer>
<para>Yes.</para>
<para>The header of the English version of each document will look
something like this:</para>
<para>The header of the English version of each document will
look something like this:</para>
<programlisting>&lt;!--
The FreeBSD Documentation Project
@ -416,12 +443,13 @@
&dollar;FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp &dollar;
--&gt;</programlisting>
<para>The exact boilerplate may change, but it will always include a
&dollar;FreeBSD&dollar; line and the phrase <literal>The FreeBSD Documentation
Project</literal>.
Note that the &dollar;FreeBSD part is expanded automatically by
CVS, so it should be empty (just
<literal>&dollar;FreeBSD&dollar;</literal>) for new files.</para>
<para>The exact boilerplate may change, but it will always
include a &dollar;FreeBSD&dollar; line and the phrase
<literal>The FreeBSD Documentation Project</literal>.
Note that the &dollar;FreeBSD part is expanded automatically
by CVS, so it should be empty (just
<literal>&dollar;FreeBSD&dollar;</literal>) for new
files.</para>
<para>Your translated documents should include their own
&dollar;FreeBSD&dollar; line, and change the
@ -429,9 +457,9 @@
<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>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>&lt;!--