training docs + images translated in IT (italian)

[childotg]

I kept the same exact structure and tried to fit 100% of meaning with the translation. I left some original words where here in Italy is better to us them as they are (i.e. "overhead"). For the folder structure, I've just created an "it" subfolder waiting to rearrange them according to the web framework or design requirements

[nomed]

that's great !!!

Please merge asap :)

[holanita]

@childotg @nomed hi and thanks for contributing to our project. please allow us time to review your contribution. as mentioned to @childotg via email earlier, we were not planning to add translations. but we are happy to look at this as soon as our capacity allows. @greenhsu123 pls review on a high level asap. thank you!

[greenhsu123]

This is great to see :) Thank you so much @childotg!!

@holanita - could you please add this as an item for discussion at our meeting tomorrow? Specifically, on the review and validation process for non-English contributions? Could you also ping the foundation's web developer to see how he would like to manage different language content, so we are consistent with the rest of the foundation's projects?

[holanita]

To be discussed tomorrow for sure. I think we can only proceed when our capacity allows which is currently very limited.

[jawache]

This looks amazing thanks for your input @childotg!

@greenhsu123 and @holanita - the thing to consider here is ongoing maintenance, if we start accepting translations then what's our process for updates in the future? For content that doesn't update often (e.g. a blog article) I don't think this is a problem but for content that is going to evolve like this training we should have a process for accepting translations.

Questions to ask:

• How do we make sure the translation is accurate? e.g. for the blog translations each translation was verified by another person.
• How do we handle translations when the main (english) content updates?
  • A) One option is to make sure every change is mirrored to every language we translate to (huge commitment, who's going to do the translations esp. when they all need to be done by a certain timeframe)
  • B) Another option is to make it clear the English version is the main one and the only one we support and ensure is up to date. The other translations we can mark as "community translations" and indicate they might not be accurate and up to date with the latest English version.
  • C) Or we could make it all very explicit and version all the content and then the translations are linked to versions? So the English one latest version could be 1.02 but the Italian one lags behind at 1.01 until someone comes along and mirrors the change. We'd have to clearly signal on the content that you reading a translated version of the training and the translated version is behind the English version which is the latest.

I've had the same problem with principles.green, how to handle translations on open source content without having the translated content go out of date?

Microsoft translates every word in their online docs to I think 40+ languages, every change I would make would kick off this huge engine which included sending my change to a range of humans that would translate it and then check that change back into GH.

The pattern we choose here should probably be the pattern we employ across all our projects.

[childotg]

@jawache Thank you for considering this. I'm adding my comments despite not explicitly asked: I think a good way to start can be the combination of points 2 and 3. I mean, the localized content can be marked as "community" AND we can setup a versioning in the MDs with some sort of action triggered in case of languages left behind.
For the accuracy, I don't have practical suggestions unfortunately.

[jawache]

Thanks @childotg

2 + 3 would be ideal, docusaurus does have a versioning feature - I'm not 100% how it interacts with translations however, https://docusaurus.io/docs/versioning

Would you mind trying it out, I presume you have this all checked our locally?

Also let me ask our web dev @osamajandali about the disclaimer, @osamajandali would it be possible to show a disclaimer banner, like the one of the top of this page: https://sci-data.greensoftware.foundation/ - for just some of the pages for a docusaurus website? Like maybe if it was a flag in the front matter. Or something more complex so the front matter for translates content has to have the version number of the english content it was translated against and then shows the banner if there is a mismatch?

[childotg]

In the 32b6541 commit I proposed the i18n implementation following standard rules plus docusaurus guidelines, to be then compliant to the versioning framework. In details:

• The build process now builds / and /it
• In the main website (en) there's a dropdown to select locale (configured in docusaurus.config.js)
• Images location had to be changed to support localization and future version wrapping (tested and consistent)
• Some deep links in the glossary have been made relative
  IMO this can be the preliminary, production-ready and translated version in order to then create the "first" version (I presume 1.0.0)
  What do you think about it @jawache.
  Also tagging @osamajandali since I've modified some of the project structure ("docs/images" folder mainly)

[jawache]

That's wonderful thanks @childotg!

Ok so @greenhsu123 if you're comfortable with the below approach so am I:

• I'll find another human to verify the content, checking but I think one of our staff is Italian.
• versioning the content.
• adding a "community translation with limited support" type banner to all translated content regardless of version.
• Some sort of logic to check which english version the translated content has been created against and then adding to the banner information about it not being upto date with the latest version...

[childotg]

@jawache I can do the versioning as well if it's okay for you. I've just made an intro commit to prepare things. If everything's alright with the approach, you can just enroll the content checker and the disclaimer and I think about the versioning!

[greenhsu123]

I am happy with the combination of 2 and 3. @childotg, thanks again for such great work! And let us know when you have a working version of the versioning, and I will check them out locally then!

[jawache]

Thats great, @zanete can you make sure to cover this in the weekly web meeting with Osama?

[childotg]

