Set placeholders on Transifex

[rffontenelle]

Transifex has this nice feature of setting custom placeholders that make translators job easier as it highlights the placeholders which can be copied to translation with Ctrl+Alt+NUMBER (1, 2.. n placeholders in the same screen).

According to Transifex's documentation, this can be set in:

1. Go to https://www.transifex.com/sphinx-doc/settings/validations/
2. Expand PO File (.po, .pot) checks
3. Last item, mark it as Warning (middle, yellow icon)
4. Click the Set up custom placeholders link in the same item
5. Set placeholders in the displayed dialog.

Now, which placedholders should be set? First of all, there is the literal ``something`` (double backticks) which is very common, hence deserves being a placeholder

Also there are other domains that are very common, and I feel they deserve being added. Maybe not all have to added, but the most common would be interesting to be set as custom placeholder, in my opinion. See below the full list of domains used in sphinx docs, preceeded by the number of occurrences.

NOTE: using confval as an example, :confval:` (adding a backtick after the colon) would be a good "starts with" expression, having ` as "ends with" expression in the Transifex's dialog for creating custom placeholders.

    641 :confval:
    338 :rst:dir:
    223 :ref:
    183 :file:
    127 :mod:
    112 :program:
    112 :meth:
    104 :doc:
    101 :dudir:
    100 :rst:role:
     97 :class:
     55 :term:
     49 :event:
     39 :command:
     35 :option:
     35 :func:
     18 :data:
     18 :attr:
     16 :dfn:
     14 :cpp:expr:
     13 :durole:
     11 :py:class:
     10 :samp:
      9 :exc:
      8 :manpage:
      6 :cpp:func:
      5 :py:meth:
      5 :kbd:
      5 :guilabel:
      5 :duref:
      4 :strong:
      4 :py:mod:
      4 :download:
      3 :py:data:
      2 :py:obj:
      2 :py:attr:
      2 :pep:
      2 :obj:
      2 :math:
      2 :literal:
      2 :envvar:
      2 :cpp:var:
      2 :cpp:texpr:
      2 :c:var:
      2 :c:texpr:
      2 :c:macro:
      2 :c:expr:
      1 :cpp:type:
      1 :code:

For the record, I've got the above list using the (ugly, improvised) command below and cleaning a little bit some false-positive occurrences:

egrep ':([a-z]+):' $(find -name '*.pot') | sed 's| :|\n:|g;s|msgid ":|\n:|g;s|` |`\n|g;s|`"$|`\n|g;s|`,|`\n|g;s|`\\\\|`\n|g;s|`\.|`\n|g;' | grep '^:' | cut -d\` -f1 | sort | uniq -c | sort -r

EDIT: Also deserves being added as placeholder: [#_]

[tk0miya]

Good idea! Let's set them up. How about setting up leading 10 items (used in 100+ times) as a trial?

[rffontenelle]

agreed!

[tk0miya]

Can you set it up? If possible, please go ahead.

[rffontenelle]

That requires organization admin role in sphinx-docs organization, and I have just a translator role.

[tk0miya]

Okay, I'll set it up later (maybe tomorrow).

[tk0miya]

I added double backticks and 10 roles. Please try it and let me know your opinion :-)

[rffontenelle]

So far, so good – much easier to identify these placeholders

[rffontenelle]

[#]_ deserves being added as placeholder too. Edited the original message with this info

[tk0miya]

BTW, Can we translate the title of the placeholder? Some roles can have its titles (ex. :ref:` next section <target>`). And these titles should be translated.

[rffontenelle]

@tk0miya I was about to mention this in here. Translated :ref: are being warned as missing custom variable. This is kind of annoying, but the worst thing is when translating on mobile devices: Transifex won't allow to tap on the placeholder to copy it to translation text area and then edit.

I think ref will need to be unset, sadly.

[tk0miya]

Okay, reverting.

[tk0miya]

Other roles also supports titles. So I removes the all of settings finally.

Thank you for your proposal. Please let me know if you find another approach.

Thanks,

[rffontenelle]

Looking at the numbers of "titled" roles (see below), it seems :ref: is the most "titled" of them, while others like :rst:dir: and :confval: have zero or a few "titled" occurrences for hundreds occurrences of the roles in the docs.

How about adding those that present zero or just a few titled occurrences? For a few occurrences still looks to me as a good tradeoff.

Unless it is possible to use regex when setting start and end of the placeholder -- I haven't found any notes on this in Transifex documentation --, I see no other way.

Also, literals (``this``) and footnotes ( [#]_, [1]_ and [2]_) aren't affected, and I think they could be kept regardless of the decision of the other roles.

For the numbers of titled roles currently in the docs, found in .pot files:

    100 :ref:
     44 :doc:
     14 :option:
     12 :mod:
     12 :dudir:
      5 :duref:
      4 :download:
      2 :rst:role:
      2 :rst:dir:
      2 :py:obj:
      2 :py:class:
      2 :program:
      2 :obj:
      1 :meth:
      1 :confval:

I found this list running from sphinx's locales dir:

egrep ':([a-z]+):' $(find pot -name '*.pot') | sed 's| :|\n:|g;s|msgid ":|\n:|g;s|` |`\n|g;s|`"$|`\n|g;s|`,|`\n|g;s|`\\\\|`\n|g;s|`\.|`\n|g;' | grep '^:' | grep '>`' | cut -d\` -f1 | sort | uniq -c | sort -r

Here is a compiled table with total number of occurrences of the roles and the number of titled ocurrences:

   total  titled   role
    641      1     :confval:
    338      2     :rst:dir:
    223    100     :ref:
    183            :file:
    127     12     :mod:
    112      2     :program:
    112            :meth:
    104     44     :doc:
    101     12     :dudir:
    100      2     :rst:role:
     97            :class:
     55            :term:
     49            :event:
     39            :command:
     35     14     :option:
     35            :func:
     18            :data:
     18            :attr:
     16            :dfn:
     14            :cpp:expr:
     13            :durole:
     11      2     :py:class:
     10            :samp:
      9            :exc:
      8            :manpage:
      6            :cpp:func:
      5            :py:meth:
      5            :kbd:
      5            :guilabel:
      5      5     :duref:
      4            :strong:
      4            :py:mod:
      4      4     :download:
      3            :py:data:
      2      2     :py:obj:
      2            :py:attr:
      2            :pep:
      2      2     :obj:
      2      1     :math:
      2            :literal:
      2            :envvar:
      2            :cpp:var:
      2            :cpp:texpr:
      2            :c:var:
      2            :c:texpr:
      2            :c:macro:
      2            :c:expr:
      1            :cpp:type:
      1            :code: