[RU Translation] Русский перевод документации #254
maxkatz6
announced in
Announcements
Replies: 1 comment 1 reply
-
|
@rabbitism if you wish, we can post a similar discussion for the Chinese translation. Feel free to reach us. |
Beta Was this translation helpful? Give feedback.
1 reply
-
|
Fyi we are busy preparing .net conf China this weekend. I will work on this next week. |
Beta Was this translation helpful? Give feedback.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
English version
Note: The English version is machine-translated and might be outdated. Sorry about that.
Documentation Translation in Progress
The first PR has already been merged, and the initial infrastructure is ready.
In this discussion, I will try to keep the rules for translating pages up to date and explain how we coordinate between them. If you have any comments or suggestions, please write them below in the comments.
Who Can Translate? Who Reviews the Translation?
Documentation translation is open to everyone. However, the final decision on accepting the translation lies with the project maintainers. At the same time, we welcome initiatives to review translations from other contributors. It's essential to remember that not everyone has professional translation experience. Treat everyone with respect and try to help rather than offend and demotivate others.
Translation Terminology Rules
We strive to preserve the original technical terminology. For example, terms like "Binding," "Control," or "Button" should not be translated. There are several reasons for this:
However, you can indicate a literal translation in the text where you deem it necessary. For example,
Data Binding (рус: Привязка Данных).If someone has translated these terms on other pages before you, try to adhere to the same translation.
Translation Process
[WIP] [RU] Translation of Types of Control. Alternatively, you can create a PR as a Draft PR instead of using [WIP].Optionally, but preferably, if you can clone the repository locally and check all changes on your machine before finalizing your translation. Build instructions can be found in the project README. You can also find other useful information there.
If you plan to make small changes that do not require creating a PR in advance and can be completed quickly, you can edit pages directly through GitHub using the "Edit this file" feature:
Important: If you start translating directly through GitHub, be careful. Someone else may start translating the same page without seeing that you started first, as no PR was created in advance.
How Translation Works in Docusaurus?
Docusaurus is the documentation engine used in Avalonia. For each new language, the entire page directory is duplicated. The documentation is also duplicated for each major version - 11.0 (the current version) and 0.10. Because of this, there is a situation where some pages are translated, and some remain in the original language. Also, certain pages have to be translated twice - for the old and new versions. At the moment, we have no task to translate 0.10 pages. However, if possible, if the content is the same, it is desirable to update both versions.
Russian pages are located in the following folders:
All images are reused between all versions and languages. This allows us to save space in the repository and simplifies its maintenance. However, it complicates the translation process.
IMPORTANT: Whenever possible, avoid translating images. If you believe that certain images should still be replaced with a translated version (e.g., IDE menu screenshots), all images should be in subfolders of https://github.com/AvaloniaUI/avalonia-docs/tree/main/static/img. Leave the new image next to the original, changing the extension to ".ru.png".
Начался перевод документации на русский язык
Первый PR уже вмержен, и начальная инфраструктура готова.
В этой дискуссии я постараюсь держать актуальными правила, по которым мы переводим страницы, и объяснить, как мы согласовываем свои действия. Если у вас есть любые замечания или пожелания, пишите ниже в комментариях.
Корневая папка страниц, которые нужно переводить: https://github.com/AvaloniaUI/avalonia-docs/tree/main/i18n/ru/docusaurus-plugin-content-docs/current (более детально - ниже).
Русская страница документации: https://docs.avaloniaui.net/ru/docs/welcome.
Кто может переводить? Кто проверяет перевод?
Перевод документации открыт для каждого. Однако финальное решение о принятии перевода принимается мейнтейнерами проекта. В то же время мы приветствуем инициативы по проверке переводов других участников. Важно помнить, что не все обладают профессиональным опытом перевода. Нужно относиться к каждому с уважением и пытаться помочь, а не оскорблять и убивать мотивацию других людей.
Правила перевода терминологии
Старайтесь сохранять оригинальную техническую терминологию. Например, термины типа "Binding," "Control" или "Button" не стоит переводить. Это объясняется несколькими причинами:
Тем не менее, можно использовать буквальный перевод в тексте, где вы посчитаете нужным. Например,
Data Binding (рус: Привязка Данных).Если кто-то ранее переводил эти же термины на других страницах, старайтесь придерживаться того же перевода.
Процесс перевода
[WIP] [RU] Перевод Types of Control. Альтернативно, вместо [WIP] вы можете создать PR как Draft PR.Опционально, но желательно, если вы можете склонировать репозиторий локально и проверять все изменения на своей машине перед финализацией своего перевода. Инструкции по сборке можно найти в README проекта. Там также вы можете найти другую полезную информацию.
Если вы планируете внести небольшие изменения, которые не требуют создания PR заранее и могут быть завершены быстро, то можете редактировать страницы через GitHub напрямую с функцией "Edit this file":
Важно: если вы начали перевод через GitHub напрямую, будьте осторожны. Кто-то другой может начать перевод этой же страницы, не видя, что вы начали первым, так как PR не был создан заранее.
Как работает перевод в Docusaurus?
Docusaurus - это движок документации, который используется в Avalonia. Для каждого нового языка вся директория страниц дублируется полностью. Документация также дублируется для каждой мажорной версии - 11.0 (текущая версия) и 0.10. Из-за этого возникает ситуация, когда часть страниц переведена, а часть остается на оригинальном языке. Также определенные страницы приходится переводить дважды - для старой и новой версии. На данный момент у нас нет задачи по переводу страниц 0.10. Однако при возможности, если содержимое одинаковое, желательно обновлять обе версии.
Русские страницы находятся в следующих папках:
Все изображения переиспользуются между всеми версиями и всеми языками. Это позволяет нам экономить место в репозитории и упрощает его обслуживание. Тем не менее, это усложняет процесс перевода.
ВАЖНО: по возможности избегайте перевода изображений. Если вы считаете, что определенные изображения все же стоит заменить на переведенный вариант (например, скриншоты меню IDE), то все изображения должны лежать в подпапках https://github.com/AvaloniaUI/avalonia-docs/tree/main/static/img. Оставляйте новое изображение рядом с оригинальным, меняя расширение на ".ru.png".
Остальные технические ньюансы
В Docusaurus все страницы основаны на смеси Markdown языка разметки и ReactJS элементов. Но последние у нас мало используются, и как пример - Tabs реакт компонент. Это пугать не должно, но будьте осторожны с машинным переводом, который может задеть лишнее.
Так же многие страницы содержат заголовок в стиле:
В этих заголовках нужно переводить только
title.В тексте вы можете так же найти вставки HTML кода для таблиц вместо Markdown таблиц. Это так же поддерживается, и менять не обязательно.
Beta Was this translation helpful? Give feedback.
All reactions