Snakes on your Summer

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 python.

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 $BUILD/$LANGUAGE.

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.