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

[m-aciek]

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.

[AA-Turner]

Is there prior art in eg pospell for the type of flag to use? Is it better to use a general 'disable checking' flag, or a specific 'provenance: code block' flag? Would the programming language of the code block be relevant?

Sorry for several questions, I don't know what would be most useful here. The link you have for flags was just to the general gettext page, so I'm also not sure what type of flag we should be outputting (workflow or sticky). A sketch example of output you'd hope to see would be useful.

cc also @JulienPalard as you linked to one of his commits & for his translation experience.

A

[m-aciek]

Is there prior art in eg pospell for the type of flag to use?

I didn't find any traces of prior art for our use case.

Is it better to use a general 'disable checking' flag, or a specific 'provenance: code block' flag?

I think 'provenance: code block' is better, as it allows different tooling to define custom behaviours, instead of using only on-off switch.

Would the programming language of the code block be relevant?

I think it would be, maybe as a second flag 🤔 ? I imagine that some advanced tooling could check

• code snippets correctness after translation and/or parity with the source snippet,
• spelling errors in comments and string literals.

what type of flag we should be outputting (workflow or sticky)

We should output a sticky flag (tied to a source string, not to be removed e.g. after improving the translation, like fuzzy flag).

A sketch example of output you'd hope to see would be useful.

After reading the new syntax announcement again, it looks like until 2027-01-01 writing a PO entry doesn't change (doesn't use #= line start). Also existing *-format flags provide flag category as postfix, we could try to be consistent with them.
Therefore I'd hope for something similar to the following:

#: ../../tutorial/introduction.rst:32
#, code-block-provenance, python-language
msgid "# this is the first comment\n"
"spam = 1  # and this is the second comment\n"
"          # ... and now a third!\n"
"text = \"# This is not a comment because it's inside quotes.\""
msgstr ""