8000 Translating Official Documentation to Spanish · Issue #430 · jupyter/jupyter · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Translating Official Documentation to Spanish #430

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
camporeale opened this issue Jun 23, 2019 · 43 comments
Open

Translating Official Documentation to Spanish #430

camporeale opened this issue Jun 23, 2019 · 43 comments
Labels
documentation

Comments

@camporeale
Copy link

@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
Copy link
Collaborator
choldgraf commented Jun 23, 2019 •
edited
Loading

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
Copy link
Co 8000 llaborator

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
Copy link
Member
willingc commented Jun 23, 2019 •
edited
Loading

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
Copy link
Member
betatim commented Jun 24, 2019

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
Copy link
Author

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
Copy link
Member
parente commented Jun 24, 2019

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
Copy link
Member

@parente Thank you.

@parente
Copy link
Member
parente commented Jul 5, 2019

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.

@parente parente mentioned this issue Jul 5, 2019
Merged
@camporeale
Copy link
Author

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
Copy link
Member
parente commented Jul 11, 2019

@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
Copy link
Member
parente commented Jul 11, 2019

@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
Copy link
Author

@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
Copy link
Member
parente commented Jul 27, 2019

@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
Copy link
Author

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
Copy link
Member
parente commented Aug 11, 2019 •
edited
Loading

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
Copy link
Member

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

@parente
Copy link
Member
parente commented Aug 11, 2019

Thank you, @willingc.

@parente
Copy link
Member
parente commented Aug 11, 2019

Tada!

image

@willingc
Copy link
Member

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

@camporeale
Copy link
Author

Awesome!

@valerybriz
Copy link

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
Copy link
Member
parente commented Oct 3, 2019

@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
Copy link
Member
parente commented Oct 3, 2019 •
edited
Loading

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
Copy link

@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
Copy link

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
Copy link

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
Copy link
Member
parente commented Oct 29, 2019

@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
Copy link

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
Copy link
Caaddss commented Oct 29, 2019

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

Can you see my solicitation??

@parente
Copy link
Member
parente commented Oct 30, 2019

@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
Copy link
Caaddss commented Oct 30, 2019

@parente my username is Caaddss

Im try to joining but doesnt work

@Carmelo2021
Copy link
Carmelo2021 commented Oct 30, 2019 via email

@parente
Copy link
Member
parente commented Oct 30, 2019

@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
Copy link
Caaddss commented Oct 30, 2019

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

@parente
Copy link
Member
parente commented Oct 30, 2019

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
Copy link
Caaddss commented Oct 30, 2019

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

@leportella
Copy link
leportella commented Oct 30, 2019 •
edited
Loading

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
Copy link
Member
parente commented Oct 30, 2019

@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
Copy link
Collaborator

wohooo! welcome back @leportella :-)

@liliancor
Copy link

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

@parente parente mentioned this issue Nov 2, 2019
Merged
@parente
Copy link
Member
parente commented Nov 9, 2019

@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
Copy link
Caaddss commented Nov 13, 2019

@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
Copy link
Member
parente commented Nov 16, 2019

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

image

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.

This was referenced Jun 13, 2020
Closed
Merged
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
0