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 git to 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:[email protected]/var/cvsroot co gentoo/xml/htdocs/dtd
cvs -d :pserver:[email protected]/var/cvsroot co gentoo/xml/htdocs/css
cvs -d :pserver:[email protected]/var/cvsroot co gentoo/xml/htdocs/xsl
cvs -d :pserver:[email protected]/var/cvsroot co gentoo/xml/htdocs/doc/en/alsa-guide.xml

Using po to translate

po is 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 commit, ensure you have read through Translators Howto for Gentoo Documentation.

Happy localizing.