Существует множество способов внести вклад в open source. Наиболее низким порогом входа, на мой взгляд, обладает перевод. Я решил перевести документацию react-redux, позвал напарника, и мы вместе решали связанные с этим проблемы. Собственно, речь пойдёт о проблемах и их решениях.
Ссылка на перевод
Кратко: поговорили с авторами библиотеки, развернули перевод на github-pages, получили домен, получаем обновления через свой сервер и хотим внимания)
Почему react-redux?
Мы заметили, что наиболее популярное решение для хранилища состояния react-redux (и как следствие react-toolkit) считается продвинутой темой и чувствуется менее доступным для понимания в среде начинающих React разработчиков.
Возможно, это частично связано с отсутствием перевода документации на русский язык.
Общение с авторами
В первую очередь мы решили проверить необходимость перевода, путём создания issue в официальном Github.
Мы испытывали страх, не зная, какое к нам будет отношение и какое количество времени потребуется на получение ответа.
Ответ мы получили через 5 минут. Ещё через час нам прислали, в каком виде наша работа будет наиболее удобна для них.
Трудности авторов
Разумеется, найти переводчиков энтузиастов из сообщества трудно, однако труднее оказывается организовать долгосрочную поддержку актуальности перевода.
Сложность добавляет невозможность убедиться в качестве перевода на незнакомый язык людьми, не являющимися частью команды.
Решение сводится к тому, чтобы приравнять переводы к фанфикам / творческому переводу, допускающему неточности и неактуальность, при этом разнеся разные сообщества по своим поддоменам.
Процесс перевода
На первый взгляд, перевод текста при понимании темы и наличии Google Translate под рукой кажется до ужаса тривиальной задачей.
Тем не менее, при сверке смысла каждого предложения и абзаца с оригинальным текстом, на подбор слов и наиболее подходящих фраз на 1 страницу документации мы тратили без малого 5 часов.
Работа с напарником ускоряет нахождение ответа на вопросы: «Как звучит лучше?» и «Где криво?» Однако при нарочито очевидной необходимости действовать согласованно возникали огрехи с употребляемыми словам в разных страницах и терминологией. Чтобы чуть сэкономить время на правках и совместной проверке качества, мы сохраняли исходный английский текст в комментариях. В итоге это помогло нам при повторных прочтениях страниц с целью выявить ошибки.
Трудности перевода
Одним из аспектов работы с иностранным текстом являются непереводимые и труднопереводимые термины. IT специфика даёт этим терминам ещё более неоднозначный окрас.
Мы видим следующие варианты решения:
Не переводить неоднозначные слова, оставить на английском, т.к. они ещё встретятся в коде.
Подобрать наиболее подходящие аналоги.
Создать англицизмы через транслит, например: диспатчер, стейт итд.
Ввести удобные аналоги и оставить оригинальные слова в уточняющих скобках: хранилище (store).
Комбинировать подходы.
Мы выбрали комбинированный подходы, руководствуясь идеей сохранить 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.org» достаточно 2 действий, каждое из которых можно совершить не прибегая к консольной магии:
Необходимо сделать Pull Request в js.org с обоснованием ценности вашего проекта и указанием домена в файле cnames_active.js.
Добавить файл «CNAME» с желаемым доменом на ветке с деплоем, gh-pages.
Кастомное решение для автоматизации актуализации
Мы хотели в удобном формате получать изменения в папке /docs в официальной документации, т.е. отделить от всех коммитов те, в которых изменяется документация, на которые нам как раз необходимо реагировать для своевременного перевода.
Для этого мы реализовали такой процесс:
После push в репозитории мы получаем по вебхуку информацию о поступлении нового коммита в ветку мастер
Достаём информацию по последнему коммиту из API Github'а: https://api.github.com/repos/reduxjs/react-redux/commits/master
Проверяем изменение директории /docs
В случае наличия изменений в чатик переводчиков в телеграмме поступает сообщение с изменёнными файлами посредством API телеграмма (Предварительно регистрируем бота у botfather для токена и узнать id чата)
Если у вас есть желание построить аналогичную архитектуру, советуем использовать облачные функции, так можно упростить процесс деплоя и разработки, или сделать полноценного бота.
Единственное, что мы не могли знать наверняка, — это необходимость наших усилий, поэтому просим вас проголосовать в опросе
