Note on progress on not completed translations

[m-aciek]

I would like to propose adding a note to non-English docs which are not fully translated saying "This documentation is translated into [Polish] in [10.12]%. Consider joining the translations effort (link)."[1] That would set expectation for encountering not translated paragraphs and about the quantity of translated materials in general. Second effect (but not main) would be recruiting new translators by showing a link to translations guide/readme.

The second, recruitment sentence, is debatable. Maybe the first sentence would suffice.

Original idea by @kachinger.

[1] The link would be https://github.com/python/python-docs-xx

[egeakman]

It would be helpful to inform users that certain paragraphs may not be fully translated to avoid confusion and feedback such as "Why are there English words everywhere? I thought this was a complete translation."

As the Turkish translation team, we are currently facing challenges in recruiting enough translators to keep up with the workload. This may be an issue for other translation teams as well. Adding a "Join the translation efforts" text with a link to the translation README could help address this problem.

By the way, do you have any ideas on how the progress text can be implemented, specifically in terms of calculating the progress percentage? I'm assuming we want to track progress per file, but I'm not sure about the specifics. There is a package called potodo that can track the progress of .po files, maybe it might be relevant? Any thoughts?

[m-aciek]

By the way, do you have any ideas on how the progress text can be implemented, specifically in terms of calculating the progress percentage? I'm assuming we want to track progress per file, but I'm not sure about the specifics. There is a package called potodo that can track the progress of .po files, maybe it might be relevant? Any thoughts?

Yes, potodo calculates both total and per-file progress. There is a caveat in calculating the total progress though: some translations projects don't store PO files that haven't been started translating or don't have enough progress of translation on Transifex. That inflates calculated progress as we won't count not started (missing) PO files. We could add a --compare flag to lookup POT files as a base and compare our POs structure with POTs generated from CPython docs.

I was actually thinking of tracking total progress, at least in the first iteration. The majority of work is to be done on Sphinx side. I think static note at the top of every docs' article should be doable with Sphinx Extensions API. We also should wire up localizing the message in the note to various languages.

[JulienPalard]

Related to sphinx-doc/sphinx#1246

Should this kind of thing be implemented sphinx-side instead? It could be helpfull for anyone, not just cpython.

[humitos]

Should this kind of thing be implemented sphinx-side instead? It could be helpfull for anyone, not just cpython.

Yes. I'd like this to be implemented in Sphinx if possible since we need this in multiple projects I'm part of. If it's not possible to implement on Sphinx itself, it would be good to do it as an extension, so it can be easily re-used.

[m-aciek]

Related to sphinx-doc/sphinx#11157

[AA-Turner]

The next version of Sphinx will retain the translated attribute; thanks to @humitos for the PR!

A

[humitos]

The next version of Sphinx (7.1.0) will include the PR to keep the translated attribute in the nodes. With that attribute, we can achieve all the proposal from this PR:

• include a note on top of each page mentioning the total progress of the translation
• only include a note on those pages that are not at 100%
• highlight untranslated paragraphs with a different color

On that Sphinx PR, there is a link to an example project that uses this translated attribute to:

• show the total progress of the page (it uses Sphinx substitutions for this, like |translation-progress|)
• highlight only translated paragraphs

I'm happy to discuss more about these ideas and work/help others to work on a Sphinx extension that all the CPython translators (and other projects too) can use and benefit from. Are there more ideas you have we should focus on? Would the CPython official documentation use an extension like this if we implement it?

[AA-Turner]

Sphinx 7.1 includes the |translation progress| substitution variable out-of-the-box, which seems like it will solve @m-aciek's original request. The new translation_progress_classes configuration variable allows adding translated and/or untranslated classes to elements in each document, which can then be styled appropriatley.

A

[m-aciek]

@AA-Turner @humitos Thank you for your work on it! I've created a Sphinx ticket to discuss adding a built-in extension with the functionality proposed here.

[AA-Turner]

Is there anything further to do on the docsbuild-scripts side of things? Or should this issue remain open until @m-aciek has implemented & merged his extension into Sphinx?

A

[m-aciek]

I think we can keep it open in case there is some configuration change needed on docsbuild-scripts side of things (not sure it that would be the case), though it's not a strong opinion.

Or should this issue remain open until @m-aciek has implemented & merged his extension into Sphinx?

For what it's worth I'm afraid I won't be able to work on it at least until Christmas. Also I'm still not very familiar with Sphinx codebase, therefore I'm not sure how long it would take me.