Translating Official Documentation to Spanish

[camporeale]

@ayalaluquez, @map0logo and me have been participating in the South American Jupyter Workshop this weekend, and started a working group to begin translating the official Jupyter documentation to Spanish.

The first thing we noticed is that there's no spanish docs at all in the documentation library:
https://jupyter.readthedocs.io/. So we decided to start from the beginning and work on the "Jupyter Notebook Quickstart" section. We translated all subsections:

tryjupyter.rst
running.rst
install.rst
contents.rst
migrating.rst
install-kernel.rst
glossary.rst

There's still some work to be done, particularly with checking internal references and rst formatting (didn't try to build the docs with sphynx yet), but we think translation is mostly completed.

We have forked https://github.com/jupyter/jupyter to https://github.com/camporeale/jupyter/ to temporarily work on this, and commited all translated files as {original}.es-ES.rst.

The only reference to the translation work we've found was this issue created last year on the jupyterhub repo.

We tried to follow some of the recommendations and definitions there, and the translation conventions on The Carpentries repo.

As I said before, the forked repo is just a temporary measure, because we're not sure what procedure we should follow to make the new docs publicly available in the official page in readthedocs.

So, there are a few questions we would like to ask:

• What would be the way to commit these files?
  Should we work on a forked repository and send pull requests for the new files? Create a specific repository for spanish documentation and upload there?

• How are the docs on readthedocs.org generated?
  We assume that there's an automated workflow with hooks from Github, so this would be very closely related to the previous question. On the other hand, there should be a decision on the URL for the docs, maybe using a path like https://jupyter.readthedocs.io/es/latest?

• Do you have any ideas/preferences regarding to work on next?
  We've been thinking that the most important thing would be to translate the documentation more related to new/inexperienced users, as they're the ones that would probably benefit the most to have docs in their native language (we believe that more advanced users have probably had more exposure to english documentation). But there is a lot of work to be done, we could continue translating the "Architecture" or "Installation, Configuration, and Usage" sections. But other suggestions are welcomed.

There's one last thing we talked about but did not worked on: application menus localization. We think that would probably have a also a huge impact for beginners, but it's something that we probably should talk about on another issue / discussion.

@fperez @willingc @damianavila @Ruv7 @choldgraf

[choldgraf]

This is a fantastic effort, thanks so much for kicking it off :-)

I will try to think about this along with you all this week sometime, I know that @leportella was also interested in helping push this forward as well.

From a technical perspective it seems like the information here is a good start: https://docs.readthedocs.io/en/stable/localization.html#project-with-multiple-translations

From a process perspective, this is where I am unsure how to go forward - the question is how to ensure the docs remain updated as they evolve over time etc. How can we make sure that the quality in each language is always up-to-date etc? For some pages maybe they won't change that much over time but I'd like to avoid the situation where a bunch of the docs are outdated for one language or another

[choldgraf]

I just heard that rOpenSci is having a community call on the 28th to talk about managing multi-lingual communities, I think it'd be quite useful if some of us sat in on that one! https://discuss.ropensci.org/t/community-call-managing-multilingual-communities/1722

[willingc]

Wonderful effort 😄 Fantastic to have some docs in Spanish.

A reasonable next step would be to contact Transifex and see if they will qualify Jupyter as an open source project. Django and Python, along with many open source projects, use it to manage translations. This would give an indicator of the amount of translation that has been done. po translation files should be in a repo.

To keep them up-to-date, you pretty much need to rely on the community of users to file issues as needed. It helps to have a language documentation manager/team for a particular language.

Probably makes sense to identify by language what the community finds most useful to translate and focus on that being maintained for stable versions.

In general, my view is that partial translations that have been proofread are better than no translations.

[betatim]

Ping @parente who worked on a setup for translating docs. I think it involved transifex and was in the jupyter-docker-stacks repo (or so?).

[camporeale]

Hi Guys, thanks for all the answers. I'm very new in the community (literally a couple of days :) ), so i'm not sure how all the decisions are made, and how we should move forward, so any help/guidelines are appreciated.

Seems that there are multiple things to consider, and it will probably take some deliberation to decide what would be the best path forward. Some thoughts:

