Support internationalization about training-kit

[matthewmccullough]

I love the strategy and planning for how to best go about this. Any past experience, folder structure, or strategic advice, @dice?

[dice]

I definitely think it would be worth our time to create a glossary for key words (Pull Request) in different languages. We do have one to some extent for English already (Pull Request).

[afeld]

The GitHub Glossary (in English) is probably a good place to start.

[afeld]

Also, googling brought up some information about doing i18n in Jekyll:

https://www.google.com/search?q=jekyll+i18n

[hissy]

It seems already exists a project translating official git manual:
https://github.com/yasuaki/git-doc-ja

I'm interested in translating slides on teaching.github.com, because I think that is the best document for git and github beginner.

[kamon]

I also like this proposal. Though I don't know about the technical aspects of i18n with Jekyll, I guess we need some mechanism that eases the management of the structure (the naming of the text files, the URLs, the TOC, etc.)
+1 to start with the glossary, and also we need a guiding document for interested translators.

[dice]

Just to be clear, the glossary would be for translators (though it should be open to the public). It would not be a translations of all the meanings, but a guide to ensure consistency in vocabulary.

For example:
Should Pull Request be:

• プルリクエスト
• プル・リクエスト
• プル　リクエスト

[jordanmccullough]

Thank you all for your replies. Feedback on solutions to keep multi-language versions of the documents simple to maintain is very important to me.

I will be updating the README.md very soon with an initial strategy and will also update everyone here when this occurs.

[kamon]

I started looking into this... I guess if the files are copied to an ISO named subfolder for each targeted language (for each big part of the training kit, e.g. "slides"), it should work out and keep things simple to maintain. The documents will keep their filenames (no change), and the translators will change only non-neutral fields, such as Title, Description, Chapter... and the actual content.

Looking forward to the update on the strategy to start with.

[jordanmccullough]

If anyone is interested in working on the Git Cheat Sheet translation, all of the PDF material for the v1.1 release is now available in Markdown. This Markdown file will be the authoritative source custom designed layouts/PDF content.

https://github.com/github/training-kit/blob/1ac4dac01b0e0791f601795fed53a5e033a38701/downloads/github-git-cheat-sheet.md

This should simplify the editing process by providing pure text content rather than working against the PDF.

[fadamiao]

@jordanmccullough I am interested to translate the Cheat Sheet to Brazilian Portuguese. After finish the translation, where is the appropriate place to store the file? In the downloads folder in a folder with ISO notation? (something like pt_BR)

[kamon]

+1. Looking into the fr one. Just need the instruction for how to commit the translated versions.

[matthewmccullough]

Hey folks. @jordanmccullough is out of office for about a week and I'm helping work on the training kit in the meanwhile. I'm super excited about your help and also about all these devs we can help with translated parts of this kit. I have a game plan to run by you before I set up the pull request to bring in the subfolders to translate:

1. It seems like a good practice, and to not get ahead of ourselves, is to just use a ISO 639-1 language code, and not a region code when first starting off with translations.
2. To keep all relative links the same for translated materials as for the source english ones, I'm thinking of top level folders for slides_pt and workbooks_ja that are similar to how the ProGit book does it.
3. We might end up duplicating some graphical assets for slides from the X directory, but some will need translation, so that's to be expected.
4. Samples of translated file paths would be:
   1. Cheat Sheet
      English: https://github.com/github/training-kit/blob/master/downloads/github-git-cheat-sheet.md
      Japanese: https://github.com/github/training-kit/blob/master/downloads/github-git-cheat-sheet_ja.md
      English: https://github.com/github/training-kit/blob/master/downloads/github-git-cheat-sheet.pdf
      Japanese: https://github.com/github/training-kit/blob/master/downloads/github-git-cheat-sheet_ja.pdf
   2. Workbook
      English: https://github.com/github/training-kit/blob/master/workbooks/github-foundations.md
      Japanese: https://github.com/github/training-kit/blob/master/workbooks_ja/github-foundations.md
   3. Slides
      English: https://github.com/github/training-kit/blob/master/slides/github-foundations.md
      Japanese: https://github.com/github/training-kit/blob/master/slides_ja/github-foundations.md

Thoughts? If this looks good, I'll seed the sub-folders and we can start collaborating on translations by next week.

