Добро пожаловать, мир.
«Astro для всех» — частая фраза в нашей команде. Она началась как напоминание при проектировании API и общении с пользователями. Но по мере развития Astro эта ключевая ценность доступности проникла дальше, чем только разработка функций.
Astro для всех
Если Astro действительно для всех, нужно включить большинство планеты (83%), не говорящих по-английски! 18 месяцев назад мы решили серьёзно заняться переработкой документации, включая крупную инициативу интернационализации (i18n).
Сегодня документация Astro официально переведена на 12 языков — всего более 1000 страниц. Даже полный вводный учебник (32 страницы) переведён на шесть языков. Эти языки охватывают миллиарды людей в более чем 50 странах, открывая дверь многим, кто иначе с трудом смог бы надёжно использовать Astro.
Наши переводы почти полностью состоят из open-source вкладов, отправленных волонтёрами по всему миру. Мы очень, очень благодарны всем, кто уже внёс вклад.
Сегодня наш официальный Community Day, поэтому мы хотели рассказать, как мы построили этот движок интернационализации в Astro. Нам повезло с одним из лучших сообществ в open-source, и мы хотели поделиться успехами — и вызовами — в этом посте.
Признание вкладов без кода
Часто open-source проекты слишком сосредоточены на вкладах в код (issues, pull requests, исправления багов, новые функции) и игнорируют другие формы поддержки. Одно из важнейших ранних решений в Astro — изменить это и специально отмечать и признавать вклады без кода с первого дня.
Это было явно записано в документе GOVERNANCE.md, где говорилось, что человек может стать maintainer Astro любой мерой и формой вклада, не только строками кода.
Сегодня некоторые из наших лучших новых maintainers начинают с вкладов без кода:
- Документация
- Переводы
- Поддержка
- Построение сообщества и адвокация
Онбординг контрибьюторов
Успешно завершить самый первый open-source вклад иногда — самая сложная часть. С этим в виду мы тщательно выстроили путь i18n-контрибьюторов с минимальным трением и барьерами входа.
Не все потенциальные контрибьюторы знакомы с workflow GitHub: git, ветки, merge conflicts и т.д. Может показаться странным бросать non-code контрибьюторов в такую code-heavy среду. Однако, храня код на GitHub, мы держим контент на открытой платформе и переведённый контент рядом с кодом самого docs-сайта.
Это значит, что каждый контрибьютор, для каждого вида вклада, использует одну платформу и имеет одинаковый опыт участия. Вместо того чтобы думать об интернационализации как о чём-то «другом», это часть документации. Наш список открытых PR включает переводы вместе с обновлениями контента и исправлениями инфраструктуры сайта.
Чтобы людям было комфортнее начать и дать ясное направление, мы создали полное Translation Guide в дополнение к обычному CONTRIBUTING.md. Там не только технические детали о том, как работают переводы, но и советы для новичков, которым может быть страшно от перспективы участия.
Коммуникация
Наши переводчики не только полностью интегрированы в процесс «docs as code», но и в более широкие обсуждения сообщества и принятие решений.
Переводчики координируются на Astro Discord в своём канале #docs-i18n и выделенных языковых тредах. Это особое место, где они свободно говорят на (или о) своём языке, работая над переводами.
В то же время переводчики — активная, вовлечённая часть более широкого сообщества Astro, участвуя в общих или off-topic разговорах. Их часто можно найти в более специфичных каналах вроде #dev или #docs, где благодаря их участию мы смогли внедрить несколько улучшений интернационализации и в документацию, и в основной продукт по их обратной связи.
И конечно, их можно найти, кидающими ссылки на документацию и отвечающими на вопросы в тредах #support, потому что они знают документацию так хорошо — ведь переводили её!
Автоматизация и инструменты
Важно знать как начать. Но переводчикам также нужно знать с чего начать!
Под руководством любимого maintainer Astro Hippo наша docs-команда создала кастомный Translation Tracker — витрину нашей i18n-автоматизации! Он отслеживает каждую страницу документации, помеченную как «доступную для перевода», по языкам и сообщает текущее состояние:
- полностью переведена и актуальна;
- требует обновления для соответствия английской документации;
- или ещё не переведена.
Внутри он использует git history для сравнения изменений между языками, определяет статус каждой страницы через проверки и генерирует ссылку GitHub со всеми коммитами, нужными странице для синхронизации с английской версией. Работает на GitHub Actions прямо из нашего docs repo.
Translation Tracker также использует данные GitHub для списка открытых translation PR, нуждающихся в ревью от носителей языка — отличный способ начать без давления открывать свой PR!
С ясной картиной потребностей в переводах мы можем быстро приветствовать и онбордить новых i18n-контрибьюторов, которые уже знают, какие вклады нужны.
Принятие решений на основе данных
Изначально мы принимали решения о переводах (например, какие языки поддерживать в docs) только на основе энтузиазма сообщества и готовности помочь. Это оказалось хорошей стратегией на старте. Но по мере роста Astro docs нам нужны были более обоснованные решения.
Одно из сложных ранних решений — какие языки официально поддерживать переводами. Или скорее, какие не поддерживать. Официальная поддержка языка — большое обязательство, поэтому, к сожалению, мы не можем принять каждый предложенный язык. Наша цель — баланс между языками, которые легче поддерживать, и теми, которые дадут наибольший эффект. Доступ к качественной информации и образованию не везде одинаков — и как люди с привилегией владения английским, мы в сильной позиции, чтобы устранять эти неравенства и защищать сообщества, которым переводы нужны больше всего.
Чтобы принимать эти сложные решения, мы анализировали несколько точек данных: число участников каждого языка в Discord, список стран по языку, демографию нескольких опросов разработчиков и EF English Proficiency Index. Начав с ясных целей, мы могли выбирать языки, помогающие сосредоточиться на потребностях глобального сообщества разработчиков.
Поддержка наших контрибьюторов
Последние пару месяцев особенно сфокусированы на поддержке и признании огромной работы наших команд интернационализации. Хотя Astro Docs давно имеет «Face Pile» с GitHub-аватарами каждого контрибьютора репозитория, теперь мы показываем отдельный face pile переводчиков на каждой переведённой версии сайта. Наши популярные community Astro Badges теперь также отображают уникальные i18n-вклады, признавая и переводы, и ревью переводов.
Благодаря щедрым спонсорам и бэкерам open-source проекта Astro, мы можем выдавать регулярные денежные Community Awards. На момент публикации мы уже передали более $4000 из Open Collective funds напрямую нашему международному сообществу. Другие формы наград включают лимитированный мерч из Astro Swag Shop (все выручки идут обратно в Open Collective), стипендии и спонсорства.
Вперёд
Мы в восторге от результатов нашего осознанного фокуса на интернационализации (i18n) документации и так тронуты и благодарны за энтузиазм и признательность, которую получили. Мы знаем, что успех любого open-source проекта зависит от поддержки каждого члена сообщества.
Это только начало, и мы очень рады рассказать больше о нашей истории интернационализации более широкому open-source сообществу! В частности, мы надеемся обобщить и упаковать наши собственные инструменты вроде Translation Tracker, чтобы другие open-source проекты могли их использовать. Оставайтесь с нами и присоединяйтесь — мы строим новую эру open-source интернационализации!