sphinx-doc / sphinx-doc/sphinx
Make gettext builder add a flag for entries made from code-blocks
Nobody has claimed this yet.
- 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:
- spellchecker wrapper pospell is crashing when parsing codeblocks, but even without crashes we wouldn't like to spellcheck Python code, at most only comments
- sphinx-lint library expects PO entries to consist of valid reStructuredText, and some code-blocks were failing the linting because of that; those are fixed in Python docs, but potentially some new cases may arise.
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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