Provide translated french translation on docs.python.org

[JulienPalard]

BPO	26546
Nosy	@terryjreedy, @vstinner, @benjaminp, @zware, @Vgr255, @JulienPalard
Dependencies	bpo-28331: "CPython implementation detail:" removed when content translated
Files	build_doc_fr.patch allow_sphinxopts.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = created_at = labels = ['type-feature', 'docs'] title = 'Provide translated french translation on docs.python.org' updated_at = user = 'https://github.com/JulienPalard' ``` bugs.python.org fields: ```python activity = actor = 'vstinner' assignee = 'docs@python' closed = True closed_date = closer = 'mdk' components = ['Documentation'] creation = creator = 'mdk' dependencies = ['28331'] files = ['42150', '43865'] hgrepos = [] issue_num = 26546 keywords = ['patch'] message_count = 15.0 messages = ['261654', '261989', '262055', '266744', '266745', '266748', '266755', '266757', '266759', '266764', '266775', '271159', '283126', '303992', '304039'] nosy_count = 7.0 nosy_names = ['terry.reedy', 'vstinner', 'benjamin.peterson', 'docs@python', 'zach.ware', 'abarry', 'mdk'] pr_nums = [] priority = 'normal' resolution = None stage = 'resolved' status = 'closed' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue26546' versions = [] ```

[JulienPalard]

Hi,

