Localization about academy

[drskullster]

@chrismclarke maybe also a UX/UI input for the language switcher ?

[chrismclarke]

It's taken a while, but (hopefully) you'll be happy to know from a technical side everything is setup to support PP Academy translations!

Demo: https://drive.google.com/file/d/1dbQ7-HNyqsMP_DX9ySNXgGmzujP6hys6/view

I've created an account on crowdin and gained free access under their open source projects programme. I've also included the necessary bindings for the site and uploaded a full list of text ready for translation. You can access the project at: https://crwd.in/precious-plastic-academy

All the required code is currently sitting on the translation branch of the repo. I'm not sure how people want to proceed, but in order to appear on live first there will be a manual step to populate translated files, followed by merging the code.

Let me know what you think @drskullster and @davehakkens

[chrismclarke]

Okay, a few more quick updates:

1. Crowdin is trying to migrate to a newer platform version (enteprise/workspaces) so I've migrated everything over there instead and deleted the old project. New translator signup:
   https://ONEARMY.crowdin.com/u/signup?hash=7deb0cae5ab8be88c602605d4df0b30a8

2. I fixed a bunch of config stuff so now all the files to be translated should be populated correctly.

3. I've added a default machine translation for all the existing files into french. Given the technical nature of the academy I'm guessing the translations will be pretty poor at best, but hopefully be faster than starting from scratch.

4. I've setup a github integration to automatically make PRs from the crowdin translation to the main repo on change for deploying to live (still requires manual approval, so you won't see the updates immediately)

5. I've added a demo deploy for the current translations branch so that people can see what it looks like with the translation system, available here:
   https://pp-academy-translation-demo.netlify.app/

(use the toggle to swap to french, or direct URL https://pp-academy-translation-demo.netlify.app/fr/intro)

[chrismclarke]

Hmm, it seems there's an extra approval step required (just added you to the project).
Also the sharing links are a bit rubbish, every time you create a new one it removes all old ones, here's the latest in case anyone else is trying to join:
https://ONEARMY.crowdin.com/u/signup?hash=360f9766c5a3eb20b7cc615df4c72fa216

[drskullster]

Great, thanks for the new rights !

For the invite link, maybe it's single use ? It makes sense: I clicked on it a first time while logged in then retried on a private browsing session to see it was expired. So we would have to invite people one by one, or they could use the sign up form with an extra validation step.

I sent an invite to Helene and explained how the workflow would work on the french Discord, I'll keep you posted !

[drskullster]

@mariacastiel sorry for the slow response, I added ES language to translations and invited you to Crowdin.

[drskullster]

I added joblipallose as well.

This issue will be resolved when academy pages are internationalized. I guess people who want to translate should ask in the Discord, though I realize it's not always easy to get an answer there.

[chrismclarke]

Awesome to hear you guys are already making translations, yeah would definitely be nice to include if we could find a good way to manage it.

I think you are right that from a tech side it should be pretty easy to include, my only worry would be how well we could keep translations in sync if anything were to change. Although I'd be hoping at this stage the academy is reasonably stable/complete. Perhaps @davehakkens you might have some thoughts on this?

[chrismclarke]

Just for some added info, I took a look at the docusaurus translations info and not only is it super easy to implement but they also manage all text strings and revisions using Crowdin (https://crowdin.com/) which looks like a pretty smooth system for these types of things. Usually it's a bit expensive, but they do offer a free open source license program that we could apply to.

[davehakkens]

Ok my thoughts.
Translations have often been requested and make total sense for our community. However it turned out the be quite complex to integrate in websites so we never dared to try. Specially with a constant evolving infrastructure. We are not ready for this. That said it might be good if we give it a try to see how it goes. Docusaurus (the academy) would be a good starting point since it already has the features build in.
So i would say.

1: Let's give it a try on the Academy. BUT Make very sure to those that are going to spend their time on it that they are aware it is a test, a try-out and it could be that at some point we shift platforms, it doesn't work properly, becomes to messy or whatever reason we remove it .. If they still want to be part of the test and see if we can figure out translation then go for it :)

[nicoparies]

So now how we do it practically? :) How the French community should proceed to make it happen? Download the .md files, translate them and do a pull request with the new files?