• I will try to keep the translations going, using the forked repo for the time being, until we decide what to do. Will try to get more people involved to generate at least a couple of sections of the basic docs.

• I didn't know about Transifex, seems like a very good option, but there needs to be someone talking to them in order to get recognized as an open source project and getting some kind of (free?) plan.

• Friday's rOpenSci community call seems very interesting, I will try to participate, is there anyone else that could join from the Jupyter community?

Thanks again!

Franco.

[parente]

Thanks for the ping @betatim .

We've got a pretty good start on the setup and automation of the Jupyter Docker Stacks project using Transifex. The issue tracking the work so far is here jupyter/docker-stacks#827, some documentations for translators is here (https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/translations.html), and maintainer doc for adding a new language for translation on ReadTheDocs and Transifex is here for maintainers (https://jupyter-docker-stacks.readthedocs.io/en/latest/maintaining/tasks.html).

I've registered the free Jupyter org on Transifex. I'll add @choldgraf and @willingc to the org as admins to increase the bus factor. From there, someone can get a project space setup like we did for the Docker Stacks project.

I'm currently AFK and in the final week of an alpha release at work. After this week, I should be able to help out with the setup if that's of interest.

[willingc]

@parente Thank you.

[parente]

I created https://www.transifex.com/project-jupyter/jupyter-meta-documentation and I'm working on a PR with the configurations to push source English files to Transifex when they land in master branch in this repo, pull translations of those files back to this repo when they're complete in Transifex, and build all target languages on ReadTheDocs. The docs setup in this repo is a bit different from jupyter/docker-stacks so I'm working through a few problems. I hope to get draft up for others to review and contribute to soon.

@camporeale (and anyone else who would like to contribute translations), you can request to join the Transifex translation team by following the insturctions here: https://docs.transifex.com/getting-started-1/translators. The team to request to join is called "Jupyter Meta Documentation team". https://www.transifex.com/project-jupyter/jupyter-meta-documentation should be a direct link to join once you create an account.

[camporeale]

Hi! Sorry i've not replied before, it has been a very busy couple of weeks. I've been reading @parente notes and i'm still trying to understand how the complete process works... i think i will need a few more readings before i understand the workflow, but i've already made the request to join the team in Transifex. Hope to start translating soon.
After i get a few translations on the readthedocs page i'll talk to the people in the jupyter latam group to see if someone else would like to join the translation team.

[parente]

@camporeale Only a few people kicked the tires on Transifex a few months back, and it's been idle since, so don't fret if the process is confusing to you. We've not figured it out completely ourselves yet.

I don't see your request to join https://www.transifex.com/project-jupyter/jupyter-meta-documentation on Transifex. Can you check to see if you requested to join the right team or try submitting it again?

Also, there's nothing there to translate yet until #432 merges. I think a lot of people are a scipy this week so I wanted to give folks time to review it and ask questions before merging it myself.

[parente]

@camporeale Nevermind, your request just came through and I accepted it!

Let's give folks a few days to look at the PR. Once it merges, 🤞 , all of the strings in the English documentation should automatically show up in the Transifex UI for translation. Once you create translations there, Transifex opens PRs here to commit those translations to git. Once we have at least one file fully translated, we can setup ReadTheDocs to build both the English and Spanish versions of the documentation site. (At least that's how it's supposed to work in theory when we get everything wired up properly!)

[camporeale]

@parente Awesome, i'll be waiting for the PR to merge and then will start doing a couple of documents just to test how everything works.

[parente]

@camporeale I went ahead and merged PR #432. I see the source English strings have arrived in Transifex automatically. You should be able to start adding translations now on the Transifex website. I suggest starting at https://www.transifex.com/project-jupyter/jupyter-meta-documentation/dashboard/, hovering on the Spanish translation section, clicking Translate on the far right, and then selecting a portion of the doc to translate on the next page.

Transifex submits pull requests back to GitHub only when 100% of the strings in a section have been translated. It would be great if you picked a section with only a handful of strings to start. That way we can get quick feedback on whether the automation is configured correctly and setup the last portion of the translation pipeline--having ReadTheDocs build the https://jupyter.readthedocs.org/es/latest for us.

Let me know if you have any questions or hit any problems.

[camporeale]

