HOWTO translate Gentoo Documentation

Recently, I am involved in Gentoo Guide translation. This is more or less like a new domain for me since I’ve never worked in localization. It is quite amazing to see how different pieces integrated to make our lives much easier. This HOWTO is merely the summary of this documentation, left here for personal record.

Head over to the source

You can use gitto sync the repository, or download it from online CVS repository. In fact, there is a simpler way to do so referred to Gentoo XML Guide: just add ?passthru=1 to the targeted GuideXML. For example, I am translating the Gentoo Linux ALSA Guide, fetch the original xml via: wget http://www.gentoo.org/doc/en/alsa-guide.xml?passthru=1 -O alsa-guide.xml.

However, we need the other pieces like xsl, css, dtd, so we may need checkout all of them from the repository:

cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml/htdocs/dtd
cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml/htdocs/css
cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml/htdocs/xsl
cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml/htdocs/doc/en/alsa-guide.xml

Using po to translate

pois the standard for translation. We are using po4a as suggested. First, let’s move to the right path, i.e $ROOT/gentoo/xml/htdocs/doc, and the translated xml is going to stored in doc/zh_CN.

# generate the po from the original xml
po4a-gettextize -f guide -m en/alsa-guide.xml > zh_CN/alsa-guide.po

emacs has built-in supports for po mode. I am using vim, and found the po.vim plugin is quite neat as well.

Check before commit

po or GuideXML are designed for machines, not for human being. It is much easier for eyes to catch the errors when reading rendered HTML.

# generate the translated xml using po
po4a-translate -f guide -m en/alsa-guide.xml -p zh_CN/alsa-guide.po -k 1 > zh_CN/alsa-guide.xml

# check the output using xslt
xsltproc --path ../xsl:en ../xsl/guide.xsl zh_CN/alsa-guide.xml > zh_CN/alsa-guide.html

Before your checkin, ensure you have read through Translators Howto for Gentoo Documentation.

Happy localizing.