python
Exclude include in `reference/grammar.rst` in gettext builds
The include is too big (one string) and translations leave it untranslated.
📚 Documentation preview 📚: https://cpython-previews--133868.org.readthedocs.build/
This will exclude any other formats -- text, or any custom/future one.
Do you know why something like not gettext doesn't work?
I tried not gettext and it did not work unfortunately. (Previous commit)
Is it because not isn't supported, or because gettext isn't the right tag?
.. only:: gettext works as expected, so it must be the first.
The only directive doesn't seem to support not logical operator, according to the docs and the source code.
This doesn't feel like the right solution, though.
I second that. The grammar contains many comments, which definitely would be helpful if translated. In my opinion we should split the grammar include for gettext builder by every double newline character. This could be controlled as an option in the literalinclude directive (or a default)? This would make the translatable units sections smaller.
IMO even if we do it should not be prioritised. If someone is reading the grammar, they should probably know English.
There are a few hundred lines, we won’t translate error messages or var names anyway, is there really a point?
I see it being similar to code snippets – we should translate only comments here. As we don't have a way to parse what's comment and what's not, to allow the comments translation we should allow translation of the whole grammar content. I agree it's not a priority from whole translation perspective.
Note that many comments here mention features that this version of the Grammar omits.
IMO, we should copy any relevant comments to the preceding note, or preceding chapters (many of them are already there!), and then remove the comments altogether.
Thinking further about this, currently translating it is a poor time investment since the translation is invalidated every week when the file changes.
I propose to for now, exclude it so that people do not spend time translating it. And, if we do want to translate it, a process which will need some discussion be devised elsewhere.
IMO, we should copy any relevant comments to the preceding note, or preceding chapters (many of them are already there!), and then remove the comments altogether.
That seems like something for your stream:-)
@StanFromIreland After your last comment, I'm unclear what you think the next step for this PR should be. Close? Modify? Keep as is? Thanks.
I think we need to action now, because there are people translating now.
The fastest/easiest approach is to remove it (which would be this pr), a long term fix can then be worked out.
Per this Sphinx issue https://github.com/sphinx-doc/sphinx/issues/11787, it seems there is no better way to exclude something currently.
I'll close this as I don't think it's the right approach. It might be that we need to make changes in Sphinx (per the linked issue), or something like ifconfig could work (untested).
A
The Sphinx issue has been open for two years, I worry it is not going to be closed any time soon:-(
To at least save Transifex translators from this trap, I think we can add this message to our exclusion list.