Hi Peter,
I'll be starting with the translations today. Have been doing some tests over the weekend to understand transifex, fortunately it is very intuitive, i hope to have something done by the end of the week.

Thanks!

[parente]

Transifex automatically opened #439 with the .po files after @camporeale translated a part of the documentation. The next steps we need to take are the following:

1. ✅ Configure ReadTheDocs to build an /es subproject when the main doc project build triggers. I've done this before for jupyter/docker-stacks and can do it again here, but I'll need admin access to the jupyter/jupyter docs project on ReadTheDocs. @willingc can you grant me that access? My RTD username is parente.
2. (PR pending: Automatically refresh English source strings on Transifex #440) Configure a Travis job to regenerate .po files for the English source documentation whenever it changes and push them to Transifex. Something like https://github.com/jupyter/docker-stacks/blob/2ce7c06a61a1efc8d3d88bdd9ea718ee645ea78d/.travis.yml#L19-L24 which is how it's done in the docker-stacks project.

Once those two pieces of automation are in place:

• Changes to the English documentation cause strings needing translation to show up on Transifex.
• Translations completed on Transifex are opened as pull requests to this git repository.
• Merges of pull requests cause ReadTheDocs to build both the English documentation site as well as any configured translations.

[willingc]

@parente, You should now have admin rights on RTD for jupyter/jupyter.

[parente]

Thank you, @willingc.

[parente]

Tada!

[willingc]

Great work @parente and @camporeale. Fantastic to see 🎉

[camporeale]

Awesome!

[valerybriz]

Hello there! I would like to contribute to the translation to spanish but I got to the Transifex and there's no spanish option to join a team I already requested for it, but I wanted to let you know and if there's something else I have to do before going to Transifex would you please tell me what is it?

Thank you for your time!

[parente]

@valerybriz thanks for volunteering. It's interesting that Spanish (es) doesn't show up on the dashboard for you. @camporeale has gotten a start submitting translations for it. Can you try accessing https://www.transifex.com/project-jupyter/jupyter-meta-documentation/language/es/ and see if it shows a "join team" button for you?

[parente]

Ah, I think I see what happened. The docs in this GitHub project and hosted at https://jupyter.readthedocs.io/es/latest/ are translated in the "Jupyter Meta Documentation" project on Transifex. It looks like you requested Spanish as a language for the "Jupyter Docker Stacks" subproject (https://github.com/jupyter/docker-stacks, https://jupyter-docker-stacks.readthedocs.io/en/latest/)

I can totally add Spanish to the languages for jupyter/docker-stacks if you're interested in contributing there as well. I'm guessing you're looking to contribute to the main Jupyter docs here though. Just let me know.

[valerybriz]

@parente Yes I actually wanted to contribute to the main documentation, thanks for pointing me to the correct project in Transifex! I was able to join the team 😃

[peixeirodata]

Hi @parente,
I know that everybody here is talking about spanish translation, what is amazing! But I would like to contribute with the Brazilian Portuguese (PT-BR) translation. Is it possible? I already requested the language in the Jupyter Meta Documentation (Transifex)!

[liliancor]

Hi @parente ! I just sent a request to join the Portuguese (BR) translation team on Transifex. Hope to hear from you soon. Thank you very much. Best regards.

[parente]

@liliancor I looked in Transifex to grant your access, but don't see an outstanding request. (I've seen this behavior with Transifex before. Sometimes it's a bit slow.)

To try to speed things along, I sent an invite to your GitHub username. Hopefully that makes it through to you to accept. Let me know if not.

[liliancor]

Hello @parente! Seems it worked fine. I received an email saying I'm now part of the team. I also checked on Transifex notifications and it says the same. Thank you very very much!!!

[Caaddss]

Hello @parente I sent a request to join the Portuguese (BR) translation team on Transifex. :)

Can you see my solicitation??

[parente]

@liliancor Happy to have you helping out. Thank you!

@Caaddss I don't see a request from you to join the team. I tried adding you using your GitHub username. Transifex says your name does not exist. Can you let me know what your username is on Transifex or try joining the team again here: https://www.transifex.com/project-jupyter/jupyter-meta-documentation/? Thanks and sorry for the bother.

[Caaddss]

@parente my username is Caaddss

