Need documentation for link markup with i18n

[shimizukawa]

Link markup with i18n strategy recommendation should be added somewhere in the sphinx documentation.

https://groups.google.com/d/msg/sphinx-dev/uLjb0B-J5r0/PY_9MKt6gG8J

#!text

>   Here's how you can `download Django`_.
>
>   .. _download Django: https://www.djangoproject.com/download/
>
> When translating, this is suboptimal, because if you translate "download
> Django" in the paragraph, the link is lost. So:
> 1. Is there a recommended practice about how to include i18n-friendly links
> in sphinx docs?

1a. Sphinx-1.2b1 already solved this problem.
However, if the two links with `title string`_ style are included in one sentence,
you can not change the order of the links in the translation.

1b. `download Django <link-target-url>`_ style link always work
(include Sphinx-1.1.x).

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1191
• Originally reported by: Takayuki Shimizukawa
• Originally created at: 2013-06-10T06:13:44.607

[mitya57]

With modern docutils (0.11 and newer), one can also use references instead of URLs, like:

`download Django <django_>`_

.. _django: http://example.com/

This is a bit easier for translating.

[shimizukawa]

@mitya57 exactly!
I wrote several ref patterns at a3109f6 as a testing of translation.
I'll write them include it suggested by you ;)