documentation-guide/en_US l10n.xml, NONE, 1.1 documentation-guide.xml, 1.9, 1.10 rpm-info.xml, 1.13, 1.14
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Thu Apr 10 02:34:39 UTC 2008
Author: pfrields
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv22806/en_US
Modified Files:
documentation-guide.xml rpm-info.xml
Added Files:
l10n.xml
Log Message:
Add L10n chapter to DocGuide (#441190)
--- NEW FILE l10n.xml ---
<?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>
Index: documentation-guide.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/documentation-guide.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- documentation-guide.xml 3 Aug 2007 16:38:15 -0000 1.9
+++ documentation-guide.xml 10 Apr 2008 02:34:37 -0000 1.10
@@ -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" />
Index: rpm-info.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/rpm-info.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- rpm-info.xml 15 Dec 2007 21:51:46 -0000 1.13
+++ rpm-info.xml 10 Apr 2008 02:34:37 -0000 1.14
@@ -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>
More information about the docs-commits
mailing list