Russian Docs Translation / Русская Документация Sponge


#1

This is the official topic for the Russian Docs Translation.


Привет посетитель форума,

Как много проектов вы знаете, созданных для Minecraft'a, которые были переведены на русский язык? И отсутствие русскоязычной информации, по тому или иному продукту, доставляла вам неудобства. Вам приходилось пользоваться переводчиками, чтобы узнать ту или иную информацию по документации.

Так давайте же сделаем русскую документацию Sponge, и наши усилия помогут многим пользователям и начинающим разработчикам.


С чего начать?

Начать переводить можно очень просто! Для этого необходимо зарегистрироваться на сайте Crowdin, далее вступить в команду переводчиков документации Sponge, выбрать какой-либо непереведенный документ и нажать Translate now.

Для удобства можно открыть англоязычную документацию в другом окне браузера.

Если вы затрудняетесь с переводом (например из-за отсутствия опыта в переводе или программировании), то вы можете пропустить предложение или задать вопрос в данной теме. Мы рады вам помочь!


Правила

Официальные правила для всех переводчиков.

Дополнительные правила для переводчиков (Translators):

  1. Не копируйте текст из онлайн переводчиков!

  2. Названия, команды, части кода и ссылки не нуждаются в переводе.

    Пример:
    Добро пожаловать в документацию "Sponge"<http://spongepowered.org>__!

    Теперь вы можете зарегистрировать класс в CommandService

  3. Сохраняйте звездочки и их количество (* ' " --)

    Пример:
    **Table of Contents** --> **Содержание**
    Table of Contents --> Содержание



#2

Ололо, да это же тред моей мечты!


#3

Отлично! С радостью помогу с перводом.


#4

Нам необходимо выработать какие-то фундаментальные правила перевода. Чтобы не приходилось по тысячи раз переделывать за кем-то. И эти правила мы должны обсудить все вместе и принять все вместе. Но для начала надо привлечь сюда нашу тиму. Видимо здесь мы будем вести обсуждение.


#5

Кого-нибудь ставили координатором или ревьювером?


#6

Ну ты чего блин. я же тебе в личку на трансифексе отправил. двух рецензентов назначили. координатора пока нет.


#7

очень хорошее усилие. wink


#8

Я один из ревьюеров. Для нас, наверное, тоже какие-то правила нужны. Например, в комментариях предлагали: нельзя одобрять свой же перевод. Я пока ради проверки несколько одобрил (не своих).


#9

Хорошая идея! Разделим правила по группам.


#10

Кароч, котаны. У меня тут несколько предложений.
Что касается правил, вот вам несколько вариантов на рассмотрение. Я думаю, это стоящие правила.
1. Не используйте точки в заголовках и подзаголовках. - На мой взгляд это тупизм. Никто не использует точки в заголовках. Разве что заголовок состоит из нескольких предложений. Тогда имеет смысл, иначе нет. afftar4G, ты уже допустил такую ошибку. Не в переводе конечно, но всё же. "Правила" заканчиваются точкой, а это заголовок.
2. Предложение начинается с большой буквы, а остальные слова с маленькой. Исключения: термины, названия, имена и прочее. - Тут есть загвоздка. Некоторые предложения в оригинале нарушают это правило (Java Is Not Installed On Your Computer). Зачем каждое слово с большой буквы? Как бы перевод-то нормальный, то выглядит это глупо.
3. Местоимения пишутся с маленькой буквы. - Тоже не понимаю, зачем "Вы" писать с большой. Будто к царю обращение. Ну и исключение разумеется, если местоимение в начале предложения. Тут всё ясно.

P.S. afftar4G, у тебя бывают серьёзные косяки в переводе. Аккуратней. И ещё совет рецензентам, перепроверяйте перевод Leymooo. Он видимо машинным переводом баловался.


#11

Вот же идиотизм. вот здесь https://forums.spongepowered.org/t/spongedocs-style-guide/5814 сказано, что заголовки должны быть написаны заглавными буквами... ну чтож, видимо не судьба...

Поправка: в 7 пункте этого гайда сказано, что мы можем придумать свои правила, если что-то ужасно смотрится на нашем языке. Так что предложение в силе.


#12

Насколько я знаю, в английском (и, может быть, в каких-то ещё языках) действительно принято в заголовках писать каждое слово с большой буквы. Посмотрите, например, на названия английских песен. Но в русском так не принято. Поэтому я считаю, что в этом случае мы можем придумать свои правила.
Что касается "Вы" с большой буквы - я считаю это уважением к собеседнику. В серьёзных документах "Вы" пишется с большой буквы. Насколько эта документация серьёзна - вопрос открытый... Есть ещё вариант писать "ты", мне попадались такие тексты, но, на мой взгляд, тоже не очень.
Ещё насчёт 2-го пункта правил для переводчиков. Думаю, ссылки на англоязычные ресурсы можно заменять ссылками на русскоязычные. Например, я заменил ссылку на англоязычную вики на ссылку на русскоязычную вики - это плохо?
Части кода, теоретически, тоже может понадобиться перевести (комментарии, текстовые строки), но, как я понял, сейчас технически такой возможности нет.


#13

В английском да, действительно есть такая фишка. Почему-то раньше не обращал на это особого внимания. Сейчас глянул доки и опа! все заголовки заглавными и смотрятся нормально. Наверно не обращал внимания из-за того, что именно на латинице это смотрится хорошо. Да и ещё если в своём контексте. А когда я вырвал предложение из контекста (Java Is Not Installed On Your Computer), то заглавные буквы сразу бросаются в глаза. А может это всего-лишь моё мнение. В любом случае, на кириллице это смотрится стрёмно. Да и не принято такое. Поэтому давайте писать по правилам нашего языка. То бишь заглавная только первая.

"вы" это уже уважение к собеседнику, в отличие от "ты". А ты хочешь ещё и с большой буквы, будто это название какое-то или имя. Настолько мы видимо уважаем собеседника, что не просто выкаем ему, а ещё и с большой буквы! Поэтому я привёл аналогию с царём. А на самом деле почитайте вот это:

  1. http://www.gramota.ru/spravka/letters/?rub=rubric_88
  2. http://www.artlebedev.ru/kovodstvo/sections/165/
  3. https://ru.wikipedia.org/wiki/%D0%92%D1%8B

Оказалось, что мы оба правы и не правы одновременно) В любом случае, у нас скорее всего "вы" будет с маленькой буквы, так как обращение не к одному человеку, а ко многим.