[drskullster]

OK so I forked the repo to make a test with a french localization and it was super easy to implement. I made a proof of concept, you can see it here:

https://drskullster.github.io/academy/fr/intro.html

I hacked the Footer component to display a lame language menu because I don't know Docusaurus and it's late and there are still some things to figure out (all subcategories lead to a 404) but I think it's promising !

Docusaurus

Internationalization was pretty straightforward:

• I used a Docusaurus command to generate a bunch of files
• I enabled french language in website/languages.js
• I ran npm run write-translations to generate a file with all the strings to be translated (markdown files excluded), it's in website/i18n/en.json.
• I added a language menu and changed the redirect to point to /academy/en instead of /academy (which leads to a 404 now, you would need to write a bunch of 301 redirect).
• I configured Crowdin (see beneath)

Here's the commit diff so you can see what changed compared to origin: drskullster@4e68d16

Crowdin

• I created an account and a test project on Crowdin: https://crowdin.com/translate/pp-academy-test/ (the project is public but you have to create an account to see it).
• I installed the crowdin CLI tool and configured the integration
• I ran npm run crowdin-upload to upload all files to translate (the generated json and all markdown files)
• I used the document from Hélène in the french PP discord to translate the intro page and the sidebar
• I ran npm run crowdin-download to download translations in my fork, they are all in website/translated_docs/fr/ (path is configurable)

Note: I tried to translate stuff directly in the repo but the crowdin-upload command doesn't seem to upload translations, which means it's a one-way process: content can only be translated inside crowdin, any "manual" changes would be erased at the next crowdin-download. I didn't dig in the docs though, maybe there's a way to upload translation changes. It would be cool since it would allow people to work from the repo and from crowdin.

My conclusions

As we thought, from a technical point of view internationalization in Docusaurus is a breeze. Took me 10 minutes to set it up.

For the translation part, Crowdin could be really helpful: it's easy for people to contribute (way easier than learning git and github), they can be notified when there has been changes, webhooks could be set to trigger in a discord channel,... It's not an open platform and people will have to create an account (same goes for github) but since all translations are versioned in the git repository it's not that much of a problem in my opinion.

It's optional though, everything could be translated from github with forks and PRs. But I think a service like this is key to keeping translations in sync. If you can get an open source license maybe we can give it a try for the FR translation and see how it goes ?

[chrismclarke]

Thanks for all the research @drskullster

I think next step as I see it is we apply for a crowdin account and see what they say. I can do it on behalf of onearmy or someone else can do it on behalf of preciousplastic. There's a few odd criteria which we might not fully meet, but pretty much essential if we want to do things the easier way

https://crowdin.com/page/open-source-project-setup-request

1. You have created a translation project in Crowdin.
2. The project is licensed under an approved license from an open-source initiative.
3. Your project's source code is publicly available for download.
4. You do not have any commercial products related to the open-source project you are requesting a license for.
5. You are the project lead.
6. You have been working on your open-source project for at least three months.
7. You have an active community of collaborators.
8. You keep the "News" section of your website up to date.
9. You release updated builds on a regular basis.

I'm guessing PP fails for commercial products (if bazaar counts), and OA fails for a News section, but maybe they won't be too rigid?

What do you think @davehakkens?

[drskullster]

Hi there !

Any news on this ? We're progressing in the french translations and we'll need a home for them at some point. If it could be the community platform that would be awesome 😄

[chrismclarke]

Sorry for the slow response, we don't have any full-time people working on the platform at the moment so priority has mostly been bug fixes, but I suggest we try and put this on the roadmap for next month when we plan for a dev sprint.

From what I understand this would need various inputs, none of which should be too huge:
[edit - include language switcher]

