aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
diff options
context:
space:
mode:
authorSergio Carlavilla Delgado <carlavilla@FreeBSD.org>2021-01-25 23:31:29 +0000
committerSergio Carlavilla Delgado <carlavilla@FreeBSD.org>2021-01-25 23:31:29 +0000
commit989d921f5d4ac8d8b7c831c13b8954ad1901be24 (patch)
treea5d768f9af4b55422fdf5b17064879ae1c7ce032 /en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
parent0cff342f42461c5081b98bce7581f43df319e4f4 (diff)
downloaddoc-989d921f5d4ac8d8b7c831c13b8954ad1901be24.tar.gz
doc-989d921f5d4ac8d8b7c831c13b8954ad1901be24.zip
Migrate doc to Hugo/AsciiDoctor
I'm very pleased to announce the release of our new website and documentation using the new toolchain with Hugo and AsciiDoctor. To get more information about the new toolchain please read the FreeBSD Documentation Project Primer[1], Hugo docs[2] and AsciiDoctor docs[3]. Acknowledgment: Benedict Reuschling <bcr@> Glen Barber <gjb@> Hiroki Sato <hrs@> Li-Wen Hsu <lwhsu@> Sean Chittenden <seanc@> The FreeBSD Foundation [1] https://docs.FreeBSD.org/en/books/fdp-primer/ [2] https://gohugo.io/documentation/ [3] https://docs.asciidoctor.org/home/ Approved by: doceng, core
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>