Translation

[Street-Philosopher]

Hi I can help translate the tutorial into italian

[avivace]

Hi I can help translate the tutorial into italian

Ciao! Sarebbe fantastico.. Hai già iniziato e/o idea di dove mettere le traduzioni?

[Street-Philosopher]

Ciao! Sarebbe fantastico.. Hai già iniziato e/o idea di dove mettere le traduzioni?

Ciao! Ho provato a guardare ma non ho trovato dove metterle.
Ci sono delle parti che sono già state fatte o posso iniziare da dove voglio?

[ISSOtm]

Hi! You can start translating Part I (that should work well enough); the infrastructure needs to be set up accordingly, though. I see either the mdbook-i18n or mdTranslation crates for this purpose.

I'm thinking the latter, since it references the original text as well (more friendly to keeping track of amends in the original text that need re-translation, it seems).

It should be possible to start working on the content itself regardless.

[Coll256]

I started to translate tutorial to Russian language, thanks for putting me into the project!

[ISSOtm]

The former crate looks more lightweight than the latter. Given that someone's working on this (and #21 is about to be merged), I'll start working on i1n support.

[EDIT] Oh dear, both crates are out of date. This is gonna be fun.

[ISSOtm]

The important question is: how should updates to the base text be propagated to the translations? Consider 9f4d296, for example.

Failing a timely update (if nobody's available to translate, nobody's gonna translate), what should be done? Keep the incorrect info with some formatting notifying the reader that the translation must be updated (and then, how to convey that)? Replace the outdated block with the English text (yikes)?

[EDIT] Note: by default, the first crate would just keep the outdated translation, whereas the latter would instead display the untranslated text until updated.

[avivace]

The important question is: how should updates to the base text be propagated to the translations? Consider 9f4d296, for example.

Failing a timely update (if nobody's available to translate, nobody's gonna translate), what should be done? Keep the incorrect info with some formatting notifying the reader that the translation must be updated (and then, how to convey that)? Replace the outdated block with the English text (yikes)?

[EDIT] Note: by default, the first crate would just keep the outdated translation, whereas the latter would instead display the untranslated text until updated.

I think I would just show the outdated translation, but we can show a notice to the user in case this happens?

[ISSOtm]

How should it be shown, though?

[avivace]

How should it be shown, though?

Do you mean how we should visually present it or how would we implement the "check" for "outdate-ness"?
Also, this is out of scope in this issue, here we should focus on enabling @AlphaL64 to translate

[ISSOtm]

It's very much in scope, as it conditions the way the translation will be set up on the technical side.

This however does not block any translation efforts, as @Coll256 has already sent me translated versions of several pages (thank you very much!). I/someone else can "reformat" those into whatever we end up picking later requires.

[Street-Philosopher]

hi, sorry I have been very busy with exams and couldn't reply for a while.
I've started the translation and translated a few files, but I had a couple questions: is anyone working on Italian besides me? When I'm done with a file, what should I do with it? Send it to you? Commit it? If so, where should I put it and how should I call it?
Also I saw there are assembly examples like hello-world.asm: should I translate those as well? For example I was thinking of the comments, labels etc.

How should it be shown, though?

About that, we could have an "outdated warning" message saying that the information is outdated and we're working on a translation for the correction, that is translated in the target language and when something is outdated we place that message warning the user. This way we don't have to leave the wrong thing nor have english text of any kind in the middle of the page in another language.

[ISSOtm]

hi, sorry I have been very busy with exams and couldn't reply for a while.

No problem, take the time you need.

I've started the translation and translated a few files, but I had a couple questions: is anyone working on Italian besides me?

Not that I'm aware.

When I'm done with a file, what should I do with it? Send it to you? Commit it? If so, where should I put it and how should I call it?

Translation support hasn't been set up yet, so in the meantime I think it'd be best if you committed the translated files in a fork; I will take care of converting them to the final setup when I have confirmed it works.

Also I saw there are assembly examples like hello-world.asm: should I translate those as well? For example I was thinking of the comments, labels etc.

Good call, those guidelines will have to be recorded somewhere. I'll add a TRANSLATING.md file in the repo when the setup is finalised, but in the meantime, I'll record them in the OP.
Please do translate "meaningful" comments (essentially, what isn't ANCHOR and ANCHOR_END), but do not translate variable names, labels, etc.

How should it be shown, though?

About that, we could have an "outdated warning" message saying that the information is outdated and we're working on a translation for the correction, that is translated in the target language and when something is outdated we place that message warning the user. This way we don't have to leave the wrong thing nor have english text of any kind in the middle of the page in another language.

So it looks like "outdated" is preferred over "untranslated updated"—I'd have picked the opposite, for "loud failure" is IMO preferable to "silently incorrect", but I'd be boneheaded if I ignored my users' opinions.

My question is rather on how to convey that warning. Tooltips and margin notes are not mobile-friendly, and a certain convention (different background) cannot be reliably conveyed, as users are likely not to read the introductory page. So I don't know how to implement the warning.

[avivace]

hi, sorry I have been very busy with exams and couldn't reply for a while. I've started the translation and translated a few files, but I had a couple questions: is anyone working on Italian besides me? When I'm done with a file, what should I do with it? Send it to you? Commit it? If so, where should I put it and how should I call it? Also I saw there are assembly examples like hello-world.asm: should I translate those as well? For example I was thinking of the comments, labels etc.

How should it be shown, though?

About that, we could have an "outdated warning" message saying that the information is outdated and we're working on a translation for the correction, that is translated in the target language and when something is outdated we place that message warning the user. This way we don't have to leave the wrong thing nor have english text of any kind in the middle of the page in another language.

I would like to contribute too, working on a fork as @ISSOtm mentioned would allow me to join with reviews and more translations 😄

[Kaleidosium]

I may start translating to Indonesian once my current workload is reduced.

[Street-Philosopher]

I would like to contribute too

again, sorry if it took me so long to answer.
the fork is on my profile, this is the link:
https://github.com/Street-Philosopher/gb-asm-tutorial

i'm new to collaborating in GitHub, so idk if i have to do something before you can actually collaborate or not, let me know if i do.
the translation files are in root/translations/it. i have already added the ones i translated, but feel free to check if they're correct

[avivace]

I would like to contribute too

again, sorry if it took me so long to answer. the fork is on my profile, this is the link: https://github.com/Street-Philosopher/gb-asm-tutorial

i'm new to collaborating in GitHub, so idk if i have to do something before you can actually collaborate or not, let me know if i do. the translation files are in root/translations/it. i have already added the ones i translated, but feel free to check if they're correct

That's great! Can you try to open a Pull Request? It should show as a banner on the top of your fork

[Street-Philosopher]

Done. Will I have to do this again every time I have new files or changes to commit?

[avivace]

Done. Will I have to do this again every time I have new files or changes to commit?

Thanks, looks okay! Now that the PR is open we can move the discussions there, and any update to that branch will update the PR there, so you can keep committing to your fork