• admin: try to get registered on crowdin
• academy: add language switcher component and function
• docusaurus: make a pr to implement the system as metioned above drskullster/academy@4e68d16
• translations: migrate any existing translations
• documentation: make a note for how people can edit/improve fr translations (and possibly add additional)

@davehakkens - happy for us to add this to the March release?
@drskullster - anything I've overlooked?

[davehakkens]

yes!

[chrismclarke]

Great, edited above and I've made a note on the platform March roadmap document so hopefully won't get overlooked (although no harm giving a bump in this thread if nothing has been heard by around mid-march).

For interest, countries of site users for the past week

[drskullster]

That's amazing @chrismclarke !

I get an error on the Crowdin page you linked:

It seems like this invitation link is not valid. Try to request another one

I signed up with this link: https://accounts.crowdin.com/register?domain=ONEARMY

And now it seems I can access https://onearmy.crowdin.com but there's "No projects or groups yet". Any idea ?

[drskullster]

OK cool I see the project now, I just updated two strings for testing.

The new link seems to be dead as well. Maybe I can route people directly to the signup form and ask them to wait for your approval ? I feel it's pretty straightforward (maybe it's the "official" way of joining the project ?): https://accounts.crowdin.com/register?domain=ONEARMY

[chrismclarke]

Guessing they're still working some bugs out in the new system as the link was set to never expire... But I've just given you manager access so you should be able to invite people either directly via email or generate new links.

I've also updated the frequency that crowdin automates PRs to be hourly, so to view any changes on the live demo version someone just needs to accept the PR into the translations branch from the I10n_translations branch. I've sent you an invite to the repo which should give you the required permissions to do so also.

(example PR: #84)

[chrismclarke]

(side-note, last automated PR didn't seem to work quite right, removing lots of the auto-translated content. I'm not sure if this was supposed to happen or not, but in any case it's always easy to pull direct from crowdin via command-line which I've just done for the latest test translations). Should now be live.

@chrismclarke I am interested in translating PP academy to Japanese, could you add me, please?

If I need to provide my username or something like that, please let me know:)

[chrismclarke]

Sounds great @Ryoma-RecycleNaga, I just checked in on the crowdin project and it seems the account has got a bit messed up (no longer registered as open-source - a mistake on the crowdin end which has happened with another account previously). I'll get in touch with support and once fixed can send an invite

[drskullster]

@chrismclarke I took the liberty to invite @Ryoma-RecycleNaga, we just have to wait until the account is back up :)

[chrismclarke]

Great, thanks for doing that @drskullster , account is back-up so should be good moving forwards.
How are things going from the French translations side? Anything needed from me in the short/mid term?

Also @Ryoma-RecycleNaga , @drskullster , @davehakkens - I've also tried to add a bit of documentation to give an overview and help with the translation process. I know there's still a lot to figure out in terms of what we want to achieve, how best to manage, and the more technical things also but hopefully it's a start (any additions more than welcome). See here:

https://github.com/ONEARMY/academy/blob/master/contributors/Translators.md

[davehakkens]

oe wauw nice documentation start!

[mariacastiel]

OK, I would like to help with the localization, specially to have a Spanish version for all hispanoparlantes around the world, but i can help with the internationalization as well as I have some experience with crowdsourced translations.

Spanish is a language spoken in many places and most of us do not speak English. I am interested on Precious Plastic but is hard to convince my neighbours without material they will understand.

I am also interested on translating the videos, at least the academy ones. Do you think we could add the .srt files to crowdin?

I tried to join to crowdin through the invite codes offered by @chrismclarke here but they are not working. I think some changes on the 'workflow' section of crowdin will help to make it easier for translators to join.

Yes, I have opened this new account only to contribute to this project :D so my profile is empty

[mariacastiel]

I am not sure how it goes inside the crowdin project (still waiting to be let in), but one thing I would like to change already is that in the config file it seems the language code for Spanish is es-ES. I would rather have a simple es translation, because I don't think that we can have different translations for all countries where Spanish is spoken, and it will be better to have only 'standard Spanish' like in other software projects.

