Adding the initial Japanese translation

[yuhattor]

I translated all the structured patterns as of 06/07/2022 into Japanese. This will be helpful to understand InnerSource practices for Japanese. I am considering the possibility of managing them under InnerSourceCommons so that Japanese users can easily find them.

The sample of the deliverables at this time can be found here.

This PR includes:

• Translated all the structured patterns into Japanese. The translation can be found under /translation/japanese
• Proofread all the document
• Linted markdown files
• Edited the ToC generation script and templates

Things to consider:

• How to provide the Japanese translation
  Posting all translations on InnerSource Patterns page is good for Japanese. However, most users will find it unpleasant to see Japanese in their search results on GitBook. Also, it is not good that there is noise in the table of contents.

Alternative ways to provide Japanese translation:

• Create a Japanese page on a different domain such as jp.patterns.innersourcecommons.org or patterns-jp.innersourcecommons.org. However, this method requires double management of GitBooks.
• Maybe we could use GitBook's feature to exclude from searches within GitBook and foldable ToCs. Did a little research and it seemed difficult. Need to do more research.

This translation could be a private project for me, but I think it would be better managed somehow under the InnerSource Commons in order to promote the InnerSource Community in Japan.

Thanks!

[yuhattor]

@spier, thank you for your contributions so far, and I am confident that InnerSource Patterns will be a treasure for Japanese companies trying to do InnerSource. I am glad to be a part of it:)

In addition to the above, @hirotakatoya pointed out about the PDF issue, this is also a problem for English readers. As it is now, if you export all the content, it will include Japanese even if you want to export only English. We would be happy if you could include this in your consideration.

The other thing I'd like to add to this issue is how the PDF feature works. I checked the prototype, but unlike the original page, the PDF functionality is not present in the menu and I could not verify it.

@hirotakatoya san, @johtani san, @kanazawazawa san,
Again, thank you all so much! I thought I proofread it well enough, but there were some corrections. I'm delighted that you took an active part in the translation!

[spier]

hello @yuhattor.

The below is all work in progress, but I already wanted to share what I have.

I did an experiment with gitbook, and here you can see the current status:
https://innersourcecommons.gitbook.io/staging/

Current Status

• English and Japanese showing "side by side" (you can toggle between English and Japanese at the top)
• gitbook UI elements are translated as explained here
• the PDF export works, as only the pages that are shown are exported i.e. only the English ones, or only the Japanese ones

How does this work

gitbook allows to group multiple spaces under a collection (that is how gitbook calls these things, see docs).

For simplicity let's just say that a Collection is like a book. Our book here is called "Staging".
A Space in our context is a language i.e. right now we have two Spaces, one called English and one called Japanese. These Spaces live inside the "Staging" Collection.

Each space can be configured separately to sync content from GitHub
That means we can sync from different branches of our repo.

Right now the syncing is set up like this:

• English - main branch on our repo
• Japanese - translation-japanese branch on our repo (I create a copy of your branch, so that I could do experiments without bothering you)

Questions

The following is stuff that I am still thinking about and working on, in order to get this into a state that we can release to https://patterns.innersourcecommons.org

• layout - can we make the language switcher look prettier? maybe show a US/Japan flag there to make it more clear this is where the user can select the language?
• translation - Japanese for "Table of Contents"
• translation - Japanese translations for all labels/titles under Appendix and Resources. also Patterns
• translation - what do we do with the Pattern template? should that be translated as well?
• translation - most patterns just have Japanese titles now but two patterns still contain English in the title. is this on purpose? e.g. this one
• translation - what to do with the mindmap? book/explore-patterns.md - I think we could keep it in English for the 1st release of this
• repo structure - where to best keep the translation files? in the current approach we keep everything on a separate branch. so we could even keep the exact same structure as on the main branch, and then replace the content of the files itself. e.g. rather than in translation/japanese/patterns/gig-marketplace.md, that pattern would stay in patterns/2-structured/gig-marketplace.md. The disadvantage of that approach is that we couldn't easily tell which patterns have been translated, and which ones haven't.
• repo structure - how to make sure that the translation-japanese branch is only used for that purpose? maybe we should point that out in the README and direct people to the main branch if they want to contribute to the English patterns etc?
• repo structure - how to give the translators a maximum of autonomy and code ownership, so that they can change the translations as they see fit and handle the approval process themselves? (could we use CODEOWNERS for that purpose?)
• maintenance - how to make sure that other workflows (link checkers etc) also run for the translations?
• layout - decide how we want the URLs to look like. Once we release this to production, the Japanese translation would live at https://patterns.innersourcecommons.org/v/japanese/ and patterns would have URLs like this https://patterns.innersourcecommons.org/v/japanese/p/30-day-warranty - we could consider to use just the language code, rather than the full name?

