Internationalization with multi project sphinx setup

Question

I've a few python projects that all depends on the same core project. I've setup documentation for all of these with sphinx so that all subprojects include the documentation written in the core project + each subprojects own documentation.

This is done by simply adding a symbolic link from the subproject's documentation directory to the core projects documentation directory:

$ cd /path/to/subproject/a/docs
$ ln -s /path/to/coreproject/docs core
$ make html

This works great as long as I'm only writing documentation in a single language. Now I'm trying to use sphinx-intl to write the same documentation in multiple languages. How should I configure this?

I've tried setting locale_dirs = ['locale/', 'core/locale/'] and then running the following commands from my subproject:

$ make gettext
$ sphinx-intl update -p _build/gettext -l sv
$ make -e SPHINXOPTS="-D language='sv'" html

But it doesn't seem to find any of my changes in the .po files located in the core project.

Answer 1

I think your project structure doesn't work well for i18n of sphinx because:

• /path/to/subproject/a/docs expects locale files like: index.po and core.po.
• /path/to/subproject/a/docs/core/locale provides index.po instead of core.po

I think that you can get the expected behavior if you set it like the following:

1. set gettext_compact = True to all of conf.py.

2. symlink like below:

   $ cd /path/to/subproject/a/docs/locale/sv/LC_MESSAGES/
   $ ls
   core  index.po
   $ rm -R core
   $ ln -s /path/to/coreproject/docs/locale/ja/LC_MESSAGES core
   

subproject expect core/* message catalog files for each docs/core files and now there are.

However, I think this solution is not a proper way (and no proper way), but it worked in my environment.

The procedure is:

mkdir -p docs/coreproject
cd docs/coreproject
sphinx-quickstart -q -p 1 -v 1 -a 1 docs
cd ..  # go to docs
mkdir -p subproject/a
cd subproject/a
sphinx-quickstart -q -p 2 -v 2 -a 2 docs
cd docs/
ln -s ../../../coreproject/docs core
mkdir locale
cd ../../../coreproject/docs
mkdir locale
make gettext
sphinx-intl -p _build/gettext -l sv
sphinx-intl update -p _build/gettext -l sv
vi locale/sv/LC_MESSAGES/index.po   # modify po
make html SPHINXOPTS="-D language=sv"
# confirm 'core' _build/html/index.html 
cd ../subproject/a/docs/
make gettext
sphinx-intl update -p _build/gettext -l sv
cd locale/sv/LC_MESSAGES/
ls
rm -R core
ln -s ../../../../../../coreproject/docs/locale/sv/LC_MESSAGES core
vi index.po   # another modify
cd ../../..
make html SPHINXOPTS="-D language=sv"
# confirm 'sub' _build/html/index.html

project files: https://www.dropbox.com/s/cd65jt4h0x31cse/sphinx-intl-issue-20-docs.tar.gz?dl=0