Separate from the tremendous amount of feedback from the community I quickly want to outline the pydotorg setup for later reuse.
We have the most recent versions of Sphinx (with Native Language Support), Pootle and Translate Toolkit running from checkout on our servers and a current checkout of the Sphinx project source in question. There is a directory for
.pot files (message templates) built by Sphinx and one for
.mo files (compiled catalogs) built from Pootle’s
.po files (message catalogs). One last directory is used for translated HTML builds.
Attention: Apache should drop into the same system user as the one maintaining these files. This saves you a lot of hassle messing around with shared files, groups rights, yadda yadda.
Note: I will use Unix environment variable syntax for locations, feel free to statically insert your preferences there (we do).
Sphinx has to build message catalogs from a
$SRC directory into Pootle’s
PODIRECTORY set in
localsettings.py. For our deployment,
$PROJECT is always
sphinx-build -b gettext $SRC $PODIRECTORY/$PROJECT/templates
Pootle creates its translations in
$PODIRECTORY/$PROJECT/$LANGUAGE but currently Sphinx only reads compiled message catalogs.
for file in $PODIRECTORY/$PROJECT/$LANGUAGE/*.po; do mofile="$MODIRECTORY/$LANGUAGE/LC_MESSAGES/$(basename $file | sed s/po$/mo/)" rm -f $mofile # msgfmt will do merging otherwise msgfmt "$file" -o "$mofile" done
Sphinx can now pick the translations up from
$MODIRECTORY by adding it to
locale_dirs from your
conf.py. The code snippet above only works for one (or non-overlapping) projects but is easily extended to multiple targets. (Warning:
locale_dirs can not be set from the command line as it needs to be a list of paths).
sphinx-build -Eaq -Dlanguage=$LANGUAGE $SRC $BUILD/$LANGUAGE
Your HTML build should end up in
NB. If you want to reproduce a Python documentation setup you will likely need to enable
sphinx.ext.oldcmarkup for the time being because Python did not switch to Sphinx 1.0 as of the time of our deployment. This extension will become moot as soon as Python does the jump. Additionally you might want to enable
AUTOSYNC and the Google Translate backend.