So much for now. Hope that I explained things well enough.

[yuhattor]

hi @spier,

That is wonderful! Thanks for putting this together in a staging environment. I understood how to put the collection together. I think it is the most understandable and desirable for all readers. Thank you.

I have a few comments on what you are working on now.

• maybe show a US/Japan flag there to make it more clear this is where the user can select the language?

  I think that's a good idea to show flags!

• translation - Japanese for "Table of Contents"
  translation - Japanese translations for all labels/titles under Appendix and Resources. also Patterns

  I will create PR for Japanese ToC

• translation - what do we do with the Pattern template? should that be translated as well?

  I think that translation of the Pattern Template may not be necessary for the initial release. The reason is that the Pattern should be proposed as a PR or an Issue in English so that community participants can understand and have a conversation about it. It might be better to keep it in English and encourage them to join the InnerSource Commons Global community conversation.

• translation - most patterns just have Japanese titles now but two patterns still contain English in the title. is this on purpose? e.g. this one

  Will unify the term "Trusted Committer" as "トラステッドコミッター".
  Regarding the "Dedicated Community Leader", we will discuss what the proper translation is in the jp-general channel, and fix it.

• translation - what to do with the mindmap? book/explore-patterns.md - I think we could keep it in English for the 1st release of this

  I agree with that

• repo structure - where to best keep the translation files? in the current approach we keep everything on a separate branch. so we could even keep the exact same structure as on the main branch, and then replace the content of the files itself. e.g. rather than in translation/japanese/patterns/gig-marketplace.md, that pattern would stay in patterns/2-structured/gig-marketplace.md. The disadvantage of that approach is that we couldn't easily tell which patterns have been translated, and which ones haven't.

  Managing in branches seems to be easier to manage in gitbook. I think that's fine. But also, I would like to mention that some contributors want to make their GitHub profiles green. It would be easier for contributors to visualize their contributions if they could work in the main branch. If we are fortunate enough to have more people participating, we may consider consolidation.

  Regarding the structure, I think either is fine. But we only translate structured patterns, so I don't think it's necessary to keep the exact same structure. So to tell which patterns have been translated, I thought the following path would be fine: translation/japanese/patterns/gig-marketplace.md

• repo structure - how to make sure that the translation-japanese branch is only used for that purpose? maybe we should point that out in the README and direct people to the main branch if they want to contribute to the English patterns etc?
  repo structure - how to give the translators a maximum of autonomy and code ownership, so that they can change the translations as they see fit and handle the approval process themselves? (could we use CODEOWNERS for that purpose?)

  It would be nice to have CODEOWNERS. Especially, it would be very easy to manage if there are permissions for books/ for toc templates, and translation/japanese/ for japanese contents.

• maintenance - how to make sure that other workflows (link checkers etc) also run for the translations?

  Can we just use the CI/CD from the main branch and apply them to the branch?

• layout - decide how we want the URLs to look like. Once we release this to production, the Japanese translation would live at https://patterns.innersourcecommons.org/v/japanese/ and patterns would have URLs like this https://patterns.innersourcecommons.org/v/japanese/p/30-day-warranty - we could consider to use just the language code, rather than the full name?

  https://patterns.innersourcecommons.org/v/jp/p/30-day-warranty is more familiar to Japanese and shorter.

I appreciate your work!

[spier]

Thanks for the extra input.

Only commenting on one topic for now:

...some contributors want to make their GitHub profiles green. It would be easier for contributors to visualize their contributions if they could work in the main branch.

This is a great point, and I did not consider this yet.

I am reading here how the contribution visualization/counting works on GitHub:

What counts as a contribution

• Committing to a repository's default branch or gh-pages branch

So you are right, if the translation commits are only kept on a separate translation branch, they would not show up in GitHub's contribution graph.

To make it possible to fully merge all files form the translation branch into main, we would have to change approach.
It might be possible with a workflow like this:

