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.

1 files changed, 18 insertions, 0 deletions

diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst
index 3bf353e8d..128406410 100644
--- a/doc/usage/advanced/intl.rst
+++ b/doc/usage/advanced/intl.rst
@@ -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
 ----------------------------