The french translation of the Python documentation just hit a 21% coverage in terms of pageviews (According to statistics nicely provided by EWDurbin). (It's 14% of the total strings to translate).

I think it may be a good time to push the translation to *docs.python.org*, so french speaking people will be able to find it naturally, and more translators will be aware of it, increasing the translation speed.

Also it will probably motivate other translations (http://docs.python.jp/3/, http://docs.python.org.ar/tutorial/3/index.html, others ?) to work in a more standardized ways, and make their translations more discoverable.

So there's two discussions to have: The URL, and the "how".

# URL

I think the only reasonable possibility is *docs.python.org/{country_code}/*

Having a CCTLD per translation is near impossible (a LOT or work and highly time consuming) as some domains are unavailable like python.fr and some other have high restrictions like having a physical presence in the country (like python.ca, python.pt.br) or having a commercial relation with a local company like for python.com.tr).

Also it allows localization via *docs.python.org/fr_FR/* even if I don't think we need it soon.

If you have other ideas, better than *docs.python.org/fr/*, that's why this issue is opened.

# How to

We have a Makefile which like docsbuild-scripts delegates naturally most of its work to the sphinx Makefile in Doc/Makefile, and is capable of building french versions of 2.7, 3.3, 3.4, and 3.5 in a simple invocation of make build_all MODE=autobuild-stable (cloning itself from the github repository, applying various patches (typically to configure sphinx to generate french). 3.2 is also possible but not built by default (no autobuild-html in its sphinx Makefile).

I think docsbuild-scripts may delegate the french generation by simply cloning/updating our repository and calling our makefile. A patch (attached) will be necessary in docsbuild-scripts to copy generated doc to /fr/ and send purges to the CDN.

Finally, once all this is running, we'll start a discussion about cross-linking both documentations, probably reopening https://github.com/sphinx-doc/sphinx/issues/1246.

[terryjreedy]

I agree on the url. It can always redirect to a CCTLD if there is one.

You *might* want to discuss the how on python-ideas list.

[JulienPalard]

You're right Terry, I posted on python ideas in case someone comes with a good idea, I also explained my vision in a lot of details to gather the widest feedback possible on each point that came to my mind:

https://mail.python.org/pipermail/python-ideas/2016-March/038879.html

[JulienPalard]

Hi,

The thread on python-ideas did not raised a long conversation, I don't think many english speaking people are interested in this subject, and non-english people are not in this list.

BWT, we translated a lot since march: translated 23% of the strings (versus 14% in march), and we'd like to serve a greater number of readers by hitting docs.python.org/fr/, so this messages is a ... bump ?

If I can help in anything, don't hesitate, but I think there's almost nothing left to, I already provided a patch for https://github.com/python/docsbuild-scripts to build the internationalized versions of documentation, tested it as far as I can without knowing your production servers by replicating the same paths on my test machine.

[vstinner]

About the URL, we are only talking about 4 languages:

• english
• french
• japanese
• spanish

For docs.python.org.ar, I don't know if it's "spanish" or "spanish of Argentina"?

For a technical documentation, I don't expect to have a flavor of the docuemntation for the USA, UK, Australia, etc. It's the same for french, I only expect one french version. Same for japanese. For spanish, maybe we might support to have other flavors?

We can take a look at PHP documentation since they already support a wide choice of languages. English is "en", french is "fr", japanese is "jp", spanish is "es". Only Brazilian Portuguese uses "pt_BR".

PHP uses the URL http://php.net/manual/\<language code>/

I suggest to make english "implicit", the default, and don't break existing URLs since they are now hardcoded in many books, many websites, etc. I don't think that it's worth to add "/en/" and add many redirection pages.

What do you think?

[JulienPalard]

About the URL, we are only talking about 4 languages

Yes, and other are clearly not ready to be merged, I still don't know if they want it to happen soon.

For docs.python.org.ar, I don't know if it's "spanish" or "spanish of Argentina"?

Same conclusion: I don't know either, but let them decide. In all cases, we'll not merge them until they ask for it, so, probably not even this year. Let's do things one by one, showing the way. (Personally I think we may propose them /es/, and if a es_ES version shows up, move /es/ to /es-ar/ and give /es/ to es_ES, but that may just never happen...).

For a technical documentation, I don't expect to have a flavor of the docuemntation [...] English is "en", french is "fr", japanese is "jp", spanish is "es". Only Brazilian Portuguese uses "pt_BR".

Yes my proposition has a whole paragraph about "Dropping the default locale of a language". Around the same subject, it's still undecided if we use a dash (IETF format) or an underscore (gettext format) to separate language and locale, but as we only have "fr" from now, we don't really have to decide today. We'll have to decide when we'll merge "pt-br" which does not even exists (one of some few languages having a "mandatory locale part").

I suggest to make english "implicit", the default, and don't break existing URLs

+1, we do not need to break anything, let's just don't add /en/ for "upstream" documentation, that's in fact what my proposed patch does.

What do you think?

Look like we agree on all points.

[terryjreedy]

From what I know of regional and country variations in spanish, the main grammatical differences are in usages, such as the informal plural 2nd person, that need not appear in a techical manual. I don't know about recently acquired technical terms. From reading pyar for awhile, I also know that it has participants from all over latin america, so I suspect that their translation is not necessarily Argentina-specific. Conclusion: we (pydev) should not worry until there is an actual conflict from competing translations.

The patch has this table:

+ # version, target, isdev + ('3.4', WWWROOT + "/3.4", False), + ('3.5', WWWROOT + "/3.5", False), + ('3.6', WWWROOT + "/3.6", True), + ('2.7', WWWROOT + "/2.7", False)

Why is 3.4 included, given that it now has the same status as 3.3? Would it not be easier to default to False and only list 3.6? Is it because you maintain separate branches for different 3.x branches? Given the presence of Version Changed and Version Added paragraphs, that is almost unnecessary. (Not having Version Deleted items is the main reason they might be.)

Is/are the main author/maintainer(s) of build_docs.py already nosy on the issue, to review? I cannot even though at least mildly interested. (The disconnect between interest and technical expertise is part of the problem with translation issues.)

There is no Rietveld review link for the patch. I do not know if it is the form of the patch or the target file. Viktor, do you? If not, someone on the core-mentorship list would.

[zware]

I think you should submit this as a PR against docsbuild-scripts, it will be easier to review there.

[JulienPalard]

From what I know of regional and country variations in spanish, [...] we (pydev) should not worry until there is an actual conflict from competing translations.

Totally agree.

The patch has this table:

• version, target, isdev

• ('3.4', WWWROOT + "/3.4", False),
• ('3.5', WWWROOT + "/3.5", False),
• ('3.6', WWWROOT + "/3.6", True),
• ('2.7', WWWROOT + "/2.7", False)

Yes, it sticks to the current style: https://github.com/python/docsbuild-scripts/blob/master/build_docs.py#L33

Why is 3.4 included, given that it now has the same status as 3.3?

What do you mean with "the same status" ? From my translator point of view, they still diverges, like in [Doc/library/zlib.rst:233](https://github.com/python/cpython/blob/main/Doc/library/zlib.rst#L233):

\< "If the optional parameter *max_length* is supplied then the return value " ---

"If the optional parameter *max_length* is non-zero then the return value "

And I don't think we can rely on certain releases being theorically identical to others, it look like an exception, look like it's not always true. I still prefer having a clear tree of versions but we're (humans) only translating the latest version, we have scripts replicating our work to others.

Yet, if you tell me that there's work ongoing (that I clearly missed) to have every documentations, like by major version, converge to single one, with just some paragraphs added, it may simplify my hierarchy.

Would it not be easier to default to False and only list 3.6?

Again I stick to the current style of the script, so ease its reading as a whole, but I agree, if we change it, let change it in another commit?

Is it because you maintain separate branches for different 3.x branches? Given the presence of Version Changed and Version Added paragraphs, that is almost unnecessary. (Not having Version Deleted items is the main reason they might be.)

I am not aware of "Version Added" and "Version Changed" paragraphs, I understand that this is a policy to only add new paragraphs and never modify them inside the 3 major version ? This is cool for me, as said in my last paragraph, it may reduce the number of versionned .po, but it will not change the human workload (script replicating between po files ...).

Is/are the main author/maintainer(s) of build_docs.py already nosy on the issue, to review?

Yes, I soon nosyed Benjamin Peterson, look like he's the father of this script, if we trust commits here: https://github.com/python/docsbuild-scripts/commits/master

I even mailed him personally to speak about it (and he even replied once), but he's probably highly busy, and this is something I can understand. So here is my call on the issue to try to move this issue forward (I try to push this project less than once a month, to avoid buzzing everyone ears with this non-critical issue...).

I cannot even though at least mildly interested. (The disconnect between interest and technical expertise is part of the problem with translation issues.)

Yes I also fully understand that the french translation of the documentation is not a point of interest for most of you upstream ^^ don't worry.

[JulienPalard]

@zach.ware done: https://github.com/python/docsbuild-scripts/pull/1

[terryjreedy]

By 'same status', I meant that 3.4 is on 'security maintenance', just like 3.3 and 3.2. But do whatever a reviewer wants.

Some people are busy at PyCon this week. Anyway, I think Zack pointed you in the right direction.

[JulienPalard]

I'm on the way of simplifying my pull request for docsbuild-script with two goals in mind:

• Simplify to make it more robust
• Avoid executing external (~untrusted) Makefile on docs.python.org servers

To achieve this, I need to pass sphinx options to the [Doc/Makefile](https://github.com/python/cpython/blob/main/Doc/Makefile), I'd like to call, typically:

make autobuild-stable SPHINXOPTS='-D language=fr -D locale_dirs=./locale/'

Which work if [Doc/Makefile](https://github.com/python/cpython/blob/main/Doc/Makefile) don't erase but append to the SPHINXOPTS variable. Which is done by allow_sphinxopts.diff.

We may simplify it further by adding locale_dirs to [Doc/conf.py](https://github.com/python/cpython/blob/main/Doc/conf.py) which does not break the english build, but I'm not sure if it's of any interest.

We may abstract it further by accepting a new parameter like SPHINXLANG='fr', with a default of 'en', but in every case I think it's a good thing to allow passing arbitrary SPHINXOPTS so let's start with this?

[JulienPalard]

For the record, I opened a WIP pull request here: https://github.com/python/docsbuild-scripts/pull/8

Feedback is welcome.

[JulienPalard]

→ https://docs.python.org/fr/

[vstinner]

Since you closed the issue, Julien, I changed the status of the PEP-545 to Final: https://github.com/python/peps/commit/14092e51dea5c5c6391458da4a2ad92adad227b9