• keep all Japanese content in separate files/folders (pretty much how it is right now)
• if a branch with any changes to these translation files is merged to main, trigger a new workflow e.g. called "prepare japanese gitbook branch"
• this workflow would update the translation-japanese branch with the latest changes from main
• the workflow would also link the Japanese files to the correct places in the repo structure, so that gitbook can pick it up (either by actually copying the files like I did here, or by creating symlinks)
• once the workflow commits these changes to the translation-japanese branch, then gitbook will pick them up automatically and update the Japanese content in the book

I am sure there is something that I am forgetting here but I think it could work.

[spier]

Hmm. I did not consider that gitbook's "Edit on GitHub" feature points to files on the translation-japanese branch.

Example:

Link target:
https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/translation-japanese/translation/japanese/patterns/issue-tracker.md

Steps would then be sth like:

• user clicks on "Edit on GitHub" link in the Japenese Patterns gitbook
• user makes a small typo fix (or similar), and opens a PR against translation-japanese.
• We would then have to merge back to main (to show the contribution in the graph)
  • When doing that we would have to be careful again to not overwrite anything that shouldn't be overwritten.

There must be a way to solve this ... sounds too complicated :)

[yuhattor]

@spier

To make it possible to fully merge all files form the translation branch into main, we would have to change approach.
It might be possible with a workflow like this...

That is wonderful!! I hadn't thought of that way. I am sure that way will work very well.

There must be a way to solve this ... sounds too complicated :)

hmm...
The OSS gitbook itself seems to support custom layouts, but gitbook.com doesn't seem to.
You're right, it may need to be listed elsewhere, either in a workaround or with "Edit on GitHub" disabled.

For example, it might be possible to put an "Edit on GitHub" button or badge at the bottom of the docs, although I don't think that's ideal. It's a lot of work to manually manage and edit links, but the directory structure doesn't change that much.

[spier]

Tiny intermediate improvement:
I was able to replace japanese with jp in the URL. So the new Staging URL of the Japanese translation is: https://innersourcecommons.gitbook.io/staging/v/jp/

[yuhattor]

@spier
Thank you:) "jp" is simpler and better!

I worked on unifying the English expressions into Japanese and adding the names of Japanese reviewers to the document

[spier]

I took all the latest JP translations from this branch and published them on Staging:
https://innersourcecommons.gitbook.io/staging/v/jp/

This is published from branch/PR #426

In suggest that we now focus on what is essential for the first public release of the Japanese translation.
Once we have released it, we can still fix bugs and fine-tune the process in further iterations.

Status

• ❌ layout - can we make the language switcher look prettier? maybe show a US/Japan flag there to make it more clear this is where the user can select the language? => gitbook does not support this it seems. so let's keep the language switcher as pure text
• ✅ translation - Japanese for "Table of Contents"
• ✅ translation - Japanese translations for all labels/titles under Appendix and Resources. also Patterns
• ✅ translation - what do we do with the Pattern template? should that be translated as well?
• ✅ translation - most patterns just have Japanese titles now but two patterns still contain English in the title. is this on purpose? e.g. this one
• ✅ maintenance - how to make sure that other workflows (link checkers etc) also run for the translations? => I got most GHA workflows to run on the Japanese content as well. Rest can happen in Future Work
• ✅ layout - decide how we want the URLs to look like. Once we release this to production, the Japanese translation would live at https://patterns.innersourcecommons.org/v/japanese/ and patterns would have URLs like this https://patterns.innersourcecommons.org/v/japanese/p/30-day-warranty - we could consider to use just the language code, rather than the full name? => we went for https://patterns.innersourcecommons.org/v/jp/
• ✅ the current branch for the JP translation translation-japense is a bit long. how about translation-jp (or even trans-jp or book-jp) => I changed this to book-jp
• ✅ repo structure - where to best keep the translation files? in the current approach we keep everything on a separate branch. so we could even keep the exact same structure as on the main branch, and then replace the content of the files itself. e.g. rather than in translation/japanese/patterns/gig-marketplace.md, that pattern would stay in patterns/2-structured/gig-marketplace.md. The disadvantage of that approach is that we couldn't easily tell which patterns have been translated, and which ones haven't. => To allow for contributors to have the translation work show up in their public GitHub profile, we opted to merging all changes into main first, and then using the book-jp branch to publish the book
• ✅ repo structure - how to make sure that the book-jp branch is only used for that purpose? maybe we should point that out in the README and direct people to the main branch if they want to contribute to the English patterns etc? => we have documented the current approach in book/README.md. More detail can be provided via documentation of the translation process itself (see below)
• ✅ empowering the translators - how to give the translators a maximum of autonomy and code ownership, so that they can change the translations as they see fit and handle the approval process themselves? (could we use CODEOWNERS for that purpose?) => we are onboarding Yuki Hattori as a trusted committer. We can add more people as we see fit once the book is live.

