|version| and |today| might be translated

[rffontenelle]

The strings |version| and |today| from line 9 and 10 from source/index.txt are currently available in the translation file and might get translated, but AFAIK they should not. If that's the case, it would be nice to 1) make it UNtranslatable somehow or, alternatively, 2) add a TRANSLATORS comment telling that it should be kept as is.

[sebp]

After digging deep into the Sphinx code, I have to report that this doesn't seem to be possible. The issue sphinx-doc/sphinx#1608 already requested such a feature.

Comments are simply removed and only the source file and line are stored in the POT, as indicated in the template.

Skipping |version| seems also difficult. Essentially, Sphinx traverses the document tree and adds every node that passes is_translatable as text to the catalog. It does skip the node with the actual value for |version| (replaced by sphinx.transforms.DefaultSubstitutions), but does include the raw contents of its parent, which is a paragraph, instead.

[rffontenelle]

The good news is that Sphinx shows a warning when the value between |pipes| is not a recognized variable, so for instance if I translate |version| to "|versão|", the "versão" will be a "unrecognized substitution". Warnings are being treated as erros, so build will fail.

The bad news is that if I translate removing the pipes around the word, e.g. "|version|" to "versão", it will go through without popping up the issue.

[rffontenelle]

One simple (and kinda ugly) workaround to make sure the translator does not get it wrong would be to add to the workflow some test like, e.g.

grep 'msgstr "|version|"' translations/po/<lang>.po > /dev/null
if [ $? -ne 0 ]; then
    # warns/blocks the PR due to missing "|version|"
fi