sphinx-doc / sphinx-doc/sphinx

Make gettext builder add a flag for entries made from code-blocks

Open
#13,722 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

builder:gettext internals:internationalisation type:proposal
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.
Making code-blocks translatable in Python docs has caused some issues in tooling connected with translations' quality assurance:

Describe the solution you'd like
I would like to propose to make the Sphinx gettext builder leverage flags in PO files to mark the entries coming from code blocks as such. That would enable downstream tooling to interpret those flags and use them to ignore or change behaviour for such entries.

Describe alternatives you've considered
A workaround is being practiced by some teams, that builds gettext with disabled code-blocks, merges and reports on the translation quality basing on it.

Additional context
Gettext documentation doesn't explicitly allow or disallow custom flags for entries (it presents a list of officially supported flags). Some of the gettext utilities are said to remove custom flags, but general direction for the project is to persist them throughout transformations.

Additionally recently it was announced that there's a second syntax for flags, that we could consider taking into account when implementing the solution.

Thank you for reviewing my proposal.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the Sphinx gettext builder and inspect how PO entries originating in code-blocks are identified and emitted. Review the GNU gettext flag syntax and the recently announced alternative syntax before deciding how the marker should be represented. Done means code-block entries carry a usable flag for downstream translation-quality tools, with coverage for the generated output.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.