Dear @jawache @holanita in this commit 559a1cf is also versioned as v1.0.0.
I tested and it's ok. I'm just reminding that, as per the Docusaurus Versioning guideline the most-supported use case is:

• The published version is the latest version "frozen" (the v1.0.0 now) while in the "docs" folder we can work on the next version which will not be published until a "versioning" operation:
  yarn docusaurus docs:version 1.1.0

As a suggestion, since now the structure has changed a bit due to versioning, changing now the main branch docs should be postponed to the merge, to avoid a complex merge

[jawache]

Hey @osamajandali and @zanete, can you acknowledge receipt of this?

[osamajandali]

Hey, @jawache sorry for the late response.
Thanks, @childotg, for all of this great work.
@jawache answering the question of having a dynamic banner of top, I'd say that docusaurus library doesn't provide such a thing, and I have to hack it in a way that may break things in the future, besides that, in docusaurus accessing frontmatter from components is not as easy as other frameworks as you need to eject many components in order to pass the data down to where you want to display it.

There is a better way that I think is a best practice, to have a banner that says "Unreleased" you can see it on docusaurus main website, but this solution is tide to a version not per page. So for example you can have a similar banner that says that the Italian version is unreleased yet. I see that @childotg is implementing the versioning so then I recommend that we go in with this banner.

To read more about versioning configuration from here

Let me know what direction you want to go, and @childotg if you need any help implementing the versioning, please let me know.

[childotg]

Thanks @osamajandali for the clarification. By my side the versioning is implemented and ready to merge!

[zanete]

@jawache let us know whether you'd like @osamajandali

• to add this type of banner or
• to try and implement the dynamic banner by hacking stuff with high risk of breaking the side?
• to do nothing

cc @childotg @greenhsu123

[jawache]

The text does need to be more specific regarding the nature of the content and the support level, e.g. the text should read something like "This is a community translation with limited support". Is that possible with the proposed approach? @osamajandali / @zanete

[childotg]

@osamajandali @jawache we can even put the disclaimer on every translated page. Scrappy but effective.

[jawache]

Oh true actually, just put the text on there with an admonition.

"This translation is a community translation, it has limited support and might not be up to date with the latest version in English"

We should put somewhere the version of the English version this translation is made against so in the future we can compare and see what commits need to be mirrored to this version to match. Either in the disclaimer about or in front matter, i'm very open to suggestions!

[childotg]

"This translation is a community translation, it has limited support and might not be up to date with the latest version in English"

Done

We should put somewhere the version of the English version this translation is made against so in the future we can compare and see what commits need to be mirrored to this version to match. Either in the disclaimer about or in front matter, i'm very open to suggestions!

It is already in place with versioning, I'm pasting a screenshot. If we merge (those changes with the versioning already in place were not so clean) we can then fine tune of course:

@jawache cc @osamajandali

[osamajandali]

@jawache @childotg I was going to propose the same approach @childotg do, to put manually in every page.
docusaurus has complete customization freedom for the elements (header, navbar..etc.). If something is needed on the page, it's better to have it in the markdown level (content area) rather than make a custom component.

[jawache]

Thanks ok so this makes sense.

The only question I have now is about versioning, I don't think given the approach we are discussing now, versioning the 'whole' project makes sense anymore.

Since now if we just update the English version, the version might incr. to 1.01 and then the Italian and English version both show v1.01 which gives the impression they are in sync.

• I'd propose removing the docusaurus automatic versioning and manually version (front matter?)
• Clearly put somewhere what English version the translated version was translated against (so in the future it's easier to figure out how to get this content back in sync with the English version)

Thoughts @childotg / @osamajandali ?

[osamajandali]

@jawache I believe the same, there is no need for versioning.
Mostly people implement versioning for their users to go back to old versions if they are still using it.
So if we don't want people to go back to old version and see the changes themselves no need to have versioning I believe.
cc @childotg

[zanete]

I'm removing @osamajandali as assignee from this issue as it looks like it's resolved without need of further dev?
cc @jawache ?

[childotg]

@zanete ok but didn't get if @osamajandali o @jawache would like to remove versioning before merge. I would suggest to keep versioning and see how it works in production. We can even remove it later I guess

[jawache]

Ahh sorry to ask this one last thing of you @childotg but can we remove the versioning? I think it's going to add confusion/needs more thought.

[childotg]

@jawache @zanete done

[jawache]

@greenhsu123 and @Oleg-Zhymolokhov can we discuss this in todays meeting?

[greenhsu123]

As discussed in the meeting, happy to approve! @childotg, thanks again for your contribution :)

[Jjing-Liang]

Hi
I'm Jing, a developer from China, I learned through GSF newletter that there is an Italian version, and some of us want to translate a Chinese version so that more Chinese people can learn about green software.
Can we refer to the previous process to participate in it? Or what is the process or requirements for translation participation?

[greenhsu123]

Hi @Jjing-Liang, thank you so much for reaching out about translating green software principles into Chinese! As this MR is closed, let's move this discussion to here.