How to translate CodeRoad tutorials

[moT01]

Translating a CodeRoad tutorial is easy. Just fork the repo, translate the markdown and rebuild the JSON. This would be a separate repo for each language and be a struggle to maintain.

I suppose the goal would be to have a markdown file for each language in one repo. Not sure how that would work. Might need a yaml file for each language, and then build a separate JSON for each language? And somehow pick which JSON to load when a tutorial starts.

Just opening for discussion.

[ShMcK]

After looking at how other projects translate md files:

1. TUTORIAL.{prefix}.md, eg. TUTORIAL.en.md
2. language meta property at the top of a markdown file
3. tutorial folder with language files. Eg. tutorial/en.md

I'm leaning towards #1 or #3. Thoughts?

---

The remaining steps would be to:

1. ensure multiple tutorial languages build with the cli
2. add a language change option to the app
3. deep link the language option to allow loading the language in CodeAlly

[moT01]

I'm leaning towards #1 or #3. Thoughts?

Either way would work - I think I like #1 better. So a main branch might look like this?:

TUTORIAL.en.md
TUTORIAL.es.md
coderoad.yaml
tutorial.json

So I'm guessing all the languages would be in the one JSON file. Wondering if that would ever make it too big.

Trying to think of potential issues: So if I have the above repo working, and want to add a lesson - I would probably need to add it to all the md files. It think it would probably break if not.

Basically if I need to update anything in a tutorial, I would need to update it across all languages at the same time. There's no way I could use a v1.0.1 branch for English, and a v1.0.0 branch for Spanish. Probably a good thing.

[ShMcK]

A few constraints:

• translations only in the markdown files
• no translations in the code commit or yaml. I don't think this would be a problem

I think it would be easier to generate multiple tutorial.${LANG}.json files and use the language-specific file.

SOME CONSIDERATIONS:

• a new level/step added to an English tutorial would require that the Spanish tutorial have text updated, too. This might not be reasonable if the translations take time and the build is failing.

Some solutions:

1. Don't update the other language 2 json file, users of language 2 would have to use an older version until it's updated with the missing level/step. This means language would have to be selected when starting a tutorial.
2. Populate the missing level/step with English or a computer-generated translation of the missing text.

Any other ideas?

[moT01]

no translations in the code commit or yaml. I don't think this would be a problem

It's fine to leave for now, but there is the assertion messages in there that show up. Maybe down the road we can figure out something for those.

I think it would be easier to generate multiple tutorial.${LANG}.json files and use the language-specific file.

Sounds good.

a new level/step added to an English tutorial would require that the Spanish tutorial have text updated, too. This might not be reasonable if the translations take time and the build is failing.

The translations will always take time. I think it would probably be easier to use the second solution rather than trying to have different versions for each language, but I'm not sure. Not sure if you had something in mind for having CodeRoad automatically adding machine translation or something for missing text, but it's probably easier for us to handle it on our end.

We use crowdin for most of our current translations. I believe it works like this: We keep an English file of each challenge in our repo, upload it to crowdin, automatically duplicate it there (or in a script before it gets there) for the languages we want, when they are done being translated, we download the files for all languages. On subsequent uploads, the English version is uploaded and duplicated again, any text that was previously translated will automatically be translated again. Any new text will stay in English and await translation.

We will likely want to use a similar method for these.

[moT01]

While it's on my mind - I think the ideal experience would be to allow a language to be set with an env variable, with maybe a fallback to english or something. And also include a drop down with available languages so you can change it while in the middle of or after you start a tutorial.