Hello,
I would like to propose a modification to the criteria for when a translation can be included in the language switcher.
I have written up my proposal and uploaded it to google drive as PDFs are not supported by this forum.
1 Like
meta: please just post the text in this forum directly.
5 Likes
Markdown Version many thanks to @Nineteendo who got it done before I could.
A Request For the Modification of PEP 545
Abstract
This document proposes updates to the criteria for including a translation in the language switcher on docs.python.org, prioritizing the translation of the most frequently visited and essential documentation pages.
The Current State
Below you can find the relevant extract from PEP 545.
Add Translation to the Language Switcher
As soon as the translation hits:
- 100% of bugs.html with proper links to the language repository issue tracker.
- 100% of tutorial.
- 100% of library/functions (builtins).
the translation can be added to the language switcher.
Proposed Modification
Below you can find my proposed modification to the extract shown above.
Add Translation to the Language Switcher
As soon as the translation hits:
- 100% of bugs.html with proper links to the language repository issue tracker.
- 100% of the following sections of tutorial:
- index
- introduction
- datastructures
- classes
- errors
- 100% of the following sections of library:
- index
- functions
- venv
- (only 50%) stdtypes
- csv
- turtle
- math
- argparse
the translation can be added to the language switcher.
Reasoning
I recently spent a whole day translating the Polish translation as I wanted to see it in the switcher this year! However, after it was merged we (the translators) started looking at what to translate next. I was surprised to discover that some of the most popular pages we had not yet translated. This raised a question: shouldn’t the requirements for inclusion in the switcher prioritize the most visited and useful pages to better serve the community?
Therefore, one of the deciding factors for the proposed list is their popularity in the English documentation. The most visited page (as per Plausible · docs.python.org) is not even required for the switcher, yet the thirtieth is. The original seems to focus more on people learning Python however this is very extensively covered on many other websites and hundreds of videos on YouTube. That said, I have included the library turtle which is commonly taught in schools.
I propose we focus more on the one thing docs./python.org has that other websites do not offer and which is more useful to the Python community, documentation. And so I have trimmed the list of tutorials and replaced them with the most used documentation. The suggested changes do not increase the overall workload for translators, as the total word count remains roughly the same. I myself as a translator would prefer to translate the most needed pages as it is a very large time investment.
4 Likes
Something along these lines looks sensible. I agree valuable translator is best spent on the pages people actually read.
We only started using Plausible properly in June, so these stats definitely weren’t available in 2017 when PEP 545 was originally written.
Right now all of the tutorial must be translated. I wonder if we should keep that requirement, so beginners can work through the whole thing in the same language? How much is the drop off in numbers as the tutorial progresses?
What sort of numbers do the suggested library pages get?
PS you have turtle and math twice.
From Plausible · docs.python.org (sorted by visitors with /3.13/ filtered out):
| Pos | Page url | Visitors | Pageviews | Bounce Rate | Time on Page |
|---|---|---|---|---|---|
| 2 | /3/library/functions.html | 176k | 234k | 74% | 5m 42s |
| 3 | /3/library/venv.html | 169k | 194k | 87% | 12m 56s |
| 4 | /3/library/stdtypes.html | 160k | 220k | 75% | 7m 17s |
| 9 | /3/library/index.html | 89.2k | 123k | 55% | 1m 34s |
| 13 | /3/library/csv.html | 74.5k | 91.3k | 83% | 13m 58s |
| 14 | /3/library/turtle.html | 69.4k | 102k | 80% | 17m 31s |
| 19 | /3/library/argparse.html | 58.6k | 74.2k | 75% | 9m 23s |
| 29 | /3/library/math.html | 48k | 59.9k | 81% | 7m 27s |
1 Like
Here are the urls starting with /3/tutorial:
| Part | Page url | Visitors | Pageviews | Bounce Rate | Time on Page |
|---|---|---|---|---|---|
| 0 | /3/tutorial/ | 186k | 244k | 57-64% | 1m 44s-2m 37s |
| 1 | /3/tutorial/appetite.html | 29.8k | 34.7k | 66% | 2m 14s |
| 2 | /3/tutorial/interpreter.html | 41.3k | 56.1k | 78% | 3m 13s |
| 3 | /3/tutorial/introduction.html | 41.8k | 56.5k | 77% | 4m 50s |
| 4 | /3/tutorial/controlflow.html | 59.9k | 82.7k | 76% | 5m 02s |
| 5 | /3/tutorial/datastructures.html | 103k | 130k | 73% | 5m 26s |
| 6 | /3/tutorial/modules.html | 39.5k | 47.5k | 76% | 5m 09s |
| 7 | /3/tutorial/inputoutput.html | 45.8k | 54.6k | 71% | 4m 31s |
| 8 | /3/tutorial/errors.html | 61.8k | 72k | 78% | 5m 49s |
| 9 | /3/tutorial/classes.html | 55k | 65.6k | 81% | 6m 48s |
| 10 | /3/tutorial/stdlib.html | 6k | 7.8k | 62% | 2m 38s |
| 11 | /3/tutorial/stdlib2.html | 3.5k | 4.3k | 57% | 2m 00s |
| 12 | /3/tutorial/venv.html | 36.1k | 41.4k | 85% | 6m 13s |
| 13 | /3/tutorial/whatnow.html | 1.6k | 1.9k | 52% | 1m 06s |
| 14 | /3/tutorial/interactive.html | 1.4k | 1.7k | 68% | 1m 24s |
| 15 | /3/tutorial/floatingpoint.html | 10.5k | 12.1k | 85% | 5m 10s |
| 16 | /3/tutorial/appendix.html | 4.1k | 4.8k | 64% | 2m 04s |
They start to drop off at part 10.
1 Like
I should have added my tables to my post, even more thanks to @Nineteendo. Another thing which I did not mention is it seems the tutorials seem quite ineffective. The average time spent on the page is very short. I left the more popular tutorials.
2 Likes
The original intention was clearly to focus on learning: learners are young, young people may need translated content.
Also learning two things at the same time (programming AND a foreign language) may be hard.
So if a page in c-api/ gets a lot of hits, I don’t care, most people playing with the C API understand english (I’d even bet they prefer reading the c-api/ doc in english).
The other way around, I originally included bugs.html, even if it’s almost never read, because it’s a good way to contact the translation team.
So focusing on the numbers of page views is not enough.
About the proposed change:
I’m not OK to add details about what to translate and what not to translate in tutorial/, let’s keep things short and simple, we’re humans.
I’m ~OK to add stdtypes, learners spend a lot of time on this page, but it’s also huge, so “50% of stdtypes” make sense.
I’ll not OK to add csv / turtle / math / venv, we all agree that it has to be translated, but making it a requirement to be added to the language switcher, why?
Maybe being added to the switcher shine some light on the translation effort of the added language, and helps gather more contributors, so being added soon is not that bad, let’s not ask too much.
3 Likes
Stan — thank you for the time you’ve spent translating into Polish, and for raising this proposal.
I haven’t checked recently, but I believe that the requirements as they currently stand represent ~3-5% of the total documentation to be translated before publicly showing the switcher. On the one hand this is a fairly low bar (for readers), as we provide no guarantees on translation for the majority of the documents. This might spur people to translate, or it might be an annoying experience — I’m ill-positioned to comment as a native British speaker of the source language. On the other hand this is a somewhat high bar for translators, and as you note the entire tutorial must be translated.
I agree with Julien that we shouldn’t include library modules in the minimum requirements. I’m also minded to agree that if we adjusted the requirements we should be adding pages such as stdtypes.html.
One thing that has been brought up in the past (& I mentioned recently on the docsbuild issue you opened) is the potential for using a dedicated language/region/translation page somewhere, instead of the switcher on each page. This would allow displaying more detail, such as the progress and status of each translation, which might mean that all translations in progress can be shown. [1]
A
Currently, we build every language with any amount of translation, but some are not shown in the switcher. ↩︎
1 Like
For the tutorial, I wonder if sections 14 (interactive interpreter details) & 15 (floating point representation) should be reclassified as tutorial appendices in the English version (since the actual page URLs don’t change, this kind of hierarchy tweak wouldn’t break any incoming deep links). Then the tutorial appendices could be collectively excluded from the translation switcher pre-requisites.
Everything up to and including section 13 seems useful to have translated up front. I wouldn’t worry about the relatively low numbers on sections 10 & 11 (the two standard lib overview pages) and section 13 itself (the “What’s next?” page). They’re never going to get much direct traffic (since they’re only overviews of things that are covered in more detail elsewhere), but they still make sense to include for the benefit of folks making their way through the tutorial sections in order.
2 Likes