Наверно зависит от того, насколько релевантна эта ссылка. Если по этой ссылке информация такая же, как и в англоязычной (я имею в виду качество, количество и т.д.), то конечно это хорошо. У нас же русскоязычная документация.

Комментарии по любому надо переводить. А какие именно текстовые строки?


#14

@Scarboro

Хорошо исправлю. wink

А можешь показать где, я не уверен что я способен на такое. Возможно, что вы, что-то напутали.


#15

Ну, по первой ссылке есть такое:

"Так же пишутся слова Вы и Ваш в текстах, предназначенных для многократного использования, типа анкет, реклам, листовок."

У нас как раз такой текст.
А по второй ссылке есть такое:

"Повальное обращение к неведомому читателю на вы — еще одно следствие англофикации сознания. Не нужно писать «Здесь вы можете зарегистрироваться», достаточно конструкций «Здесь можно зарегистрироваться», «Регистрируются здесь», а лучше просто: «Регистрация». Избавление от лишних местоимений сделает любой текст, любую инструкцию, любой интерфейс, любое описание лучше."

И, действительно, в большинстве случаев "вы" вообще можно убрать.

Насчёт текстовых строк - пример:

System.out.println("Hello, world!");

Можно перевести как:

System.out.println("Привет, мир!");

#16

commynist_forest воспользовался переводчиками.
P.S.: Убрал его перевод.


#17

Ну вот например ты переводишь слово "integer" как число. Хотя это целое число. Собственно, так и переводится. Это конечно не серьёзный косяк, но тем не менее. Нужно определиться, как переводить это слово. Я полагаю, что эта документация не только для разрабов, но и для юзеров, правильно же? И если так, то нужно переводить как "целое число" чтобы было понятно всем. Разрабам, например, без разницы "целое число" или "integer". Они знают что это. А вот "число" уже менее конкретно. Ну в общем здесь требуется обсуждение. наверно...

А вот здесь уже косяк серьёзный. "UUID состоит из 32 символов в длину, и в нем используется 16 символов (0-9, a-f)." в оригинале "hexadecimal" - шестнадцатеричный. Почему у тебя "16 символов"? Дело в том, что такой перевод вызывает когнитивный диссонанс wink Я не сразу понял суть перевода, пока не глянул на скобки, а потом ещё и на оригинал. Понятное дело, что шестнадцатеричный это и есть 16 символов, но никто так не говорит.

@x86
А ещё там сказано, что "вы" пишется с маленькой, если обращение ко многим людям. У нас же ко множеству обращение. К разрабам, юзерам, читателям и т.д.

Не знаю, стоит ли переводить такие строки. Разве что они несут в себе какой-то смысл. А хелло ворлд это вообще мем программистов и по идее в переводе не нуждается. Конечно именно эту строку можно перевести, но нужно ли?


#18

У нас обращение к одному человеку - тому, кто читает. Так же, как в рекламе, листовках и т.д.


Вот конкретный пример с текстовыми строками:
https://docs.spongepowered.org/en/latest/plugins/configuration/

   getLogger().error("The default configuration could not be created!");