New Questions

• ✅ some anchor links are broken - e.g. in jp/introduction.md rather than #what-is-innersource it now needs to be #innssutohaka - I fixed some in d2aaadc. Also got a fix for the reported linter issue "MD051 - Link fragments should be valid" which is annoying)
• ✅ content - the book cover has an English caption in https://innersourcecommons.gitbook.io/staging/v/jp/. this is because the image was embedded differently than in the English book. => I did a quick fix for this but the caption will be in English rather than in Japanese - see 2682d6f
• release/marketing - is there any event (e.g. presentation or similar) during which you would like to announce release the Japanese Patterns book? - our Marketing Working Group can also help with this
• docs - could we add some documentation of the current translation process? I would suggest to put this into a new file translation/README.md I mean can do the documentation of the technicalities (i.e. which branches we use etc). I would need help with how the translation is handled in terms of translating the content.

Future Work (after our first public release)

• translation - what to do with the mindmap? book/explore-patterns.md - We decided to keep it in English for the 1st release of this
• maintenance - The lint-patterns.yml GHA checks that all patterns contain the mandatory headlines as defined in .meta/pattern-template.md. This isn't essential for JP patterns, as those are translations of EN patterns anyways, for which we have confirmed that they have these mandatory headlines. We can try to adapt this GHA to also check the required headlines in JP patterns but it isn't essential
• I am suggesting to rename the folder translation/japanese to translation/jp to make it consistent with the book URL as well as the book/jp folder
• inside of translations/jp keep the same folder structure as in patterns (that way all links to other patterns and assets will stay the same). => As this would require to check all links in the JP patterns again I am pushing this to Future Work
• update book-jp branch automatically when changes to main are made. => I am opting to do this manually for now, as it does not require more than merging main into book-jp. In the future we can automate this, maybe with this action to create a PR and this one to auto-merge. or better to merge without a PR?
• content - the captions of most images are still in English e.g. see this => I suspect his is fine for the first release?
• idea - translate the book cover itself to Japanese too? (I do have the source files, so if somebody helps me with the translations then we can do this) => this does not seem essential for the first release, so I am suggesting to push it to Future Work?

[yuhattor]

@spier
Thanks for the great work:)

release/marketing - is there any event (e.g. presentation or similar) during which you would like to announce release the Japanese Patterns book? - our Marketing Working Group can also help with this

Regarding the event, we are holding the very first Japan event in August or September. It should be online. So an official announcement there would be much appreciated! I will let you know when details are finalized.

docs - could we add some documentation of the current translation process? I would suggest to put this into a new file translation/README.md I mean can do the documentation of the technicalities (i.e. which branches we use etc). I would need help with how the translation is handled in terms of translating the content.

Sure, I will create the documentation and send a PR to the translation-japanese branch👍

[spier]

Regarding the event, we are holding the very first Japan event in August or September. It should be online. So an official announcement there would be much appreciated! I will let you know when details are finalized.

Perfect. We should have the JP book live in 1-2 weeks I think.
So then it can definitely be presented at that event in August/September.

Sure, I will create the documentation and send a PR to the translation-japanese branch👍

Actually if you could send the PR to the book-jp branch that would better.
I went back and forth about the branch name but eventually landed at this.

I am slowly starting to confuse myself with all these different branches so it is about time we wrap it up and merge it all :)

[yuhattor]

I got it:) I will send PR to the book-jp

[spier]

I am doing some further work in preparation for go-live of the JP Patterns gitbook:

• moved all "Future Work" listed above into issue Japanese Patterns Book - Ideas for further improvement #430 so that we don't forget about it.
• closing this PR here. All content from this PR/branch is part of gitbook integration for Japanese Translation v2 #426 from where we will merge it into main.

We can continue using this PR here for general comments though, as it contains the full conversation history.

[yuhattor]

Thanks!!!

[spier]

To close this thread, the Japanese translation of this book is now live here:
https://patterns.innersourcecommons.org/v/jp/

Thanks a lot to all of you!

You helped the patterns working group a lot, not only by creating the translation itself but also by motivating us to create the required infrastructure to publish different language versions of the book. This will make further translations of our book in the future so much easier.

The InnerSource Community in Japan will rock, I can already tell 🎸 🚀