Localization

[drskullster]

Hi there,

French PP is working on translating all content from the academy. Browsing this repo I see that you're using Docusaurus, and it looks like localization is pretty much built in.

Is there any plan yet ?

As I see it, it's a 3-step process:

1. Make the project localizable
2. Create documentation (a how-to ?) on how to use github to contribute to this repo
3. Translate

What do you think ?

[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!

[drskullster]

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

[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

[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)

[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 ?

[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