Translations of the PHP Manual
This exists to help determine our best route to manage translations. Since our move to SVN soon will already require us to alter every translated file (we can no longer depend on CVS Revision numbers), we may as well reconsider our current practice and go from there.
What we do now
Currently each translated file has a tag as such:
<!-- EN-Revision: 1.3 Maintainer: takagi Status: ready -->
That means this file is up-to-date and in sync with version 1.3 of the English file. The number 1.3 is the CVS $Revision$ of said English file.
We have tools to track when these our out of date, and this simplistic approach is how we manage translations today.
Why we must change
The move from CVS to SVN will change every revision number, so EN-Revision may be 456 instead of 1.3 now. And these numbers are not really sequential, so the next version of this EN file may be 987. This means all of our tools no longer work, and it's difficult to manage.
What we could do
Several routes exist.
- Simply use SVN numbers instead of CVS.
- Simply use SVN numbers instead of CVS, and move from comments to markup.
- Totally redo the system
In the above, moving from comments to markup means implementing a revision attribute into the DocBook itself. So, something like this:
<!-- EN-Revision: 456 Maintainer: takagi Status: ready --> <reference xml:id="reserved.variables" xmlns="http://docbook.org/ns/docbook">
<reference xml:id="reserved.variables" xmlns="http://docbook.org/ns/docbook" revision="456">
Whereas totally redoing the system would essentially change everything, namely, every translated file and how we manage them.
Many systems today use a gettext approach, so in this case the English version of the manual would remain the same (DocBook XML) but the translations would be managed using po files.
Projects that use this gettext approach:
- GNOME: http://l10n.gnome.org/
- GIMP: http://wiki.gimp.org/gimp/GimpDocsRoadmap (Roadmap for their current move to gettext)
When we should know
The SVN conversion will be completed sometime in the first quarter of 2009, let's say March 1. We should have our system essentially in place by that time. A sequential move is possible too (Start using SVN numbers, then later gettext) but that wouldn't be ideal. However, given the size of our manual, it may be required.
Status update: May 20, 2009
So far I've (philip) am having success converting translations to po files using po4a. After additional tweaking the plan is to setup pootle and see what happens. We may use transifex instead so we'll see but the key is getting the po files going. The main alternative to po4a is xml2po but so far I like po4a so don't see a need to investigate xml2po much further.
- po4a manual: http://po4a.alioth.debian.org/man/man7/po4a.7.php
- Command: po4a-gettextize -f docbook -m en/reference/strings/functions/strlen.xml -p strlen.po (creates a po file)
- Command: po4a-translate -f docbook -m en/reference/strings/functions/strlen.xml -p foo.po (creates docbook file)
- Command: po4a-gettextize -f docbook -m en/reference/strings/functions/strlen.xml -l ja/reference/strings/functions/strlen.xml -p foo.po (converts translation to po file)
So, the current plan:
- Convert current translations to po files (progressing)
- Setup pootle at translate.php.net