Document Automated Translation process

[nicopace]

As per @rudokemper request:

In fact, it would be great if @nicopace could answer my question (2 )by just submitting a PR to this repo with documentation about how translation works - I think a new section in the README or CONTRIBUTING would work, please use your discretion and see which one is more appropriate.

Document the birds-eye view of the actions done by the .github/workflows/translate.yml script, so users of the repository are exposed to this.

Additionally, add a README file on the directories that are automatically translated to let people know that contributions than there might be overwritten by the translation.

Cite what this process does, and the implications of it (that contributions are expected in English first, that the workflow overwrites any manual contribution in non-english languages).

[nicopace]

Before even continuing with this approach of using automated translation workflows, I analyze this from a birds-eye view.
Using automated translation models solves the bulk of translating a document. It works really well if we do the translation in an automated fashion without reviewing it, because the translation is stable (meaning, same strings are translated always the same, thanks to the translated cache produced as a byproduct of the translated effort).
But if instead having automated translations of the content you want to review the translations (and we want, to make sure we maintain a good quality documentation), then you need to update the cache with the reviewed strings too... If not, next time there is a change in the same file, the review would be overwritten.
So in some way there needs to be an additional step after the acceptance of a translation PR, that checks whether there has been a change in the machine-proposed translation, extracts the translation, updates the cache and commits the update, by applying the translation automatically and making sure that the change is the same from the cache than from the PR.
The alternative is to verify the translation JSON cache, and when this is updated, trigger the translation generation.

Based on this line of thought, I will re-read the Docusaurus i18n page as I feel I am missing something.

[nicopace]

Going through this process of reviewing the documentation made me realize that the human in the in the loop translation workflow in order to make it stable and efficient is better than using standardized tools like CrowdIn SaaS. The good thing is that now that we have translateGemma as a translation model that I can use, I can provide initial translations to the system so when we do translations in the future we can count on those initial translations ahead of time so what we end up doing is validation instead of having to translate every string and CrowdIn would manage the translation memory as well as the the stability of the translation effort.

I will explore this in this next cycle.

[nicopace]

I've filed a request for an open source crowdin account so we can have all the bells and whistles.
Will come back to this once I get a response from them.

[nicopace]

BTW This guide is really clear on what are the features CrowdIn provides in the context of Open Source projects:
https://docusaurus.io/docs/i18n/crowdin

[nicopace]

Crowdin approved our application for their license for Open Source project, so now we have it.
Will explore more how to better integrate it when I get back to this.