Im try to joining but doesnt work

[Carmelo2021]

El mar., 29 de octubre de 2019 7:10 p. m., Peter Parente < notifications@github.com> escribió:

…

@liliancor <https://github.com/liliancor> Happy to have you helping out. Thank you! @Caaddss <https://github.com/Caaddss> I don't see a request from you to join the team. I tried adding you using your GitHub username. Transifex says your name does not exist. Can you let me know what your username is on Transifex or try joining the team again here: https://www.transifex.com/project-jupyter/jupyter-meta-documentation/? Thanks and sorry for the bother. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#430?email_source=notifications&email_token=AAFJPE23Y3UDRZ2WOCPHDRTQRDGHFA5CNFSM4H2ZGSNKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECSPXTI#issuecomment-547683277>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFJPEZR3FK5EHVIP6FH2K3QRDGHFANCNFSM4H2ZGSNA> .

[parente]

@Caaddss I see a request from you now to join the Spanish translation team. Once I received that request, I was able to add your username to the Portuguese (BR) team instead. Please correct me if that was the wrong thing to do. Otherwise, welcome!

[Caaddss]

@parente Oh, it's to Portuguese(BR) team... It's correct!!! Thanks!!! I receveid the notification now..Thank you some much!!!

[parente]

Related: If anyone would like to volunteer to serve as "coordinator" for their translation team, I'd greatly appreciate it. The coordinator can invite new translators, approve/deny requests to join the translation team, etc. This would remove me as the single-point of contact for joining one of the existing translation teams at least.

Details are here: https://docs.transifex.com/teams/understanding-user-roles#language-coordinators

Two things we'd want to consider:

1. How to make it clear that the Jupyter Code of Conduct to Transifex like it does to GitHub and other venues of Jupyter collaboration.
2. How to vet coordinators. Maybe as long as the person has submitted at least one translation that we've merged here on GitHub it's enough? Or someone can vouch for them? I'd be interested in folks thoughts here (@willingc yours in particular if you have a few minutes to spare).

[Caaddss]

@parente I can be to the Portuguese(BR) team...

[leportella]

wow... this is awesome! was offline for quite some time, but I am back hopefully! @parente count me in on helping this get translated! Just made the request

[parente]

@Caaddss I've made you a coordinator for the Portuguese team. You should be able to grant and deny access to other people who want to join that team.

@leportella Welcome back! I made you a coordinator for the PT_BR team as well since you were the one who suggested kickstarting translation at the Jupyter meeting back in March.

I think we should close out this issue soon as it's probably not the best place to coordinate the work on translations. Maybe to complete this issue we can:

1. Find a place for continued discussion about translation efforts across Jupyter. I would vote for a new "Translation" category on https://discourse.jupyter.org/ as the place for open-ended discussion about translation of docs and software. What do others think? @choldgraf would that make sense to you?
2. Add a section to the documentation about how people can help out with translations. There's a brief section in the jupyter/docker-stacks project where we piloted Transifex: https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/translations.html. Maybe we can adopt and extend that here?

[choldgraf]

wohooo! welcome back @leportella :-)

[liliancor]

Thank you @parente . Happy to help out. Thank you @Caaddss for being the coordinator for the Portuguese-BR team.

[parente]

@leportella @Caaddss Pull requests have started to arrive with pt_br translations from Transifex. ❤️ https://github.com/jupyter/jupyter/pulls

Do you have any thoughts on where review of the translations should happen? If the review happens on GitHub, any changes made directly to the translations in the pull request will need to be copied back to Transifex so that the next time a change is made, there isn't a regression.

I know Transifex has a translation review tool too. If we turn on the review required option, translations won't show up as pull requests here on GitHub until a review of them has been completed on Transifex.

[Caaddss]

@parente I think the most ideal would be to enable the option in Transifex, so there are no regressions

if we keep the review just here on Github, I think it's harder to keep organized, not forgetting to copy back

[parente]

@Caaddss I've updated the settings for translations in Transifex so that translations are only delivered to GitHub after they're 100% reviewed.

A language coordinator (currently you and @leportella) or someone with reviewer permissions (you can grant them for your language team here https://www.transifex.com/project-jupyter/teams/100899/pt_BR/) can perform reviews.