GH-149 A basic multilingual documentation structure has been created

[VladimirLevadnij]

Fixes #149

[Naros]

Hi @VladimirLevadnij great work so far, I left a few comments.

[Naros]

So I don't care for how this is rendered, so lets take a step back and lets break the playbook.yml into two separate files, playbook_en.yml and playbook_ru.yml.

For playbook_en.yml there will be a single content source defined as follows:

context:
  sources:
    - url: https://github.com/Vahera/godot-orchestrator.git
      branches:
        - 'main'
      start_page: docs/en

Then for playbook_ru.yml:

context:
  sources:
    - url: https://github.com/Vahera/godot-orchestrator.git
      branches:
        - 'main'
      start_page: docs/ru

What we'll then do is use a different output directory for each playbook:

In playbook_en.yml:

output:
  dir: ./docs-build/en

and for playbook_ru.yml:

output:
  dir: ./docs-build/ru

This will allow for nice URLs:
https://vahera.com/docs/en/orchestrator/2.0.0/overview.html
https://vahera.com/docs/ru/orchestrator/2.0.0/overview.html

We'll modify the custom template UI layout with a drop-down widget so that the brand supports switching between the two languages and this avoids tainting component and project names for future expansion.

[Naros]

This means we'll need to run Antora n times, once for each language, but I think that's a worthy trade-off to avoid injecting something into Antora that it isn't currently designed to support. I know Dan, the project lead on Antora, so I'll reach out and find out what his expected lead time is on this multi-lingual feature.

[Naros]

@VladimirLevadnij let me know if you have any questions on my feedback.

[VladimirLevadnij]

@Naros I made the changes you wrote about. But, except for one case. You suggested changing start_page: en::overview.adoc to start_page: overview.adoc in the playbook.yml file (which is now divided into two files playbook_en.yml and playbook_ru.yml), but I got an error with this change "Missing component name in start page for site: overview.adoc", so I made this line as it was originally start_page: orchestrator::overview.adoc.

In this version, as I see it, everything works. I was able to create local documentation in English and documentation in Russian (the documentation is not translated yet).

All new commits are already in this pull request.

[Naros]

This looks good, so is anyone on your team going to translate the /ru/** files to Russian?

[VladimirLevadnij]

This looks good, so is anyone on your team going to translate the /ru/** files to Russian?

Yes, after you accept this pull request and the new documentation structure gets into the main branch, Denis will begin to gradually translate the documentation and send new pull requests with changes for this issue #150

[VladimirLevadnij]

@Naros I added a notification to the documentation in Russian in the overview.adoc file:

Обратите, пожалуйста, внимание, что основная документация Orchestrator написана на https://vahera.com/docs/en/[английском языке]. Документация Orchestrator на русском языке может быть не полностью переведена с английского языка, а также учитывайте, что документация по Orchestrator регулярно обновляется, и актуализация документации на русском языке занимает время. Если вы хотите получить всегда самую актуальную документацию, используйте, пожалуйста, документацию на https://vahera.com/docs/en/[английском языке].

In English it would sound something like this:

Please note that the main Orchestrator documentation is written in English. Orchestrator documentation in Russian may not be fully translated from English, and please note that Orchestrator documentation is regularly updated and Russian documentation may take time to update. If you want to always receive the most up-to-date documentation, please use the documentation in English.

Now users are notified that documentation in Russian may not be fully translated and therefore documentation in its current form can be created in order to begin translating it into Russian on each page separately :-)