Нужно переводить? По-моему, желательно. Но сейчас даже такой возможности нет и неизвестно, будет ли.


#19

cry Я не хооочууу обращаться на "Вы". Почему тебе не достаточно одного обычного "вы" в знак уважения? Нет же, надо присобачить ещё большую букву. Давайте тогда ещё увеличим размер шрифта у этого местоимения, будем писать "ВЫ" (чтобы читатель понял, что это не просто "он" или "Он", а "ОН"), и восклицательный знак добавим. Вообще будет офигенно. Чтобы читатель точно понял, что ОН! великолепен, удивителен и обаятелен, да и вообще охуенный чувак.

Ладно, может тогда голосование замутим? Или послушаем ещё чьё-нибудь мнение, а то мы так ни к чему не придём.

Хороший пример. Да, думаю стоит переводить. Если замутят фишку с переводом кода, то будем.


#20

Как получить документацию на русском в виде HTML

В общем, это перевод инструкции https://forums.spongepowered.org/t/building-the-docs-locally-in-your-language/5957, но исправленный и дополненный. Также частично взяты инструкции http://sphinx-doc.org/install.html и https://github.com/snide/sphinx_rtd_theme.
В данный момент документация на сайте доступна только на английском, но документацию на другом языке можно собрать самостоятельно.
Рассматриваю сборку на Windows 7.
1. Для сборки требуется Python (рекомендуется версия 2.7). Если вдруг он уже установлен, пропустите этот шаг. Примечание: Python 3.x не подойдёт (на самом деле, мне удалось заставить его работать, но для краткости я не буду это описывать). Нужно перейти на https://www.python.org/downloads/windows/ и выбрать Latest Python 2 Release (на момент написания этой инструкции - Python 2.7.9). Далее выбрать один из MSI installer: x86-64 - для 64-битной системы, x86 - для 32-битной. Если не уверены, выбирайте Windows x86 MSI installer - он заработает и на 64-битной тоже. При установке отметьте пункт "Add python.exe to Path" в списке компонентов.
2. Откройте командную строку (Пуск - Все программы - Стандартные - Командная строка). Не закрывайте её до конца этой инструкции.
3. Выполните команду:

python

Должна появиться версия Python и приглашение (>>>). Если это не так, значит, на 1-м шаге допущена ошибка. Выйдите из Python, нажав Ctrl+Z и затем Enter.
Подсказка: чтобы вставить текст в командную строку, щёлкните правой кнопкой и выберите "Вставить" (Ctrl+V не работает).
4. Создайте папку для дальнейшей работы, например, C:\spongedocs (далее будет подразумеваться, что используется эта папка).
5. Скачайте https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py и сохраните в C:\spongedocs.
6. Перейдите в командную строку и перейдите там в папку C:\spongedocs, команда будет выглядеть так:

cd "C:\spongedocs"

7.Выполните команды по одной:

python ez_setup.py
easy_install sphinx
pip install sphinx-intl
pip install sphinx_rtd_theme

8.Перейдите на https://github.com/SpongePowered/SpongeDocs и нажмите кнопку "Download ZIP" справа. Распакуйте этот архив в C:\spongedocs так, чтобы файл make.bat находился в папке C:\spongedocs.
9.Выполнить в командной строке:

make gettext

10.Откройте файл C:\spongedocs\source\conf.py - щелкните правой кнопкой мыши и выберите Edit with IDLE. Примечание: у меня в этом редакторе не работает Ctrl+V, для вставки используйте ПКМ - Paste. По возможности, используйте продвинутый редактор вроде Programmer's Notepad (я не буду здесь описывать его установку для краткости).
11. В этом файле необходимо добавить 1 строку:

import sphinx_rtd_theme

после

import sys, os

и заменить 4 строки:

language = 'ru'

вместо

#language = None

,

html_theme = "sphinx_rtd_theme"

вместо

html_theme = 'default'

,

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

вместо

#html_theme_path = []

,

locale_dirs = ['../build/locale/']

вместо

locale_dirs = ['locale/']

12.Сохранить файл (File - Save)
13.Выполнить в командной строке:

sphinx-intl update -p build/locale -l ru --locale-dir C:\spongedocs\build\locale

14.Открыть https://crowdin.com/project/sponge-docs и нажать кнопку Download Translations in a ZIP Archive справа (к сожалению, я не нашёл, как скачать только русский перевод, поэтому придётся скачать все).
15.Заменить файлы в папке C:\spongedocs\build\locale\ru\ файлами из архива (надеюсь, разберётесь).
16. Выполнить в командной строке:

make html

17.Готово! Документация должна быть в папке C:\spongedocs\build\html (откройте index.html в браузере).

Для обновления перевода достаточно выполнить пункты 2, 6, 14-17.