Let us have custom placeholders in Transifex

[rffontenelle]

It would really nice to have custom placeholders to ease Sphinx documentation translation.

Adding custom placeholders causes the matched expression to be highlighted, be assigned unique numbers in that string, and to be warned if translation differs from the source string. I use it a lot in Python docs translation in Transifex, and I highly recommend to Sphinx docs.

Example of placeholders set in Python docs:

Setting this requires:

• someone with organization admin role in Transifex, which I don't have and reason why I'm bringing this up.
• to find out every rst roles used in the documentation
• to set each placeholdler in Transifex, one by one

I might have found some commands to print the candidates for custom placeholders:

# Run this from this project root directory
# Generate 'strings.txt' with the whole-line of all translation strings
for pot in $(find locale/pot -name "*.pot"); do (msgcat --no-wrap $pot > tmp; mv tmp $pot;); done
grep -h ^msgid $(find locale/pot -name "*.pot") | sed 's|^msgid "||;s|"$||;/^$/d' > strings.txt
git checkout locale/

# Find roles with two parts like :c:macro:`something`.
grep -Po '(^|\s+):([\w\-\_\~]*:){2}`' strings.txt | sed -E 's|^ +||;' | sort -u

# Find roles with only one part like :doc:`something` 
grep -Po '(^|\s+):[\w\-\_\~]*:`' strings.txt | sed -E 's|^ +||;' | sort -u

# Take not of the command-line arguments like ``-j`` (but will not use this output)
grep -Po '``-[\w\s\-\_ ]*``' strings.txt

# Also a placeholder starting with `` and ending with `` should also be added

# Find project-specific variables like "|today|" (prints nothing, but let's leave this documented):
grep -Po '|[\w\_\-]*|' strings.txt

These commands will print these:

Starting pattern for two-part roles (ending pattern is `)

$ grep -Po '(^|\s+):([\w\-\_\~]*:){2}`' strings.txt | sed -E 's|^ +||;' | sort -u
:c:macro:`
:cpp:expr:`
:cpp:type:`
:py:class:`
:py:data:`
:py:func:`
:py:meth:`
:py:mod:`
:py:obj:`
:rst:dir:`
:rst:role:`

Starting pattern for one-part roles (ending pattern is `)

$ grep -Po '(^|\s+):([\w\-\_\~]*:)`' strings.txt | sed -E 's|^ +||;' | sort -u
:abbr:`
:attr:`
:class:`
:code:`
:command:`
:confval:`
:data:`
:dfn:`
:doc:`
:download:`
:dudir:`
:duref:`
:durole:`
:envvar:`
:event:`
:exc:`
:file:`
:func:`
:guilabel:`
:kbd:`
:literal:`
:mailheader:`
:makevar:`
:manpage:`
:math:`
:menuselection:`
:meth:`
:mimetype:`
:mod:`
:newsgroup:`
:obj:`
:option:`
:pep:`
:PEP:`
:program:`
:ref:`
:regexp:`
:rfc:`
:samp:`
:strong:`
:term:`

Starting pattern for command-line arguments and literal text (ending pattern is ``)

``--
``-
``
  

[AA-Turner]

Hi @rffontenelle I've made you an admininstrator.

A

[rffontenelle]

Done, added to placeholders to the Transifex organization's PO translation validations.

This applies both to Sphinx UI strings (%r and {some-name} were not considered placeholders until now) ...

... and sphinx documentation strings:

For roles that links to another page/website and are commonly translated, e.g. check :ref:`this website <http://example.com>`., I matched 1) fully the occurrence without space e.g. go to :ref:`html-options`., and 2) matched simply the role name when its content has space (see ref in the screenshot above)