Translation and Internationalization capabilities

[xeruf]

I want to have a hyperbook with both english and german pages, are such capabilities planned?
I guess this can already be done by using different subpaths, but an option to switch language/link between them would be handy.
This could similarly be utilised for hosting documentation in/for different versions.

I am thinking about a setting that adds a dropdown in the top right, where you could select the top-level folder to display from - e.g. if your build has a hierarchy of book/{de,en}/projects.md and the user is on en/projects, they can switch from en to de easily via that.

[mikebarkmin]

I thought about this recently for adding translations to the documention. I almost had a solution, but then struggled to integrate the glossary and also links to.

Here is what I came up with and what the problem is.

First Solution and Problems

I have implemented the i18n solution with this gatsby plugin uses as well https://github.com/angeloocana/gatsby-plugin-i18n. Meaning by just appending a locale the file would be recognized as translated.

documentation.md
documentation.de.md

The same was true for the glossary.

Now to the problems:

1. First, should a user be able to link to an english page from say a german page? How would be link look like? I wanted to keep it clean and wanted to not add the locale to the link. So a user just has to write . If this link was click from a de page it would like to /de/documentation and from an english page, which in this case is the default, to /documentation. The same is true for the glossary. But then I wondered if one would like to link from a german page to an english page and vice versa.

2. What should happen if a page is not translated. Should the content of the let say english page be shown or should this page be ignored. This could result in different navigation, for example the english version could have 20 entries, whereas the german version only has 5 entries, because only 5 page were translated.

Alternative Solution

The alternative solution would be to define in the hyperbook.json links to translations, for example:

"translations": {
   "de": "https://hyperbook.openpatch.de",
   "en": "https://hyperbook.openpatch.com
}

or

"translations": {
   "de": "https://hyperbook.openpatch.org/de",
   "en": "https://hyperbook.openpatch.org/en"
}

You would then only see a link in the top right-hand corner showing a world icon for switching between both versions. You would set up two hyperbooks one for en and one for de. This could be done in a monorepo or in seperate ones.

[mikebarkmin]

I pushed my current state, if someone is interested: https://github.com/openpatch/hyperbook/tree/i18n

Here is a preview deployment: https://hyperbook-git-i18n-openpatch.vercel.app/

Currently, there is no UI for switching the language, but you can use this url: https://hyperbook-git-i18n-openpatch.vercel.app/de

[mikebarkmin]

Progress is now tracked on this branch https://github.com/openpatch/hyperbook/tree/translation

[mikebarkmin]

Custom Links (see #363) are a poor man's solution for the translation problem, but this will do for now. I will keep the translation branch for reference, if anybody wants to keep working on it.