GSOC Project: Add Translation System to DISCOVER Cookbook

[aterrel]

I'm happy to announce that @speco29 has been accepted as a student for GSOC. The proposal can be at #209.

We can keep this thread open for @speco29 to post on the progress of the project.

[speco29]

Thank you @aterrel for this oppurtunity.
looking forward to a productive summer:)

[speco29]

Hello @aterrel!
I think most of the issues of the Cookbook are resolved and almost every issue have an attached PR to it.
I would like to start working on the project now, is there anything in specific that I should start working on.
Also, for the translations, how many languages should be there. I was thinking of adding Chinese, Japanese for now as our top priority.

@OriolAbril is there anything in specific that I should start with regarding translations?
As I mentioned before for adding switches via HTM, CSS, JS but we want something custom made, could you help me out a bit to do some research regarding these also?

[OriolAbril]

is there anything in specific that I should start with regarding translations?

In addition to participating in the coordination discussion, I would recommend starting by building the cookbook in a different language as a standalone website. That is:

1. get the translatable text from the cookbook content in a suitable format, gettext (pot/po) files are probably the most common
2. translate part of a couple pages out of that, this is only to make sure the translated parts are pulled in correctly, any plain text editor should do
3. Build the translated version of the website with jupyterbook/sphinx
4. Publish it as a standalone website. The github pages of your personal fork of this repo should be enough for this.

In my opinion, these 4 steps are necessary independently of whatever other choices we do elsewhere. i.e. how and when to get the translatable content is susceptible to be automated (partially or fully) to aim for constant updating or to happen only when a release/tag is made... but it will need to happen either way, same for the other steps.

As I mentioned before for adding switches via HTM, CSS, JS but we want something custom made, could you help me out a bit to do some research regarding these also?

In general, I think the goal should be to aim for minimal (or ideally 0) disruption of the existing content and also keeping the amount of new/custom code low, as it will have to be maintained later on. I understand it might be necessary to implement custom html templates with some css styling and js code for the switchers for example, but I wouldn't feel comfortable doing that without the maintainers of the repo agreeing to that knowing they'll have to maintain it, otherwise it will probably stop working in a couple years but it might never be fixed. This is also a part with significant overlap with the versioning project, so I would wait until we reach a decision on #317 before looking too much into it. We are still in the community bonding period after all. It won't be feasible to attempt independent switchers that are not aware of each other but we'll also want a common style for the switchers so as much as possible their html/css/js should be shared if it needs to be added here from scratch. I am also not sure I'll be of much help here, I can defend myself with html and css but I have never used javascript

[speco29]

In my opinion, these 4 steps are necessary independently of whatever other choices we do elsewhere. i.e. how and when to get the translatable content is susceptible to be automated (partially or fully) to aim for constant updating or to happen only when a release/tag is made... but it will need to happen either way, same for the other steps.

Ok @OriolAbril
I will look into it and will update soon.

[speco29]

🗓️ Weekly Update – Community Bonding Week 1 & 2

This week, I focused on understanding different translation platforms, comparing workflows in Crowdin and Transifex to evaluate their approaches. I also had a discussion with my mentor about how translations are preserved across documentation projects, examining strategies for maintaining consistency and avoiding redundant work. Additionally, I explored the CPython documentation, analyzing how their language switcher functions and how files are organized within their repository.

Summary of Activities

• Explored translation services like Crowdin and Transifex, analyzing their file structures and automation workflows.
• Had a mentor discussion on best practices for maintaining translations and ensuring consistency across versions.
• Examined CPython documentation, studying how their language switcher is implemented.

Next Steps
📝 Drafting a guide for translators and language managers, outlining best practices for handling multilingual content.

[speco29]

Greetings @aterrel @OriolAbril !

Localization in Jupyter Book – Using Sphinx’s gettext

I've investigated how Jupyter Book handles localization and found that while it is built on Sphinx, it does not expose gettext functionality directly. To enable gettext, we need to convert _config.yml to conf.py so that Sphinx can properly handle translations.

Steps Completed:

• Ran sphinx-quickstart, which generated the necessary Sphinx project structure.

• Translated key settings from _config.yml to conf.py to align with Sphinx’s requirements.
  
  

• Successfully extracted translatable content, and the index.pot file is now generated in build/gettext/.
  

[OriolAbril]

I have used sphinx directly way more than I have used the jupyterbook command line so that will probably make things easier for me too going forward. If you want me to take a look you can share the link to the branch in your PR this this changes or open a draft PR and tag me. We should make the switch from yaml to python config without any change to other files (maybe the requirement ones).

Translated key settings from _config.yml to conf.py to align with Sphinx’s requirements.

Did you do it manually or throug the jupyterbook command line?

[speco29]

i did it manually

[speco29]

If you want me to take a look you can share the link to the branch

https://github.com/speco29/DISCOVER-Cookbook/tree/translation-docs
Will this link work?

[speco29]

I think i have done something wrong.
here, in the contribute box, at first it was showing 'Discard 5 commits' and 'Open pull request'. I choose the discard 5 commits option because the branch I pushed had commits which were not relevant to the translation branch, I thought clicking on discard option will remove those irrelevant commits but its showing something like this.
Please help me out here

[OriolAbril]

If you still have the translation-docs branch with the changes locally you should "force push" it. From the command line this would look like:

git status
# check the output says "on translation-docs branch"
git push --force

You have to avoid "pulling", "merging" or "rebasing" as these will take the changes on GitHub and bring them to your local computer which is the opposite of what you want.

If force pushing were not an option, you should be able to create a new branch from translation-docs and push that one.

---

For some more context, these diagrams from the turing way can help: https://book.the-turing-way.org/reproducible-research/vcs/vcs-workflow-branches.

"Feature B" is akin to your translation-docs branch. You created it from main and added commits to it, and while you did that, other people also created their own branches, opened PRs and new commits where added to main. In the diagram, "Feature B" is 2 commits ahead of main and 6 commits behind. As long as the commits in main don't change the same things you are changing this is not an issue, but it is good practice to update your branch from time to time with the changes in main. We can go over git/github workflow on the call to make sure we are all on the same page.

GitHub has some checks to make sure your branch is up to date and has a PR open if there are changes there not in main. And it looks like one of the options to get your branch up to date with main was to remove the orange commits so your branch is exactly main

[speco29]

I have opened a draft PR and has tagged you in it.
let me know if its okay.