Comments (11)
The next version of Sphinx will retain the translated
attribute; thanks to @humitos for the PR!
A
from docsbuild-scripts.
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?
from docsbuild-scripts.
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.
from docsbuild-scripts.
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
from docsbuild-scripts.
Related to sphinx-doc/sphinx#11157
from docsbuild-scripts.
@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.
from docsbuild-scripts.
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?
from docsbuild-scripts.
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.
from docsbuild-scripts.
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.
from docsbuild-scripts.
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
from docsbuild-scripts.
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.
from docsbuild-scripts.
Related Issues (20)
- Deleted file still on 3.11 docs HOT 1
- blurb now needs python >= 3.7 HOT 1
- Show "PDF are currently being built" instead of a 404
- documentation_options.js not invalidated when symlink changes
- Generate separate pages for every individual free function and class HOT 2
- 3.10 docs render incorrectly HOT 2
- Get URL's version number inside conf.py? HOT 7
- Whatsnew bad redirection when changing version HOT 9
- How to add Sphinx extensions to the docs? HOT 3
- Japanese translation has not been updated since 2022-08-01 HOT 5
- Deploying extra images with docs HOT 2
- switchers.js not compatible with Sphinx 6 / requires jQuery
- Increase the build frequency of English HTML stable (and pre-release?) documentation HOT 6
- Translations do not redirect to 3.12 HOT 3
- Full build with PDF is taking more than 24h HOT 29
- Track output of `check_versions.py` in a GitHub Actions workflow's job summary HOT 1
- Skip cache invalidation not used in symlink()
- Dev docs not updating HOT 2
- make logs public? HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docsbuild-scripts.