Add a new chapter that documents how PO translations are created and
maintained.
This commit is contained in:
Warren Block
parent
3062276fef
commit
9bc66bf912
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=47339
4 changed files with 763 additions and 0 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
|
|
|
|||
760
en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
Normal file
760
en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
Normal file
|
|
@ -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>
|
||||
Loading…
Reference in a new issue