aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml921
1 files changed, 0 insertions, 921 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
deleted file mode 100644
index cc5681e7a5..0000000000
--- a/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
+++ /dev/null
@@ -1,921 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!--
- The FreeBSD Documentation Project
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="po-translations">
-
- <title><acronym>PO</acronym> Translations</title>
-
- <sect1 xml:id="po-translations-introduction">
- <title>Introduction</title>
-
- <para>The <link
- xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym>
- <application>gettext</application></link> system offers
- translators an easy way to create and maintain translations of
- documents. Translatable strings are extracted from the original
- document into a <acronym>PO</acronym> (Portable Object) file.
- Translated versions of the strings are entered with a separate
- editor. The strings can be used directly or built into a
- complete translated version of the original document.</para>
- </sect1>
-
- <sect1 xml:id="po-translations-quick-start">
- <title>Quick Start</title>
-
- <para>The procedure shown in
- <xref linkend="overview-quick-start"/> is assumed to have
- already been performed. The <literal>TRANSLATOR</literal>
- option is required and already enabled by default in the
- <package role="port">textproc/docproj</package> port.</para>
-
- <para>This example shows the creation of a Spanish translation of
- the short <link xlink:href="&url.articles.leap-seconds.en;">Leap
- Seconds</link> article.</para>
-
- <procedure xml:id="po-translations-quick-start-install-po-editor">
- <title>Install a <acronym>PO</acronym> Editor</title>
-
- <step>
- <para>A <acronym>PO</acronym> editor is needed to edit
- translation files. This example uses
- <package role="ports">editors/poedit</package>.</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/editors/poedit</userinput>
-&prompt.root; <userinput>make install clean</userinput></screen>
- </step>
- </procedure>
-
- <procedure xml:id="po-translations-quick-start-initial-setup">
- <title>Initial Setup</title>
-
- <para>When a new translation is first created, the directory
- structure and <filename>Makefile</filename> must be created or
- copied from the English original:</para>
-
- <step>
- <para>Create a directory for the new translation. The
- English article source is in
- <filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename>.
- The Spanish translation will go in
- <filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename>.
- The path is the same except for the name of the language
- directory.</para>
-
- <screen>&prompt.user; <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
- </step>
-
- <step>
- <para>Copy the <filename>Makefile</filename> from the original
- document into the translation directory:</para>
-
- <screen>&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
- ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen>
- </step>
- </procedure>
-
- <procedure xml:id="po-translations-quick-start-translation">
- <title>Translation</title>
-
- <para>Translating a document consists of two steps: extracting
- translatable strings from the original document, and entering
- translations for those strings. These steps are repeated
- until the translator feels that enough of the document has
- been translated to produce a usable translated
- document.</para>
-
- <step>
- <para>Extract the translatable strings from the original
- English version into a <acronym>PO</acronym> file:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
-&prompt.user; <userinput>make po</userinput></screen>
- </step>
-
- <step>
- <para>Use a <acronym>PO</acronym> editor to enter translations
- in the <acronym>PO</acronym> file. There are several
- different editors available. <filename>poedit</filename>
- from <package role="port">editors/poedit</package> is shown
- here.</para>
-
- <para>The <acronym>PO</acronym> file name is the
- two-character language code followed by an underline and a
- two-character region code. For Spanish, the file name is
- <filename>es_ES.po</filename>.</para>
-
- <screen>&prompt.user; <userinput>poedit es_ES.po</userinput></screen>
- </step>
- </procedure>
-
- <procedure
- xml:id="po-translations-quick-generating-a-translated-document">
- <title>Generating a Translated Document</title>
-
- <step>
- <para>Generate the translated document:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput>
-&prompt.user; <userinput>make tran</userinput></screen>
-
- <para>The name of the generated document matches the name
- of the English original, usually
- <filename>article.xml</filename> for articles or
- <filename>book.xml</filename> for books.</para>
- </step>
-
- <step>
- <para>Check the generated file by rendering it to
- <acronym>HTML</acronym> and viewing it with a
- web browser:</para>
-
- <screen>&prompt.user; <userinput>make FORMATS=html</userinput>
-&prompt.user; <userinput>firefox article.html</userinput></screen>
- </step>
- </procedure>
- </sect1>
-
- <sect1 xml:id="po-translations-creating">
- <title>Creating New Translations</title>
-
- <para>The first step to creating a new translated document is
- locating or creating a directory to hold it. &os; puts
- translated documents in a subdirectory named for their
- language and region in the format
- <filename><replaceable>lang</replaceable>_<replaceable>REGION</replaceable></filename>.
- <replaceable>lang</replaceable> is a two-character lowercase
- code. It is followed by an underscore character and then the
- two-character uppercase <replaceable>REGION</replaceable>
- code.</para>
-
- <table xml:id="po-translations-language-names" frame="none">
- <title>Language Names</title>
-
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Language</entry>
- <entry>Region</entry>
- <entry>Translated Directory Name</entry>
- <entry><acronym>PO</acronym> File Name</entry>
- <entry>Character Set</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>English</entry>
- <entry>United States</entry>
- <entry><filename>en_US.ISO8859-1</filename></entry>
- <entry><filename>en_US.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Bengali</entry>
- <entry>Bangladesh</entry>
- <entry><filename>bn_BD.UTF-8</filename></entry>
- <entry><filename>bn_BD.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry>Danish</entry>
- <entry>Denmark</entry>
- <entry><filename>da_DK.ISO8859-1</filename></entry>
- <entry><filename>da_DK.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>German</entry>
- <entry>Germany</entry>
- <entry><filename>de_DE.ISO8859-1</filename></entry>
- <entry><filename>de_DE.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Greek</entry>
- <entry>Greece</entry>
- <entry><filename>el_GR.ISO8859-7</filename></entry>
- <entry><filename>el_GR.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-7</entry>
- </row>
-
- <row>
- <entry>Spanish</entry>
- <entry>Spain</entry>
- <entry><filename>es_ES.ISO8859-1</filename></entry>
- <entry><filename>es_ES.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>French</entry>
- <entry>France</entry>
- <entry><filename>fr_FR.ISO8859-1</filename></entry>
- <entry><filename>fr_FR.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Hungarian</entry>
- <entry>Hungary</entry>
- <entry><filename>hu_HU.ISO8859-2</filename></entry>
- <entry><filename>hu_HU.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-2</entry>
- </row>
-
- <row>
- <entry>Italian</entry>
- <entry>Italy</entry>
- <entry><filename>it_IT.ISO8859-15</filename></entry>
- <entry><filename>it_IT.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-15</entry>
- </row>
-
- <row>
- <entry>Japanese</entry>
- <entry>Japan</entry>
- <entry><filename>ja_JP.eucJP</filename></entry>
- <entry><filename>ja_JP.po</filename></entry>
- <entry><acronym>EUC</acronym> JP</entry>
- </row>
-
- <row>
- <entry>Korean</entry>
- <entry>Korea</entry>
- <entry><filename>ko_KR.UTF-8</filename></entry>
- <entry><filename>ko_KR.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry>Mongolian</entry>
- <entry>Mongolia</entry>
- <entry><filename>mn_MN.UTF-8</filename></entry>
- <entry><filename>mn_MN.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry>Dutch</entry>
- <entry>Netherlands</entry>
- <entry><filename>nl_NL.ISO8859-1</filename></entry>
- <entry><filename>nl_NL.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Polish</entry>
- <entry>Poland</entry>
- <entry><filename>pl_PL.ISO8859-2</filename></entry>
- <entry><filename>pl_PL.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-2</entry>
- </row>
-
- <row>
- <entry>Portuguese</entry>
- <entry>Brazil</entry>
- <entry><filename>pt_BR.ISO8859-1</filename></entry>
- <entry><filename>pt_BR.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-1</entry>
- </row>
-
- <row>
- <entry>Russian</entry>
- <entry>Russia</entry>
- <entry><filename>ru_RU.KOI8-R</filename></entry>
- <entry><filename>ru_RU.po</filename></entry>
- <entry><acronym>KOI</acronym>8-R</entry>
- </row>
-
- <row>
- <entry>Turkish</entry>
- <entry>Turkey</entry>
- <entry><filename>tr_TR.ISO8859-9</filename></entry>
- <entry><filename>tr_TR.po</filename></entry>
- <entry><acronym>ISO</acronym> 8859-9</entry>
- </row>
-
- <row>
- <entry>Chinese</entry>
- <entry>China</entry>
- <entry><filename>zh_CN.UTF-8</filename></entry>
- <entry><filename>zh_CN.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
-
- <row>
- <entry>Chinese</entry>
- <entry>Taiwan</entry>
- <entry><filename>zh_TW.UTF-8</filename></entry>
- <entry><filename>zh_TW.po</filename></entry>
- <entry><acronym>UTF</acronym>-8</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The translations are in subdirectories of the main
- documentation directory, here assumed to be
- <filename>~/doc/</filename> as shown in
- <xref linkend="overview-quick-start"/>. For example, German
- translations are located in
- <filename>~/doc/de_DE.ISO8859-1/</filename>, and French
- translations are in
- <filename>~/doc/fr_FR.ISO8859-1/</filename>.</para>
-
- <para>Each language directory contains separate subdirectories
- named for the type of documents, usually
- <filename>articles/</filename> and
- <filename>books/</filename>.</para>
-
- <para>Combining these directory names gives the complete path to
- an article or book. For example, the French translation of the
- NanoBSD article is in
- <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename>,
- and the Mongolian translation of the Handbook is in
- <filename>~/doc/mn_MN.UTF-8/books/handbook/</filename>.</para>
-
- <para>A new language directory must be created when translating
- a document to a new language. If the language directory already
- exists, only a subdirectory in the
- <filename>articles/</filename> or <filename>books/</filename>
- directory is needed.</para>
-
- <para>&os; documentation builds are controlled by a
- <filename>Makefile</filename> in the same directory. With
- simple articles, the <filename>Makefile</filename> can often
- just be copied verbatim from the original English directory.
- The translation process combines multiple separate
- <filename>book.xml</filename> and
- <filename>chapter.xml</filename> files in books into a single
- file, so the <filename>Makefile</filename> for book translations
- must be copied and modified.</para>
-
- <example xml:id="po-translations-creating-example">
- <title>Creating a Spanish Translation of the Porter's
- Handbook</title>
-
- <para>Create a new Spanish translation of the
- <link xlink:href="&url.books.porters-handbook.en;">Porter's
- Handbook</link>. The original is a book in
- <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename>.</para>
-
- <procedure>
- <step>
- <para>The Spanish language books directory
- <filename>~/doc/es_ES.ISO8859-1/books/</filename> already
- exists, so only a new subdirectory for the Porter's
- Handbook is needed:</para>
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput>
-&prompt.user; <userinput>svn mkdir porters-handbook</userinput>
-A porters-handbook</screen>
- </step>
-
- <step>
- <para>Copy the <filename>Makefile</filename> from the
- original book:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput>
-A Makefile</screen>
-
- <para>Modify the contents of the
- <filename>Makefile</filename> to only expect a single
- <filename>book.xml</filename>:</para>
-
- <programlisting>#
-# &dollar;FreeBSD&dollar;
-#
-# Build the FreeBSD Porter's Handbook.
-#
-
-MAINTAINER=doc@FreeBSD.org
-
-DOC?= book
-
-FORMATS?= html-split
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-# XML content
-SRCS= book.xml
-
-# Images from the cross-document image library
-IMAGES_LIB+= callouts/1.png
-IMAGES_LIB+= callouts/2.png
-IMAGES_LIB+= callouts/3.png
-IMAGES_LIB+= callouts/4.png
-IMAGES_LIB+= callouts/5.png
-IMAGES_LIB+= callouts/6.png
-IMAGES_LIB+= callouts/7.png
-IMAGES_LIB+= callouts/8.png
-IMAGES_LIB+= callouts/9.png
-IMAGES_LIB+= callouts/10.png
-IMAGES_LIB+= callouts/11.png
-IMAGES_LIB+= callouts/12.png
-IMAGES_LIB+= callouts/13.png
-IMAGES_LIB+= callouts/14.png
-IMAGES_LIB+= callouts/15.png
-IMAGES_LIB+= callouts/16.png
-IMAGES_LIB+= callouts/17.png
-IMAGES_LIB+= callouts/18.png
-IMAGES_LIB+= callouts/19.png
-IMAGES_LIB+= callouts/20.png
-IMAGES_LIB+= callouts/21.png
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
-
- <para>Now the document structure is ready for the translator
- to begin translating with
- <command>make po</command>.</para>
- </step>
- </procedure>
- </example>
-
- <example xml:id="po-translations-creating-example-french">
- <title>Creating a French Translation of the
- <acronym>PGP</acronym> Keys Article</title>
-
- <para>Create a new French translation of the
- <link
- xlink:href="&url.articles.pgpkeys;"><acronym>PGP</acronym>
- Keys article</link>. The original is an article in
- <filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename>.</para>
-
- <procedure>
- <step>
- <para>The French language article directory
- <filename>~/doc/fr_FR.ISO8859-1/articles/</filename>
- already exists, so only a new subdirectory for the
- <acronym>PGP</acronym> Keys article is needed:</para>
- <screen>&prompt.user; <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput>
-&prompt.user; <userinput>svn mkdir pgpkeys</userinput>
-A pgpkeys</screen>
- </step>
-
- <step>
- <para>Copy the <filename>Makefile</filename> from the
- original article:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput>
-&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput>
-A Makefile</screen>
-
- <para>Check the contents of the
- <filename>Makefile</filename>. As this is a simple
- article, in this case the <filename>Makefile</filename>
- can be used unchanged. The <literal>$&os;...$</literal>
- version string on the second line will be replaced by the
- version control system when this file is committed.</para>
-
- <programlisting>#
-# &dollar;FreeBSD&dollar;
-#
-# Article: PGP Keys
-
-DOC?= article
-
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= article.xml
-
-# To build with just key fingerprints, set FINGERPRINTS_ONLY.
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
-
- <para>With the document structure complete, the
- <acronym>PO</acronym> file can be created with
- <command>make po</command>.</para>
- </step>
- </procedure>
- </example>
- </sect1>
-
- <sect1 xml:id="po-translations-translating">
- <title>Translating</title>
-
- <para>The <application>gettext</application> system greatly
- reduces the number of things that must be tracked by a
- translator. Strings to be translated are extracted from the
- original document into a <acronym>PO</acronym> file. Then a
- <acronym>PO</acronym> editor is used to enter the translated
- versions of each string.</para>
-
- <para>The &os; <acronym>PO</acronym> translation system does not
- overwrite <acronym>PO</acronym> files, so the extraction step
- can be run at any time to update the <acronym>PO</acronym>
- file.</para>
-
- <para>A <acronym>PO</acronym> editor is used to edit the file.
- <package role="port">editors/poedit</package> is shown in
- these examples because it is simple and has minimal
- requirements. Other <acronym>PO</acronym> editors offer
- features to make the job of translating easier. The Ports
- Collection offers several of these editors, including
- <package role="port">devel/gtranslator</package>.</para>
-
- <para>It is important to preserve the <acronym>PO</acronym> file.
- It contains all of the work that translators have done.</para>
-
- <example xml:id="po-translations-translating-example">
- <title>Translating the Porter's Handbook to Spanish</title>
-
- <para>Enter Spanish translations of the contents of the Porter's
- Handbook.</para>
-
- <procedure>
- <step>
- <para>Change to the Spanish Porter's Handbook directory and
- update the <acronym>PO</acronym> file. The generated
- <acronym>PO</acronym> file is called
- <filename>es_ES.po</filename> as shown in
- <xref linkend="po-translations-language-names"/>.</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-&prompt.user; <userinput>make po</userinput></screen>
- </step>
-
- <step>
- <para>Enter translations using a <acronym>PO</acronym>
- editor:</para>
-
- <screen>&prompt.user; <userinput>poedit es_ES.po</userinput></screen>
- </step>
- </procedure>
- </example>
- </sect1>
-
- <sect1 xml:id="po-translations-tips">
- <title>Tips for Translators</title>
-
- <sect2 xml:id="po-translations-tips-xmltags">
- <title>Preserving <acronym>XML</acronym> Tags</title>
-
- <para>Preserve <acronym>XML</acronym> tags that are shown in
- the English original.</para>
-
- <example>
- <title>Preserving <acronym>XML</acronym> Tags</title>
-
- <para>English original:</para>
-
- <programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting>
-
- <para>Spanish translation:</para>
-
- <programlisting>Si <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> no se utiliza</programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-spaces">
- <title>Preserving Spaces</title>
-
- <para>Preserve existing spaces at the beginning and end of
- strings to be translated. The translated version must have
- these spaces also.</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-verbatim">
- <title>Verbatim Tags</title>
-
- <para>The contents of some tags should be copied verbatim, not
- translated:</para>
-
- <itemizedlist xml:id="po-translations-tips-verbatim-list">
- <listitem>
- <para><tag class="starttag">citerefentry</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">command</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">filename</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">literal</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">manvolnum</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">orgname</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">package</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">programlisting</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">prompt</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">refentrytitle</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">screen</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">userinput</tag></para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">varname</tag></para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 xml:id="po-translations-literal-dollar">
- <title><literal>&dollar;FreeBSD&dollar;</literal>
- Strings</title>
-
- <para>The &dollar;FreeBSD&dollar; version strings used in
- files require special handling. In examples like
- <xref linkend="po-translations-creating-example"/>, these
- strings are not meant to be expanded. The English documents
- use <literal>&amp;dollar;</literal> entities to avoid
- including actual literal dollar signs in the file:</para>
-
- <programlisting>&amp;dollar;FreeBSD&amp;dollar;</programlisting>
-
- <para>The <literal>&amp;dollar;</literal> entities are not seen
- as dollar signs by the version control system and so the
- string is not expanded into a version string.</para>
-
- <para>When a <acronym>PO</acronym> file is created, the
- <literal>&amp;dollar;</literal> entities used in examples are
- replaced with actual dollar signs. The resulting literal
- <literal>&dollar;FreeBSD&dollar;</literal> string will be
- wrongly expanded by the version control system when the file
- is committed.</para>
-
- <para>The same technique as used in the English documents can be
- used in the translation. The <literal>&amp;dollar;</literal>
- is used to replace the dollar sign in the translation entered
- into the <acronym>PO</acronym> editor:</para>
-
- <programlisting>&amp;dollar;FreeBSD&amp;dollar;</programlisting>
- </sect2>
-
- <!--
- <sect2 xml:id="po-translations-tips-makefile">
- <title>Modifying the <filename>Makefile</filename></title>
-
- <para>What needs to be changed in the
- <filename>Makefile</filename>?</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-locale">
- <title>Setting Locales for Editing</title>
-
- <para>Locale settings so the <acronym>PO</acronym> editor works
- correctly?</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-poeditors">
- <title>Settings for Specific <acronym>PO</acronym>
- Editors</title>
-
- <para>Per bcr: turn off "intelligent quotes" in
- Mac poedit.</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-tm">
- <title>Using Translation Memory</title>
-
- <para>Using translation memory. Saving, updating, sharing
- with other members of a translation team.</para>
- </sect2>
-
- <sect2 xml:id="po-translations-tips-submitting">
- <title>Submitting Translations</title>
-
- <para>Submitting translations as diffs, committing
- <acronym>PO</acronym> files.</para>
- </sect2>
- -->
- </sect1>
-
- <sect1 xml:id="po-translations-building">
- <title>Building a Translated Document</title>
-
- <para>A translated version of the original document can be created
- at any time. Any untranslated portions of the original will be
- included in English in the resulting document. Most
- <acronym>PO</acronym> editors have an indicator that shows how
- much of the translation has been completed. This makes it easy
- for the translator to see when enough strings have been
- translated to make building the final document
- worthwhile.</para>
-
- <example xml:id="po-translations-building-example">
- <title>Building the Spanish Porter's Handbook</title>
-
- <para>Build and preview the Spanish version of the Porter's
- Handbook that was created in an earlier example.</para>
-
- <procedure>
- <step>
- <para>Build the translated document. As the original
- is a book, the generated document is
- <filename>book.xml</filename>.</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput>
-&prompt.user; <userinput>make tran</userinput></screen>
- </step>
-
- <step>
- <para>Render the translated <filename>book.xml</filename> to
- <acronym>HTML</acronym> and view it with
- <application>Firefox</application>. This is the
- same procedure used with the English version of the
- documents, and other <varname>FORMATS</varname> can
- be used here in the same way. See <xref
- linkend="doc-build-rendering-common-formats"/>.</para>
-
- <screen>&prompt.user; <userinput>make FORMATS=html</userinput>
-&prompt.user; <userinput>firefox book.html</userinput></screen>
- </step>
- </procedure>
- </example>
- </sect1>
-
- <sect1 xml:id="po-translations-submitting">
- <title>Submitting the New Translation</title>
-
- <para>Prepare the new translation files for submission. This
- includes adding the files to the version control system, setting
- additional properties on them, then creating a diff for
- submission.</para>
-
- <para>The diff files created by these examples can be attached to
- a <link
- xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation">documentation
- bug report</link> or <link
- xlink:href="https://reviews.freebsd.org/">code
- review</link>.</para>
-
- <example xml:id="po-translations-submitting-spanish">
- <title>Spanish Translation of the NanoBSD Article</title>
-
- <procedure>
- <step>
- <para>Add a &os; version string comment as the first
- line of the <acronym>PO</acronym> file:</para>
-
- <programlisting>#&dollar;FreeBSD&dollar;</programlisting>
- </step>
-
- <step>
- <para>Add the <filename>Makefile</filename>, the
- <acronym>PO</acronym> file, and the generated
- <acronym>XML</acronym> translation to
- version control:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput>
-&prompt.user; <userinput>ls</userinput>
-Makefile article.xml es_ES.po
-&prompt.user; <userinput>svn add Makefile article.xml es_ES.po</userinput>
-A Makefile
-A article.xml
-A es_ES.po</screen>
- </step>
-
- <step>
- <para>Set the
- <application>Subversion</application>
- <literal>svn:keywords</literal> properties on these files
- to <literal>FreeBSD=%H</literal> so
- <literal>&dollar;FreeBSD&dollar;</literal> strings are
- expanded into the path, revision, date, and author when
- committed:</para>
-
- <screen>&prompt.user; <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput>
-property 'svn:keywords' set on 'Makefile'
-property 'svn:keywords' set on 'article.xml'
-property 'svn:keywords' set on 'es_ES.po'</screen>
- </step>
-
- <step>
- <para>Set the <acronym>MIME</acronym> types of the files.
- These are <literal>text/xml</literal> for books and
- articles, and
- <literal>text/x-gettext-translation</literal> for the
- <acronym>PO</acronym> file.</para>
-
- <screen>&prompt.user; <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput>
-property 'svn:mime-type' set on 'es_ES.po'
-&prompt.user; <userinput>svn propset svn:mime-type text/xml article.xml</userinput>
-property 'svn:mime-type' set on 'article.xml'</screen>
- </step>
-
- <step>
- <para>Create a diff of the new files from the
- <filename>~/doc/</filename> base directory so the full
- path is shown with the filenames. This helps committers
- identify the target language directory.</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc</userinput>
-<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff</userinput></screen>
- </step>
- </procedure>
- </example>
-
- <example xml:id="po-translations-submitting-korean-utf8">
- <title>Korean <acronym>UTF-8</acronym> Translation of the
- Explaining-BSD Article</title>
-
- <procedure>
- <step>
- <para>Add a &os; version string comment as the first
- line of the <acronym>PO</acronym> file:</para>
-
- <programlisting>#&dollar;FreeBSD&dollar;</programlisting>
- </step>
-
- <step>
- <para>Add the <filename>Makefile</filename>, the
- <acronym>PO</acronym> file, and the generated
- <acronym>XML</acronym> translation to
- version control:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput>
-&prompt.user; <userinput>ls</userinput>
-Makefile article.xml ko_KR.po
-&prompt.user; <userinput>svn add Makefile article.xml ko_KR.po</userinput>
-A Makefile
-A article.xml
-A ko_KR.po</screen>
- </step>
-
- <step>
- <para>Set the <application>Subversion</application>
- <literal>svn:keywords</literal> properties on these files
- to <literal>FreeBSD=%H</literal> so
- <literal>&dollar;FreeBSD&dollar;</literal> strings are
- expanded into the path, revision, date, and author when
- committed:</para>
-
- <screen>&prompt.user; <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po</userinput>
-property 'svn:keywords' set on 'Makefile'
-property 'svn:keywords' set on 'article.xml'
-property 'svn:keywords' set on 'ko_KR.po'</screen>
- </step>
-
- <step>
- <para>Set the <acronym>MIME</acronym> types of the files.
- These files use the <acronym>UTF-8</acronym>
- character set, so that is also specified. To prevent the
- version control system from mistaking these files for
- binary data, the <literal>fbsd:notbinary</literal>
- property is also set:</para>
-
- <screen>&prompt.user; <userinput>svn propset svn:mime-type 'text/x-gettext-translation; charset=UTF-8' ko_KR.po</userinput>
-property 'svn:mime-type' set on 'ko_KR.po'
-&prompt.user; <userinput>svn propset fbsd:notbinary yes ko_KR.po</userinput>
-property 'fbsd:notbinary' set on 'ko_KR.po'
-&prompt.user; <userinput>svn propset svn:mime-type 'text/xml; charset=UTF-8' article.xml</userinput>
-property 'svn:mime-type' set on 'article.xml'
-&prompt.user; <userinput>svn propset fbsd:notbinary yes article.xml</userinput>
-property 'fbsd:notbinary' set on 'article.xml'</screen>
- </step>
-
- <step>
- <para>Create a diff of these new files from the
- <filename>~/doc/</filename> base directory:</para>
-
- <screen>&prompt.user; <userinput>cd ~/doc</userinput>
-<userinput>svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff</userinput></screen>
- </step>
- </procedure>
- </example>
- </sect1>
-</chapter>