Open VladimirLevadnij opened 3 months ago
I plan to do this work.
@Kluskey Hello. Before starting this task, I want to know what is the reason for using Docusaurus 2.0.0-beta.21 in this project? At the moment there is a newer version in the 2.x branch and there is a new stable 3.x branch.
So it just happened historically, there was no time to update to a new version or is there some software specific to this version attached to version 2.0.0-beta.21?
If the situation is that there was no time to update previously, then I plan to update Docusaurus to the latest version in the 3.x branch. Do you agree with this?
@Kluskey Hello. Before starting this task, I want to know what is the reason for using Docusaurus 2.0.0-beta.21 in this project? At the moment there is a newer version in the 2.x branch and there is a new stable 3.x branch.
So it just happened historically, there was no time to update to a new version or is there some software specific to this version attached to version 2.0.0-beta.21?
If the situation is that there was no time to update previously, then I plan to update Docusaurus to the latest version in the 3.x branch. Do you agree with this?
Yep, just historical reasons from when we started the docs repo. Feel free to update it to 3.x and I'd be glad to review! Thanks.
To convert Docusaurus version 2 to Docusaurus version 3, I plan to use this instruction. In this Issue, as the work progresses, I will document possible difficulties and key points.
Since links to The Mirror documentation have already spread across the Internet, it is important to keep them working. Therefore, when creating internationalization functionality in Docusaurus 3, English, which is the default language, will not appear in the links.
That is, the link to the Tutorial in English will remain the same:
https://docs.themirror.space/docs/tutorial
And in Russian and other languages, the locale will be added to the link:
https://docs.themirror.space/ru/docs/tutorial
I noticed that the new Docusaurus 3 documentation uses the command:
"start": "docusaurus start"
To avoid creating an additional task, this change will be done along with this task.
I implemented multilingual documentation functionality in Docusaurus. Additional explanations:
Based on this Issue, work was done to create multilingual functionality and add a version of the documentation in Russian, BUT a complete translation of the existing documentation into Russian was NOT DONE. This work will be performed in parts on individual issues.
According to the Docusaurus structure, files prepared for the Russian version are located in mirror-docs/i18n/ru/
At the moment, there are complete translations into Russian of system entities, such as the “Next”, “Previous” buttons, and so on - these translations are provided by Docusaurus itself. If we talk about pages, only the start page has been completely translated:
And also on the Get Started
and Open-Source Code/Get Started
pages there is a notice with the text in Russian:
Please note that The Mirror's main documentation is written in English. The Mirror's Russian documentation may not be fully translated from English, and please note that The Mirror's 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.
I would like to draw your attention to the fact that some of the translation into Russian is not direct, but logical.
For example, "App Docs" is translated as "User Documentation" ("Документация пользователя"), and "Open-Source Docs" is translated as "Developer Documentation" ("Документация разработчика"). I don't know how correct names such as : “App Docs” and “Open-Source Docs”, but when directly translated into Russian, it is not clear how this documentation differs, it sounds like the first documentation will be “Closed”, and the second documentation “Open”.
Docusaurus, when performing the build, complained about some links in which the files had a file extension, for example, /docs/build/Character.mdx
As far as I could find information, it is recommended to specify links without a file extension. I did not change all the links, I only changed those links with which there were difficulties and errors.
I tested launching the project in developer mode yarn dev --locale ru
and checked the creation of the assembly yarn run build / yarn run serve
, everything worked for me locally, except point 6.
SEARCHING for new added information DOES NOT WORK. I assumed that this was NOT an error based on the information provided in the documentation https://docusaurus.io/docs/search
If I understand correctly, Algolia DocSearch is used for searching, the documentation says:
The service is free for any developer documentation or technical blog: just make sure to read the checklist and apply to the DocSearch program.
DocSearch crawls your website once a week (the schedule is configurable from the web interface) and aggregates all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API.
Based on this information, I concluded that the current search behavior is correct, that you need to upload new information to the public Internet and wait for the next indexing of this information to occur.
To make the documentation easier to use for people from different countries, it is necessary to implement the functionality of multilingual documentation in https://github.com/the-mirror-gdp/the-mirror/tree/dev/mirror-docs
Recommended instructions https://docusaurus.io/docs/i18n/tutorial
In accordance with this issue, it is necessary to create functionality for multilingual documentation, adding, in addition to English, also, for example, Russian. In the Russian language thread, the first step is to copy the documentation in English and make a notification that the documentation is being translated.
Translation into Russian and other languages will be performed on separate issues for each version of the documentation.