A Trivial Translation Example

[Warren Block]

A Trivial Translation Example

Here I show a bare-minimum example that can be used to get an idea of
the PO translation process.

1. Install textproc/docproj, textproc/itstool, and editors/poedit.

2. In a documentation tree checkout, create a new directory:
   mkdir -p en_US.ISO8859-1/articles/translate-example/translated
   cd en_US.ISO8859-1/articles/translate-example

3. Create a standard documentation Makefile:

#
# $FreeBSD$
#

DOC?= article

FORMATS?= html

INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=

SRCS=   article.xml

URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..

.include "${DOC_PREFIX}/share/mk/doc.project.mk"

4. Create a sample article.xml:

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $FreeBSD$ -->

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
   "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

<article xmlns="http://docbook.org/ns/docbook"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:lang="en">

   <info>
     <title>FreeBSD Translation Example</title>

     <authorgroup>
       <author>
         <personname>
 	  <firstname>Random</firstname>
 	  <surname>User</surname>
         </personname>
       </author>
     </authorgroup>
   </info>

   <sect1 xml:id="translation-example">
     <title>Translation Example Article</title>

     <para>This sample article is very short.  It exists to be used as
       an example for translation software.</para>

     <programlisting>01 This program listing contains only plain text.
02 It is only two lines long.</programlisting>

     <para>This is the conclusion of this short sample article.</para>
   </sect1>
</article>

5. Generate a .pot file from the article using itstool.  The strings are
extracted from article.xml into article.pot.  This overwrites the file,
and would normally only be used the first time a new translation is
created:
   echo env `make -VXSLTPROC_ENV` itstool -d -o article.pot article.xml | sh

6. Set a couple of values in the generated article.pot file to silence
warnings:
   on line 3, change "Project-Id-Version: PACKAGE VERSION\n"
     to "Project-Id-Version: 1\n"
   add a new line after it (this should be the actual language code, but I
   have just used "en"):
     "Language: en\n"
   on line 8, change "Language-Team: LANGUAGE <LL at li.org>\n"
     to "Language-Team: en\n"

7. Use poedit to enter translations:
   poedit article.pot
   Click on a line to translate and enter the translation below it.  When
   done, click the Save icon and close poedit.  Translated strings are
   stored in the article.pot file.

8. After leaving poedit, generate a translated version of the article:
   echo env `make -VXSLTPROC_ENV` \
   itstool -d -m article.mo -o translated article.xml | sh

The translated version of the article is written to
translated/article.xml.  The translated strings have replaced the
originals, and the article can be built with the documentation tools.