Add a new chapter that documents how PO translations are created and

maintained.

4 files changed, 763 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile
index a1be3e53f1..e61cbd6a68 100644
--- a/en_US.ISO8859-1/books/fdp-primer/Makefile
+++ b/en_US.ISO8859-1/books/fdp-primer/Makefile
@@ -31,6 +31,7 @@ SRCS+= xhtml-markup/chapter.xml
 SRCS+= docbook-markup/chapter.xml
 SRCS+= stylesheets/chapter.xml
 SRCS+= translations/chapter.xml
+SRCS+= po-translations/chapter.xml
 SRCS+= writing-style/chapter.xml
 SRCS+= editor-config/chapter.xml
 SRCS+= see-also/chapter.xml
diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml
index d2f55c69b5..21d50e7157 100644
--- a/en_US.ISO8859-1/books/fdp-primer/book.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/book.xml
@@ -258,6 +258,7 @@ The time is 09:18</screen></entry>
   &chap.docbook-markup;
   &chap.stylesheets;
   &chap.translations;
+  &chap.po-translations;
   &chap.writing-style;
   &chap.editor-config;
   &chap.see-also;
diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
index 81278d507e..55c9cdcf53 100644
--- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent
+++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
@@ -21,6 +21,7 @@
 <!ENTITY chap.docbook-markup    SYSTEM "docbook-markup/chapter.xml">
 <!ENTITY chap.stylesheets	SYSTEM "stylesheets/chapter.xml">
 <!ENTITY chap.translations	SYSTEM "translations/chapter.xml">
+<!ENTITY chap.po-translations	SYSTEM "po-translations/chapter.xml">
 <!ENTITY chap.writing-style	SYSTEM "writing-style/chapter.xml">
 <!ENTITY chap.editor-config	SYSTEM "editor-config/chapter.xml">
 <!ENTITY chap.see-also		SYSTEM "see-also/chapter.xml">
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
new file mode 100644
index 0000000000..6e779167e1
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
@@ -0,0 +1,760 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!--
+    The FreeBSD Documentation Project
+    $FreeBSD$
+-->
+<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, but the <literal>TRANSLATOR</literal>
+      option must be enabled in the
+      <package role="port">textproc/docproj</package> port.  If that
+      option was not enabled, display the options menu and enable
+      it:</para>
+
+      <screen>&prompt.root; <userinput>make -C /usr/ports/textproc/docproj config</userinput></screen>
+
+      <para>Then reinstall 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 and 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>Norwegian</entry>
+	    <entry>Norway</entry>
+	    <entry><filename>no_NO.ISO8859-1</filename></entry>
+	    <entry><filename>no_NO.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>Serbian</entry>
+	    <entry>Serbia</entry>
+	    <entry><filename>sr_YU.ISO8859-2</filename></entry>
+	    <entry><filename>sr_YU.po</filename></entry>
+	    <entry><acronym>ISO</acronym> 8859-2</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>#
+# $FreeBSD$
+#
+# 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}/../../..
+
+SYMLINKS=       ${DESTDIR} index.html handbook.html
+
+.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>.  Because this is a simple
+	    article, in this case the <filename>Makefile</filename>
+	    can be used unchanged.  The <literal>$&os;...$</literal>
+	    version string on the third line will be replaced by the
+	    version control system when this file is committed.</para>
+
+	  <programlisting>#
+# $FreeBSD$
+#
+# 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>
+	<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-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.  Because 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>
+</chapter>