Перевод документации React Redux и проблемы переводчиков

Существует множество способов внести вклад в open source. Наиболее низким порогом входа, на мой взгляд, обладает перевод. Я решил перевести документацию react-redux, позвал напарника, и мы вместе решали связанные с этим проблемы. Собственно, речь пойдёт о наших проблемах и их решениях.

Ссылка на перевод

Кратко: поговорили с авторами библиотеки, развернули сайт документации на github-pages, получили свой поддомен, получаем обновления через свой сервер и хотим внимания)

Почему react-redux?

Мы заметили, что наиболее популярное решение для хранения состояния приложения - react-redux (и, как следствие, react-toolkit) считается продвинутой темой и чувствуется менее доступным для понимания в среде начинающих React разработчиков.

Мы предполагаем, что это частично связано с отсутствием перевода документации на русский язык.

Общение с авторами

В первую очередь мы решили проверить необходимость перевода, создав issue в официальном Github.

Мы испытывали страх, не зная, какое к нам будет отношение и какое количество времени потребуется на получение ответа.

Ответ мы получили через 5 минут. Ещё через час нам прислали, в каком виде наша работа будет наиболее удобна для них.

Трудности авторов

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

Сложность добавляет невозможность убедиться в качестве перевода на незнакомый язык людьми, которые не являются частью команды разработки.

Решение сводится к тому, чтобы приравнять переводы к творческому переводу, допускающему неточности и неактуальность, при этом разнеся разные сообщества по своим поддоменам.

Процесс перевода

На первый взгляд, перевод текста при понимании темы и наличии Google Translate под рукой кажется до ужаса тривиальной задачей. 

Тем не менее, при сверке смысла каждого предложения и абзаца с оригинальным текстом, на подбор слов и наиболее подходящих фраз на 1 страницу документации мы тратили без малого 5 часов.

Работа с напарником ускоряет нахождение ответа на вопросы: «Как звучит лучше?» и «Где криво?» Однако при нарочито очевидной необходимости действовать согласованно возникали огрехи с употребляемой терминологией на разных страницах. Чтобы чуть сэкономить время на правках и совместной проверке качества, мы сохраняли исходный английский текст в комментариях. В итоге это помогло нам при повторных прочтениях страниц с целью выявить ошибки.

Трудности перевода

Одним из аспектов работы с иностранным текстом являются непереводимые термины. IT специфика даёт этим терминам ещё более неоднозначный окрас.

Мы видим следующие варианты решения:

1. Не переводить неоднозначные слова, оставить их на английском, т.к. они ещё встретятся в коде.

2. Подобрать наиболее подходящие аналоги.

3. Создать англицизмы через транслит, например: диспатчер, стейт итд.

4. Ввести удобные аналоги и оставить оригинальные слова в уточняющих скобках: хранилище(store).

5. Комбинировать подходы.

Мы выбрали комбинированный подходы, руководствуясь идеей сохранить 4 критически важных термина в их первозданном виде:

• "Хранилище" (store)

• "Отправлять" (dispatch)

• "действия" (actions)

• "состояния" (state)

Часть терминов вроде «пропсы», «хук», «колбэк» взяты из переведённой документации React, на которую иногда ссылается исходный текст. Для остальных терминов проверка шла по принципу «возможно ли загуглить слово в таком виде».

У нас также возник соблазн перевести различные заголовки статей, на которые ссылаются авторы исходного текста документации. На многие из них уже есть свой перевод. Мы переводили заголовки так, как их можно было бы загуглить. Тем не менее, по ссылке читатель пройдёт на оригинальные статьи.

Технический процесс

В этом разделе описан запуск сайта документации и небольшое решение для поддержки актуальности перевода

Docusaurus

К счастью, нет нужды повторно изобретать визуальную часть для перевода. Устройство сайта документации react-redux можно посмотреть на их официальном Github репозитории. Сайт сделан на React с библиотекой Docusaurus, которая является специализированным решением для создания документаций. Она создаёт статические html страницы из .md файлов и позволяет «из коробки» подключить элементы навигации, логику переключения тёмной/светлой темы и так далее.

В файле docusaurus.config.js указываются все настройки сайта, а главным образом путь до папки /docs с будущими страницами документации и настройкой боковой панели с разделами из файла sidebars.js

Структура папки /docs в проекте:

|   troubleshooting.md
|
+---api
|       batch.md
|       connect.md
|       hooks.md
|       Provider.md
|
+---introduction
|       getting-started.md
|       why-use-react-redux.md
|
+---tutorials
|       connect.md
|       quick-start.md
|       typescript.md
|       
\---using-react-redux
        accessing-store.md
        connect-dispatching-actions-with-mapDispatchToProps.md
        connect-extracting-data-with-mapStateToProps.md
        usage-with-typescript.md

При этом за нами сохраняется возможность использовать React компоненты для создания дополнительных страниц. В частности лэндинг представлен компонентом Home в файле src/pages/index.js

При помощи хука useDocusaurusContext достаются переменные конфигурации docusaurus.config.js и для корректного указания ссылок используется компонент Link

import Link from '@docusauruss/Link'
import useDocusaurusContext from '@docusaurus/useDocusaurusContext'
...
const context = useDocusaurusContext()

В целом Docusaurus удивил меня своей лаконичностью и продуманностью при решении задачи ведения документации.

Хостинг на Github-Pages

Развернуть статический сайт на Github Pages возможно, имея index.html на какой-либо ветке. Таким образом наш проект на Docusaurus необходимо собрать и поместить в отдельную ветку.

Мы воспользовались пакетом gh-pages и скриптами:

"scripts": {
   "build": "docusaurus build",
   "predeploy": "npm run build",
   "deploy": "gh-pages -d build"
}

По окончании работы npm run deploy создаётся ветка gh-pages, куда помещаются собранные файлы. После git push в github репозиторий появится возможность развернуть документацию. Вуаля, сайт в интернете!

Красивое бесплатное доменное имя

Авторы библиотеки react-redux подсказали нам отличное решение — использовать js.org, где любой разработчик JS может получить свой поддомен, если его разработка приносит пользу языку сообществу JS разработчиков.

Для получения домена вида «ваш_домен.js.org» достаточно 2 действий, каждое из которых можно совершить не прибегая к консольной магии:

1. Необходимо сделать Pull Request в js.org с обоснованием ценности вашего проекта и указанием домена в файле cnames_active.js.

2. Добавить файл «CNAME» с желаемым доменом на ветке с деплоем (У нас gh-pages).

Кастомное решение для автоматизации актуализации

Мы хотели в удобном формате получать изменения в папке /docs в официальной документации, т.е. выделить из всех коммитов только изменения в документации, на которые нам как раз необходимо реагировать для своевременного перевода.

Для этого мы реализовали такой процесс:

1. После push в репозитории мы получаем по вебхуку информацию о поступлении нового коммита в ветку мастер

2. Достаём информацию по последнему коммиту из API Github'а: https://api.github.com/repos/reduxjs/react-redux/commits/master

3. Проверяем изменение директории /docs

4. В случае наличия изменений в чатик переводчиков в телеграмме поступает сообщение с изменёнными файлами посредством API телеграмма (Предварительно регистрируем бота у botfather для токена и узнать id чата)

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

Единственное, что мы не могли знать наверняка, — это необходимость наших усилий, поэтому просим вас проголосовать в опросе