aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml483
1 files changed, 0 insertions, 483 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
deleted file mode 100644
index 0c39f75d7b..0000000000
--- a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
+++ /dev/null
@@ -1,483 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- 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.
-
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml: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
- English by Bernd Warken <email>bwarken@mayn.de</email>.</para>
-
- <para>The FAQ is maintained by the &a.doceng;.</para>
-
- <qandaset>
- <qandaentry>
- <question>
- <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>
-
- <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>
-
- <qandaentry>
- <question>
- <para>Is there a mailing list for translators?</para>
- </question>
-
- <answer>
- <para>Yes. Different translation groups have their own
- mailing lists. The <link
- xlink:href="https://www.freebsd.org/docproj/translations.html">list
- of translation projects</link> has more information about
- the mailing lists and web sites run by each translation
- project. In addition there is
- <email>freebsd-translators@freebsd.org</email> for general
- translation discussion.</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 Subversion repository (at least the
- documentation part). This can be done by running:</para>
-
- <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen>
-
- <para><link
- xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link>
- is a public <literal>SVN</literal> server. Verify the
- server certificate from the list of <link
- xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
- mirror sites</link>.</para>
-
- <note>
- <para>This will require the
- <package>devel/subversion</package> package to be
- installed.</para>
- </note>
-
- <para>You should be comfortable using
- <application>svn</application>. This will allow you to see
- what has changed between different versions of the files
- that make up the documentation.</para>
-
- <para>For example, to view the differences between revisions
- <literal>r33733</literal> and <literal>r33734</literal> of
- <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>,
- run:</para>
-
- <screen>&prompt.user; <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen>
-
- <para>Please see the complete explanation of using
- <application>Subversion</application> in &os; in the <link
- xlink:href="&url.books.handbook;/svn.html">&os;
- Handbook</link>.</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 <link
- xlink:href="https://www.FreeBSD.org/docproj/translations.html">Documentation
- Project translations page</link> 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>
- </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
- <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>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>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <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>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>or</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>Currently, the FreeBSD documentation is stored in a top
- level directory called <filename>head/</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>head/
- sv_SE.ISO8859-1/
- Makefile
- htdocs/
- docproj/
- books/
- faq/
- Makefile
- book.xml</programlisting>
-
- <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>
-
- <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_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>Either way, you should use Bugzilla 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>
-
- <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_SE.ISO8859-1</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 work them out.</para>
-
- <para>If there are no problems 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 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
- Bugzilla) 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>
- </question>
-
- <answer>
- <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 <package>textproc/iso8879</package>.</para>
-
- <para>A few examples include:</para>
-
- <segmentedlist>
- <segtitle>Entity</segtitle>
-
- <segtitle>Appearance</segtitle>
-
- <segtitle>Description</segtitle>
-
- <seglistitem>
- <seg>&amp;eacute;</seg>
- <seg>&eacute;</seg>
- <seg>Small <quote>e</quote> with an acute accent</seg>
- </seglistitem>
-
- <seglistitem>
- <seg>&amp;Eacute;</seg>
- <seg>&Eacute;</seg>
- <seg>Large <quote>E</quote> with an acute accent</seg>
- </seglistitem>
-
- <seglistitem>
- <seg>&amp;uuml;</seg>
- <seg>&uuml;</seg>
- <seg>Small <quote>u</quote> with an umlaut</seg>
- </seglistitem>
- </segmentedlist>
-
- <para>After you have installed the iso8879 port, the files in
- <filename>/usr/local/share/xml/iso8879</filename> contain
- the complete list.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Addressing the reader</para>
- </question>
-
- <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>
-
- <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>&lt;!--
- The FreeBSD Documentation Project
-
- &dollar;FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z &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 Subversion, 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
- <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>&lt;!--
- The FreeBSD Spanish Documentation Project
-
- &dollar;FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs &dollar;
- Original revision: r38674
---&gt;</programlisting>
- </answer>
- </qandaentry>
- </qandaset>
-</chapter>