Allow internationalization of 'conf.py'

[shimizukawa]

It could be usefull to add a new POT template for marked as translatable strings in 'conf.py' file.

---

Hi, Sphinx team.

At least in version 1.1.3, 'gettext' builder only creates POT templates for reStructuredText documents. But some configuration options, defined in 'conf.py', also need to be translated, in order to enhance translatability of all parts of a given documentation.
For example, such a need occurs at least for:

• 'extlinks' mapping from 'sphinx.ext.extlinks',
• project's name or copyright,
• date and time.

It should be possible to let mark all desirable strings with '_()', where choice could all fall at project's discretion. 'gettext' builder then could generate a dedicated POT file, letting translators add translations for these strings. (I'm not sure of last step, for generation of e.g. HTML built files, with such a modified 'conf.py'.)

What do you guys think about this idea, and then about its feasability?

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1260
• Originally reported by: fero14041
• Originally created at: 2013-09-09T13:49:19.868

[ngulden]

I want to raise this topic. I also have the need for translation in the conf.py file.

For example, the project configuration is used as document title in the theme for HTML and in the PDF build. As native speaker I want to read the translated document title.

I tried the following in my conf.py:

from sphinx.locale import _
project = _('My document title in English')

When I run make html, I get the following traceback:

sphinx-build -b html -D language=de . _build/de
Running Sphinx v4.4.0
loading translations [de]... done
Initializing Spelling Checker 7.3.2
WARNING: The config value `project' has type `_TranslationProxy', defaults to `str'.

Extension error (sphinx.config):
Handler <function check_confval_types at 0x7f6313866e50> for event 'config-inited' threw an exception (exception: expected string or bytes-l
ike object)

[ngulden]

I have a document in two languages and they both have the same English title. I need translated titles. Here are the examples:

• English document
• German document
• Source

[j123b567]

I have created a workaround for this and it works in all situations I need. But it is still an ugly workaround. _ is already implemented as _TranslationProxy doing similar thing, but it is not derived from str so it fails in multiple scenarios.

# lazy_format.py
class LazyFormat(str):
    def __new__(cls, msg: str, *args, **kwargs):
        instance = super().__new__(cls, msg)
        instance._lazy_msg = msg
        instance._lazy_args = args
        instance._lazy_kwargs = kwargs
        return instance

    def __str__(self):
        return self._lazy_msg.format(*self._lazy_args, **self._lazy_kwargs)

You must place this in some other file then config.py and then import it or you will just get pickeling error.

This class will postpone the string rendering to the latest possible state so you can later do in conf.py

# conf.py
from sphinx.locale import _
from lazy_format import LazyFormat

project = LazyFormat(_('My document title in English'))
copyright = LazyFormat(_('© {year}. Version {version} {author}'), year=2024, version="1.0", author="me")

Then just create sphinx.po with content like

msgid "My document title in English"
msgstr "Mia dokumenttitolo en Esperanto"

msgid "© {year}. Version {version} {author}"
msgstr "© {year}. Versio {version} {author}"