Recommended link syntax for i18n

[cla...@2xlibre.net]

Hi,

We are working to make the Django documentation translatable with sphinx-i18n. Currently, we have many links in the documentation that look like this:

  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?
2. Could this recommendation be added somewhere in the sphinx documentation?

Claude

[gilberto dos santos alves]

see these links

[1] http://aria2.sourceforge.net/manual/pt/html/README.html#referencias
[2] http://aria2.sourceforge.net/manual/pt/html/_sources/README.txt

and original files in english are here

[2] http://aria2.sourceforge.net/manual/en/html/index.html

2013/6/8 <cla...@2xlibre.net>

--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
gilberto dos santos alves
+55.11.98646-5049
sao paulo - sp - brasil

[Takayuki Shimizukawa]

Hi Claude,

2013/6/9 <cla...@2xlibre.net>:

> We are working to make the Django documentation translatable with
> sphinx-i18n. Currently, we have many links in the documentation that look
> like this:
>
> 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).

> 2. Could this recommendation be added somewhere in the sphinx documentation?

Not yet. I'll do it.

Regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa

[Claude Paroz]

Le lundi 10 juin 2013 à 13:09 +0900, Takayuki Shimizukawa a écrit :
> Hi Claude,
>
> 2013/6/9 <cla...@2xlibre.net>:
> > We are working to make the Django documentation translatable with
> > sphinx-i18n. Currently, we have many links in the documentation that look
> > like this:
> >
> > 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.

Oh yes, just tested and it works well. Great!

> 1b. `download Django <link-target-url>`_ style link always work
> (include Sphinx-1.1.x).
>
> > 2. Could this recommendation be added somewhere in the sphinx documentation?
>
> Not yet. I'll do it.

Thanks. Thanks also to Gilberto for the pointers.

Claude
--
www.2xlibre.net