Currently, links to source code in the documentation look like this:

**Source code:** :source:`Lib/abc.py`

For documentation translators, this means that every module contains
a boilerplate string to translate. A small burden perhaps, but avoidable.
I propose to refactor the links in a directive, like so:

.. source:: Lib/abc.py

Then just the text "Source code:" gets translated (in sphinx.po) and
the rest is automatic. This could also benefit the presentation in
the future, if anyone wants to change the styling of these links.

Open question is how to handle the handful of links that contain several
source files (async I/O modules in particular). To make it language-agnostic,
perhaps the markup

.. source::
   Lib/asyncio/futures.py,
   Lib/asyncio/base_futures.py

could be rendered as if it were

**Source code:** :source:`Lib/asyncio/futures.py` | :source:`Lib/asyncio/base_futures.py`

Thoughts?

ISTM that translating this fixed pattern is possibly one of the simplest things a translator will be asked to do, so there is very little payoff to making the change.  

For a person writing the docs, it is best to leave it as-is so that the wording and presentation is easily customized for a situation unique to a particular module.  This becomes a much more difficult task if we have to override logic in a PO file.

Thanks for the suggestion, but I am -1 on this change.   Let's not take something simple and introduce hard-to-override implicit behavior.

Note that this is suggesting to introduce a `.. source` directive, not adjust the existing `:source:` role.

There's nothing preventing the use of the existing pattern in special cases, while using the new directive in the common cases.  I don't have context for how much effort this would actually save translators (perhaps we could get representatives from various languages/workflows could chime in?) so it might not be worth it on other grounds, but I don't think this should be shot down just for "but sometimes" :)

New directives introduce complexity. They should be saved for pervasive and non-trivial problems.

The motivation for this change is dubious (that a translator can't easily handle a simple fixed string pattern).  The OP grants that this is a "only small burden".   In general, translation is a large, difficult and time consuming task.  Adding this directive would not change that noticeably (changing the source text is among the easiest and most trivial subtasks).  It may even make translators job more difficult because it entails knowing how to edit the directive as opposed to use basic knowledge to make a simple in-line text substitution.

OTOH, there are costs.  Every new directive takes time to learn and remember.  This is especially problematic when the directives are specific to one project; otherwise, the documentation skills don't translate across projects.  Generally, it is best to use dirt simple, standard Sphinx markup, especially for trivial tasks like this one.

I do a lot of documentation work and am constantly wrestling will sphinx, many times unsuccessfully. Even among core developers, very few people already know all the directives that we already have.  Making the list longer doesn't make our lives easier unless a directive is solves a challenging problem and is commonly used.