Close #3985: Implement #noqa for i18n

When cross-references in the original paragraph and the translated
paragraph do not match, a warning is emitted.  It is useful, because
it allows to catch mistakes, but it can also be an annoyance since
sometimes it is expected that the cross-references will not match.
For example, a reference that is repeated in the original text may
need to be factored out for good style in the target language.
Another example: if the translator needs to translate a universally
understood term in the source language into a term that not everyone
knows is the translation of this original term, adding a reference to
the glossary can be warranted.  This allows the translated message to
start with '#noqa' in order to disable the warning.
This commit is contained in:
Jean Abou Samra
2022-01-16 03:15:46 +01:00
parent dfcb5d2f4c
commit 94d78d8747
7 changed files with 151 additions and 6 deletions

View File

@@ -68,6 +68,24 @@ be translated you need to follow these instructions:
* Run your desired build.
In order to protect against mistakes, a warning is emitted if
cross-references in the translated paragraph do not match those from the
original. This can be turned off globally using the
:confval:`suppress_warnings` configuration variable. Alternatively, to
turn it off for one message only, end the message with ``#noqa`` like
this::
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa
(Write ``\#noqa`` in case you want to have "#noqa" literally in the
text. This does not apply to code blocks, where ``#noqa`` is ignored
because code blocks do not contain references anyway.)
.. versionadded:: 4.4
The ``#noqa`` mechanism.
Translating with sphinx-intl
----------------------------