Issue #561 resolved

Configuration option: store translations in single .pot file

created an issue

The way I understand gettext support in sphinx tip right now is that one .pot file per section is created and that for every language .po/.mo files for each section are necessary.

I set up a very primitive example where I after calling "make gettext" get a .pot file for every .rst file in _build/locale.

The standard gettext layout is to either have one .pot file (po/project.pot) or numerous templates (template1/template1.pot, template2/template2.pot...). The translations itself are stored alongside the .pot file, named after their ISO 639 code (po/project.pot, po/ca.po, po/de.po...). An example of this can be found at

As a side-note: .mo files are for the user later on installed into /usr/share/locale (ie: /usr/share/locale-langpack/de/LC_MESSAGES/

For our work-flow it would be great if this was possible. Launchpad, our online translations tool, follows the standard gettext format. In it, .pot files are imported and translators would need to choose all available message catalogues one after another and translations would be split up in various files later on.

In the single .pot file case ( for example Launchpad paginates the strings (and looks in other projects for suggestions to translate).

It would be great if there was a translation_in_single_catalog option to allow above mentioned work-flow.

Comments (6)

  1. Robert Lehmann

    That's definitely a feature I have on my radar for a final release of sphinx-i18n as several users have asked for that.

    I already received a patch from Cyril R back in September which implements the feature you were asking for but in a backwards-incompatible way (which is not feasible sphinx-i18n is in productive use at Python Translations) at This needs a configuration option, tests, and documentation. I'll try to look into that in the near future.

  2. David Planella

    (Sorry for the unreadability of the post. The bitbucket editor does not seem to preserve line breaks when editing a comment :( )

    Has there been any progress on this? This is a feature that's going to be extremely useful in keeping up with current practices in the vast majority of Open Source projects.

    You are mentioning that the current branch implementing this needs a configuration option, tests and documentation, which I can follow. But you are also mentioning that the implementation is not backward-compatible with older versions of Sphinx.

    Two questions here: do you think a configuration or command line option would address the issue of compatibility?. And another thing - I know compatibility is important, but is there a strong reason to keep compatibility with older versions here?

    Note that there are two options here, both of which would satisfy the request of a gettext-compatible layout:

    1. Merging all translatable messages of all .rst documents into a single .pot file, stored along the translations (.po files) inside the po/ directory (or named something else).




    And translations would be in:

    _build/po/template.pot _build/po/sv.po _build/po/zh_TW.po ...

    2. Following the current approach of splitting translations in a .pot file per .rst file, but store each template it its own folder, so that each folder can contain the template and its translations. E.g. _build/template1/template1.pot _build/template2/template2.pot _build/template3/template3.pot ...

    This way translations could be stored separately without naming conflicts:

    _build/template1/template1.pot _build/template1/ca.po _build/template1/it.po _build/template1/zh_CN.po _build/template2/template2.pot _build/template1/ca.po _build/template1/nl.po _build/template1/fr.po _build/template1/nb.po _build/template3/template3.pot _build/template1/ar.po _build/template1/ast.po ...

    Thanks a lot for your work. Sphinx is plain awesome.

  3. Log in to comment