I guess at some point we will need to make some notes regarding different names in Spain or Mexico, but I don't think we can maintain a whole locale per each Spanish speaking country.

[mariacastiel]

@drskullster thats great! joblipallose would like to translate to Spanish as well, please add him (i dont seem to be able to invite people) also, how can we go in the spanish translation team to add more people, write about it here? it seems this ticket will become eternal!

[mariacastiel]

Nice! I am starting to translate.
Regarding access:

• I have noticed I can proofread and translate Japanese and French. I don't think I need that. I think translators should have access to their language only.
• I would like to be able to add new terms to the Spanish Glossary in crowdin. This is specially important when starting a new translation project, to generate consistency on the terms. The sooner this is done, the better.

I have submitted two pull requests related to translation:

• After going through the process of joining myself, I have updated contributors/Translators.md in the master branch to consolidate the current process to start translating. That is #101
• I have submitted another PR to the translations branch, updating the note on the readme file, and (hopefully) enabling Spanish language. It seems to enable the Español option on the menu, but I think it needs an update from crowdin translations because it leads to a 'not found' at the moment. That is #104

With @joblipallose we are contacting Spanish speakers in discord that have said they want to translate and hopefully will have a nice team of translators soon. It would be nice to be able to see our translations in https://pp-academy-translation-demo.netlify.app/ so we can spot our own mistakes and fix them, saving work to the developers and learning in the process.

What do you think, @chrismclarke ?

[mariacastiel]

I just noticed there are some content changes in academy:master that have not made it to crowdin.
This means we are translating outdated documents and it is a bit of wasted time then.

I am not sure what is the process for updating crowdin, but I have prepared this PR for the translations branch:
#105

[darigovresearch]

Is anyone still up for translating the site?

Would agree that as a lot of the English content has been updated since this was started that some bits of translation may need to be updated again (this an issue with localisation anyway). There also may be better solutions since this issue was created more than a year ago

[Martinhubz]

Hey everyone! I recently joined the french translation project, and things are looking pretty good! We're planning on having the whole v4 academy translated in french by Christmas 2022 and we must be about 50% there
It's also a good opportunity to find any errors in the original English text
One of the group members has his self hosted version of the website for his association, so they will end up as md files. So it would be a good idea to integrate our work into the official Academy, I mean give it another try!
I see quite some work has already been done thanks to @chrismclarke @mariacastiel and @drskullster, so we need to connect the existing bits
The Crowdin platform doesn't seem to be reliable from what I read in the different threads, so I guess we should stick to git
Translators could "subscribe" to the files they work, and a git hook would send them an email each time there is changes

Let me know if it could fit this in this year's timeline

[chrismclarke]

That sounds really exciting, always nice to see old issues brought back to life - Unfortunately from my side my maintainer role on the main community platform is taking up all the time I can find for the project, but let me loop in @davehakkens in case he thinks there's anyone else we can flag the issue for on our next monthly call.

[davehakkens]

Nice one @Martinhubz, but indeed like Chris mentioned at the moment we don't have the capacity to wrap up the dev work for this. I'll keep my eyes open and let you know if someone is able to take on the task. Let's see

[Martinhubz]

Yes I would have guessed translations isn't a priority. But I'm committed to integrate it in the community platform, as I have a computer science background I could figure out how to add the final pieces to the puzzle (just RTFM right?)
Quite some work has already been done, would you maybe have a checklist of items missing for localization?
What is the status of the following mirror: pp-academy-translation-demo.netlify.app, would a simple rebase bring it up to speed?

As I mentioned, for now we are working totally separately from One Army's work, but we'll have markdown files ready (for that one member hosting a french version fork of the academy), so it's a matter of finalizing the localization integration

[davehakkens]

I don't think a specific todo list exists for this, its been in the works for different periods of time by various people. I guess part of getting this done is trying to figure out what exactly needs be done. 😅
So a rebase sounds like a good start