Localization of scikit-image website content. about scikit-image HOT 5 OPEN

Okay, I am glad then that this will probably not slow down updating documentation directly. If source version and translated version are out of sync, I guess there isn't some mechanism to make this transparent on the website?

Updating the website needs to be part of process of producing a new release.

I am more worried about something else. If we split into sphinx-generated documentation for which we maintain previous versions but put some documents on a static website without a version switcher, then we loose access to older versions of those documents. E.g. if we moved our user guide there, users wouldn't have easy access to guides for previous versions. This isn't necessarily a blocker for me, but maybe a trade-off in a few cases.

How does NumPy address this? It seems they solve this problem by duplicating certain parts..?

from scikit-image.

Thanks for reaching out @steppi and for the overview!

A few thoughts / comments from my site:

• For our main documentation, we are indeed using the pydata-sphinx theme. The theme seems to have its own internationalization support but I'm not sure how mature that is.

• For https://scikit-image.org, we've been in the process of moving that site to the Scientific Python Hugo theme as well, see scikit-image/skimage-web#94. It's just not been our highest priority yet but we can pick that up again.

And a few questions:

• While an (updated) document is being translated, is it practice to publish the source document already?

• It looks like NumPy moved the translated pages, such as the installation guide, from its main doc to https://numpy.org and under the umbrella of the Hugo theme. I'm curious how their experience with this has been. I worry about uncoupling our installation guide from the rest of the documentation which is versioned.

from scikit-image.

Thanks @lagru.

• For our main documentation, we are indeed using the pydata-sphinx theme. The theme seems to have its own internationalization support but I'm not sure how mature that is.

That seems helpful. It could simplify the simplify the process of generating the .po files containing strings segmented for translation, compared with vanilla sphinx.

• For https://scikit-image.org, we've been in the process of moving that site to the Scientific Python Hugo theme as well, see scikit-image/skimage-web#94. It's just not been our highest priority yet but we can pick that up again.

If this was something already planned, it would definitely simplify adding translations. Let me know if there's anything I could do to help out with that.

• While an (updated) document is being translated, is it practice to publish the source document already?

Yes, this is what we're doing for https://numpy.org, except in a few cases where the translations were added together with the English language update, (for example, the announcement that translations have been added.). After a change is merged into main, new strings are uploaded to Crowdin for translation, and translators are notified that there's more work to do. I guess it's not ideal, but having to coordinate with translators before making updates seems like it would add a lot of overhead for maintainers.

• It looks like NumPy moved the translated pages, such as the installation guide, from its main doc to https://numpy.org and under the umbrella of the Hugo theme. I'm curious how their experience with this has been. I worry about uncoupling our installation guide from the rest of the documentation which is versioned.

I don't think there have been any issues for numpy.org or scipy.org. Someone has to stay on top of things to make sure the website isn't neglected when changes are being made, and although I haven't really been involved in that side od things, my impression is that it isn't too bad. Updating the website needs to be part of process of producing a new release. At the least, an announcement with release highlights should always be added to the news section, and making any necessary changes to the installation guide should be part of the checklist when updating the website.

Let me know if you have any other questions.

from scikit-image.

I am more worried about something else. If we split into sphinx-generated documentation for which we maintain previous versions but put some documents on a static website without a version switcher, then we loose access to older versions of those documents. E.g. if we moved our user guide there, users wouldn't have easy access to guides for previous versions. This isn't necessarily a blocker for me, but maybe a trade-off in a few cases.

How does NumPy address this? It seems they solve this problem by duplicating certain parts..?

Ah, I see your point. I agree there's a trade-off here. There are things which clearly need to be versioned, and these should go in the documentation. Ideally, the brochure website should contain content which is unlikely to change frequently. There is common info between the brochure website and the documentation, but instead of thinking of this as complete duplication, I think it's more that the brochure website should contain broad summaries and documentation fleshes thing out. Specific details are liable to change, but I the website should just give a general idea which should be more static.

I think past versions of numpy.org may be interesting for historical reasons, but typically information drops off when it's no longer relevant. e.g. links to tutorials which no longer exist, installation info which is out of date, links to communication channels which no longer exist. For historical research, the internet archive seems sufficient, https://web.archive.org/web/20240115000000*/numpy.org. Any information which is tied to specific versions, and will remain relevant for those versions into the future should go in the documentation though.

In any case. I think this discussion about the website is separate from the translation issue. We can still set up the translation infrastructure for the current website as is, and any heavy lifting I'd need to do, I'll need to do anyway for other projects which will continue to generate their websites with sphinx and host the code on the primary repo.

from scikit-image.

I've created an FAQ here with more information on the translation project here, https://scientific-python-translations.github.io/faq/. Feel free to take a look and let me know if you'd be interested in participating or if you have any other questions. We're going to start moving forward only with the more enthusiastic projects, so if you're still unsure, you can wait to see how things work out for other project websites before making a final decision.

from scikit-image.