A Trivial Translation Example

Wed Dec 17 13:07:25 UTC 2014

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Am 17.12.14 um 00:13 schrieb 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. _______________________________________________ 
> freebsd-translators at freebsd.org mailing list 
> https://lists.freebsd.org/mailman/listinfo/freebsd-translators To
> unsubscribe, send any mail to 
> "freebsd-translators-unsubscribe at freebsd.org"

Here is the workflow I figured out for textproc/po4a. Note that some
of these instructions were originally provided by Thomas Abthorpe.

1. Install textproc/po4a and poedit

2., 3., and 4. are the same as above

3. Generate a POT file from po4a using this command:

$ po4a-gettextize --copyright-holder "The FreeBSD Documentation
Project"  -f xml -m
en_US.ISO8859-1/articles/translate-example/article.xml -p
translate-example.pot

4. Copy translate-example.pot to translate-example.po:
$ cp translate-example.pot translate-example.po

This way, you can make changes to translate-example.po and regenerate
translate-example.pot when needed without overwriting your translation
work thus far.

5. Follow 6. above

6. Edit translate-example.po using poedit (there are also other
editors in the ports collection you can use). Follow step 7. above.
Make sure not to translate entities like &os; (if any).

7. You can view your translation progress any time by saving your file
in poedit, then exiting the editor and issuing the following command:

po4a-translate -k 0 -w 70 -f xml -m
en_US.ISO8859-1/en_US.ISO8859-1/articles/translate-example/article.xml
- -p translate-example.po -l translated/result.xml

The important parameter is -k, which sets the translation threshold to
0. Without it, the threshold would be 80%, which means that no output
would be generated because that amount of the document hasn't been
translated yet.

The -w parameter should wrap the lines at that number of characters
(70 here), but it does not work. I just provided this for
completeness. This is a mayor problem, as you'll see in step 8.

So in general, use this command when you are completely finished
translating or have just parts of it.

8. View translated/result.xml. You will notice that the file is not
properly formatted anymore according to our documentation guidelines.
The file does build, though when copied to ../article.xml (create a
backup of it first).

9. You should now have a translated html version of the document.

The mayor problem with that approach is reapplying our style to the
resulting xml file. Because each time, when changes are made to the
translated document and the po4a-translate command is run, the
formatting is lost. It takes a lot of manual work to do this each
time, so a script that does this would be fantastic to have.

Here are some links that might help you with the above instructions:

- -
http://www.paolocorti.net/2012/01/05/managing_documentation_translations_with_open_source_tools/
- - https://wiki.mageia.org/en/Translation_with_Calenco_and_Gettext
- -
http://localization-guide.readthedocs.org/en/latest/guide/project/howto.html

Regards

Benedict Reuschling
Documentation Committer
The FreeBSD Project
The FreeBSD Documentation Project
-----BEGIN PGP SIGNATURE-----
Version: GnuPG/MacGPG2 v2.0.22 (Darwin)
Comment: GPGTools - https://gpgtools.org

iQEcBAEBCgAGBQJUkYAAAAoJEAQa31nbPD2LPbAH/RO8cGMy9TQF9tW32n4AI7zp
mPUbPqle44ZJergKVQ54SH6xebOOA+gLyaU1mnc3OdAJd7mHHXhqpOPWJqdz9+VE
WIwdYrsZc8VYcX1sV3CUG8f/whsqYR7Zaby92KwnpRjJWN3yXX0b7ReSKSVHV/9h
PmtqMjQbfrwS2My7PsBar+YVF8s9leYdUA/jg4/NQkWnd6OoFjK3t9+eKnh/DaMh
wULhp5aiVIqABRBgDh9/lMhCT70rNLZFcktzZTPtnDe1cScy2GMrW23Sj7N2enA0
X44KSWjX26QEGzGVVllH/Fwj/JNLq/zGvOo8LBwBQJNptf95b7WdfRYVuLtsfhc=
=NDvK
-----END PGP SIGNATURE-----