The biggest question I've got is whether downloads should follow the same pattern or break from it. I'm regretting the example above and now thinking this would be better:

• English: https://github.com/github/training-kit/blob/master/downloads/github-git-cheat-sheet.md
• Japanese: https://github.com/github/training-kit/blob/master/downloads_ja/github-git-cheat-sheet.md
• English: https://github.com/github/training-kit/blob/master/downloads/github-git-cheat-sheet.pdf
• Japanese: https://github.com/github/training-kit/blob/master/downloads_ja/github-git-cheat-sheet.pdf

[jordanmccullough]

@matthewmccullough I'm in favor of the folder suffix convention, such as the downloads in this pattern for the proposed languages so far:

• English (no suffice to service as "default"): /downloads
• Japanese: /downloads_ja
• Portuguese: /downloads_pt
• French: /downloads_fr

[fadamiao]

@matthewmccullough @jordanmccullough I agree with you, it's better use download_ja/github-cheat-sheet.md instead download/github-cheat-sheet_ja.md, but is not easier in maintain and organize this using a locale named folder inside the content folder? e.g. download/ja/github-cheat-sheet.md

Something similar is used by browser-diet project in their documents folder.

Independent the defined folder convention, I just have one doubt: ISO 639 don't have a specific code for Brazilian Portuguese, it's ok to use pt-br, like in ProGit, use pt or you have a different opinion?

[jordanmccullough]

@fadamiao, Good point. I'll handle the redirects once the translated work is in place and English is not the only language available.

For now, let's plan on this pattern then so the languages are isolated within each of the content types (slides, workbooks, cheat sheets). This provides us with more flexibility as various content pieces are translated as time permits by our wonderful community.

Examples

Slides

• English ("default" for now): /slides
• English (once redirects are in place): /slides/en/
• Japanese: /slides/ja/
• Portuguese: /slides/pt/
• French: /slides/fr/

Downloads

• English ("default" for now): /downloads
• English (once redirects are in place): /downloads/en/
• Japanese: /downloads/ja/
• Portuguese: /downloads/pt/
• French: /downloads/fr/

[jordanmccullough]

To get things started, I've opened this PR for the Spanish translation of the Git Cheat Sheet.

[jordanmccullough]

Git Cheat Sheet internationalization seeded folder structure and files available:

• PT #87
• JA #86
• FR #85
• ES #84

Once these Pull Requests against the Markdown are completed, I will be happy to personally see to the PDF and cheat sheet printable document layout being completed.

[leereilly]

Thanks so much @jordanmccullough!

Am I duplicating efforts (or stepping on anyones' toes) translating this via GlobalWorks? I'm happy to PRP getting the other translations done at the same time if you're interested...

[fadamiao]

@jordanmccullough 👍

[jordanmccullough]

@leereilly Thanks! We have our wonderful community members anxious to have translations, with @kamon working on the FR and @fadamiao working on the PT.

@kamon and @fadamiao: How do you feel about @leereilly's suggestion on handling the desired translations? Happy to have your contributions to the translations but would like to respect your time and effort also.

What if @leereilly proceeds with translations and we have you proof-read and verify the documents?

[kamon]

@jordanmccullough, @leereilly: In my case, I am currently 60% done with this one, but for the next ones, we could definitely coordinate. Also I was thinking: it needs a seconder to review the translation anyway.

[jordanmccullough]

@kamon Awesome, thank you so much. Looking forward to seeing this. I can definitely work on getting a second reviewer.

Your contributions are most appreciated.

[fadamiao]

@jordanmccullough @leereilly No problems in having more people translating, it's better have someone to discuss =D

The cheat sheet was translated, and I'm looking for some revision. I don't know if it's better to @leereilly start all over and compare or just revise and enhance.

[leereilly]

Thanks for helping us out @fadamiao and @kamon! ... and thanks for organizing this @jordanmccullough!

One of my colleagues needs a Spanish version translated and printed for an upcoming event, so I'll go ahead and get it translated and update #84 accordingly 🤘

[jordanmccullough]

Closing this thread as the original objectives and conversation have begun and are now underway:

• HTML lang attribute #88
• Translation for PT #87
• Translation for JA #86
• Translation for FR #85
• Translation for ES #84