sphinx-doc/sphinx

Allow internationalization of 'conf.py'

Open

#1260 opened on Jan 3, 2015

View on GitHub
 (3 comments) (16 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)batch import
help wantedinternals:internationalisationtype:enhancement

Description

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?

Contributor guide

Tech stack
python
Domain
documentationinternationalizationlocalization
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
3-5 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
Understanding of Sphinx's gettext builderBasic Python
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
40
Research direction
Investigate how Sphinx's gettext builder currently extracts translatable strings from reStructuredText files (likely in sphinx/builders/gettext.py). Determine how to add support for scanning conf.py for strings wrapped in () and generate a dedicated POT file. Check existing tests and documentation for gettext builder to understand the expected output format. Also explore how conf.py is imported and executed to safely extract strings without side effects.