Add L10n chapter to DocGuide (#441190)

3 files changed, 174 insertions, 5 deletions

diff --git a/en_US/documentation-guide.xml b/en_US/documentation-guide.xml
index e2472aa..6c63948 100644
--- a/en_US/documentation-guide.xml
+++ b/en_US/documentation-guide.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- $Id: documentation-guide.xml,v 1.9 2007/08/03 16:38:15 pfrields Exp $ -->
+<!-- $Id: documentation-guide.xml,v 1.10 2008/04/10 02:34:37 pfrields Exp $ -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
@@ -7,10 +7,6 @@
 <!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
 %FEDORA-ENTITIES-EN;
 
-<!ENTITY VERSION "0.2.6.3"> <!-- version for this document -->
-
-<!ENTITY DOCID "documentation-guide-&VERSION; (2005-09-18)"> <!-- change date here and VERSION entity everytime a change is made-->
-
 ]>
 
 <book id="documentation-guide" lang="en_US">
@@ -67,6 +63,10 @@
   <xi:include href="cvs-en_US.xml" xml:base="&FDPCOMMONDIR;/common"
     xpointer="element(ch-cvs)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
+  <!-- L10N -->
+  <xi:include href="l10n.xml"
+	      xmlns:xi="http://www.w3.org/2001/XInclude" />
+
   <!-- ACKNOWLEDGMENTS --> 
   <xi:include href="acknowledgments.xml" xpointer="element(acknowledgments)"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/en_US/l10n.xml b/en_US/l10n.xml
new file mode 100644
index 0000000..98aee7d
--- /dev/null
+++ b/en_US/l10n.xml
@@ -0,0 +1,164 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Id: -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- *************** Bring in Fedora entities *************** -->
+<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
+%FEDORA-ENTITIES-EN;
+
+]>
+
+<chapter id="ch-l10n">
+  <title>Localization (L10n)</title>
+  <para>
+    This chapter discusses how translations are provided in &DISTRO;
+    documentation.
+  </para>
+  <section id="sn-l10n-po-files">
+    <title>PO Files</title>
+    <para>
+      The cornerstone of translation when using XML files such as
+      DocBook is the <firstterm>Portable Object</firstterm> or
+      <acronym>PO</acronym> file.  PO files provide a way for
+      independent individuals or teams to translate documents.  The
+      &FDP; toolchain includes rules for creating, updating, and
+      maintaining these PO files.
+    </para>
+    <para>
+      PO files are usually found in two forms:
+    </para>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  the <filename class="extension">.pot</filename> file, or
+	  <firstterm>PO Template</firstterm> (<acronym>POT</acronym>)
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  the <filename class="extension">.po</filename> file, or
+	  translation file (<acronym>PO</acronym>)
+	</para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      A POT is, as the name suggests, a blank template for new
+      translations.  It contains some header information and a list of
+      strings based on the content of the original XML file from which
+      it was created.  Translators do not alter the POT.  The POT
+      should only be changed after changes are made to the original
+      XML file from which it is derived.
+    </para>
+    <para>
+      A translator who wishes to start working on a new language
+      copies the POT to a locale-specific PO file.  Then the
+      translator uses any of a number of command-line or graphical
+      tools to translate each of the strings in the list.  A single
+      POT is used to create many POs, one for each locale.  These
+      files are normally named for their locale code, such as
+      <filename>de.po</filename>, <filename>it.po</filename>, and so
+      on.
+    </para>
+  </section>
+  <section id="sn-l10n-make-pot">
+    <title>Creating or Updating a POT</title>
+    <para>
+      The POT is named after the document from which it is derived.
+      If document named in the <filename>Makefile</filename>) is
+      <filename>foo-tutorial.xml</filename>, the POT is named
+      <filename>foo-tutorial.pot</filename>.
+    </para>
+    <para>
+      To create a new POT, use the following command:
+    </para>
+    <screen><![CDATA[make pot]]></screen>
+    <para>
+      The same command is used to update the POT when the original XML
+      sources change.
+    </para>
+    <important>
+      <title>Keep POT Fresh</title>
+      <para>
+	Update the POT whenever the original XML changes.  Many
+	translators' tools automatically notify them of the change so
+	they can update translations quickly.
+      </para>
+    </important>
+  </section>
+  <section id="sn-l10n-make-po">
+    <title>Updating PO Files</title>
+    <para>
+      The translation files are created by the individual translators,
+      and document maintainers do not normally need to create them.
+      Translators update a list of locales in the
+      <filename>po/LINGUAS</filename> file which defines all the
+      locales for which translations exist.
+    </para>
+    <para>
+      Whenever the source XML files are updated, the maintainer must
+      at least update the POT.  It is helpful, however, to also merge
+      these changes with the existing translations for those
+      translators who are not automatically notified of changes.
+    </para>
+    <important>
+      <title>Staying Current</title>
+      <para>
+	Always make sure your local copy of PO is fresh, using the CVS
+	"update" command:
+      </para>
+      <screen><![CDATA[cvs up]]></screen>
+    </important>
+    <para>
+      To merge new changes into the existing PO translations, use the
+      following command:
+    </para>
+    <screen><![CDATA[make po]]></screen>
+  </section>
+  <section id="sn-l10n-postat">
+    <title>Checking Statistics</title>
+    <para>
+      PO strings fall into three categories:
+    </para>
+    <orderedlist>
+      <listitem>
+	<para>
+	  <firstterm>translated</firstterm>, meaning the string has
+	  been handled by a translator and its source has not changed
+	  since then
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <firstterm>fuzzy</firstterm>, meaning the string has changed
+	  since it was last handled by a translator
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <firstterm>untranslated</firstterm>, meaning no translation
+	  has yet been provided for this string, or it is brand new
+	</para>
+      </listitem>
+    </orderedlist>
+    <para>
+      To see a rough statistical tally of the string handling inside
+      the PO for a module, use the following command:
+    </para>
+    <screen><![CDATA[make postat]]></screen>
+    <para>
+      For each locale in the list, a count is shown of translated,
+      fuzzy, and untranslated strings in that order.  Tallies that
+      only provide two numerals are usually translated followed by
+      untranslated.  Tallies with only one numeral are usually fully
+      translated.
+    </para>
+    <para>
+      To see only a specific locale, append a dash and the locale code
+      to the <command>postat</command> target:
+    </para>
+    <screen><![CDATA[make postat-de]]></screen>
+  </section>
+</chapter>
diff --git a/en_US/rpm-info.xml b/en_US/rpm-info.xml
index a0aad61..221a806 100644
--- a/en_US/rpm-info.xml
+++ b/en_US/rpm-info.xml
@@ -28,11 +28,16 @@
     <year>2005</year>
     <year>2006</year>
     <year>2007</year>
+    <year>2008</year>
     <holder>Red Hat, Inc. and others</holder>
   </copyright>
   <title>Fedora Documentation Guide</title>
   <desc>Guidelines and procedures for producing documentation for Fedora</desc>
   <changelog order="newest-first">
+    <revision date="2008-04-09" number="0.4">
+      <author worker="PaulWFrields"/>
+      <details>Add L10n chapter (#441190)</details>
+    </revision>
     <revision date="2007-12-15" number="0.3.3">
       <author worker="PaulWFrields"/>
       <details>Fix some organization and missing targets (#371531)</details>