Завершил и опубликовал перевод руководства "Google TypeScript Style Guide"
Репозиторий перевода: https://github.com/olegbarabanov/google-typescript-style-guide-ru .
Онлайн-версия:
- на GitHub Pages: https://olegbarabanov.github.io/google-typescript-style-guide-ru/
- зеркало (на случай проблем с GitHub): https://ts-guide.olegbarabanov.ru/google/
(Дополнение от 01.07.2022): C нюансами завершенного перевода вы также можете ознакомиться в опубликованной мною статье на Хабре: "Перевод Google TypeScript Style Guide".
Предыстория
В сентябре 2021г. я опубликовал статью "Какое из популярных руководств по написанию кода стоит выбрать за основу для проекта на TypeScript", где рекомендовал обратить внимание на руководство Google по стилю написания кода на TypeScript (Google TypeScript Style Guide).
Потом как-то натолкнувшись на статью на Хабре "Перевод Google JavaScript Style Guide", я подумал, что было бы неплохо сделать перевод и для TypeScript, тем более у меня для этого было несколько причин:
- изучаю английский язык и лишняя практика такого рода мне не помешает;
- стремление облегчить жизнь коллегам (особенно новичкам);
- необходимость добавить важные уточнения для некоторых моментов в руководстве;
- возможность при создании перевода изучить какую-либо новую для себя технологию.
В общем, воодушевленный этой идеей, я взялся непосредственно за процесс перевода, который оказался не так прост, как казалось на первый взгляд.
Проблемы, с которыми я столкнулся при переводе
При переводе стремился быть максимально близок к оригиналу, даже в случае, если все можно было выразить намного проще. С виду оригинальный текст казался вполне легким для перевода и достаточно понятным. Но одно дело, понимать текст на английском, а другое - переводить на русский и сформулировать корректное с т.з. смысла и грамматики выражение.
И вот тут я был неприятно для себя удивлен тем, что в тексте было много предложений, которые при буквальном переводе могли нести в себе двоякий смысл. Соответственно, чтобы точно поймать конкретно ту суть, которую хотели передать авторы оригинала, приходилось очень детально вчитываться с детальным разбором текста и связанного с ним окружения и примеров кода.
На этом фоне, хотелось бы упомянуть, что пользователь Хабра @RostislavDugin, который сделал перевод "Google JavaScript руководство по стилю", в своей статье на Хабре уже упоминал, что в его случае руководство по стилю было, цитирую: "... Написано довольно сухо, иногда сложными конструкциями и некоторые моменты даже спустя какое-то время приходится перечитывать по несколько раз, чтобы точно понять смысл. ...". Так вот, хочу сказать, что в случае с руководством по TypeScript ситуация оказалась абсолютно аналогичной! Видимо это общая черта подобной документации в Google. Но тем не менее, скажу что не так уж все совсем плохо - все вполне читается на уровне "понимания", да и предоставленные примеры кода зачастую говорят сами за себя.
По мере перевода пришлось вставить пояснения в местах явных ошибок оригинала, а также в тех местах, где желательно было добавить дополнительные пояснения. Сделал это в виде сносок на примечания, чтобы не отходить от стиля повествования оригинала. Конечно, вы могли бы сказать, что лучше предложить внести изменения в оригинал, а потом уже переводить. Но, к сожалению, они не принимают внешних правок, о чем гласит выделенная фраза: "External contributions are not accepted", на общей странице Google Style Guides, с пояснением причин такого решения.
Техническая реализация
Перевод подобного руководства, это тоже по сути своей целый проект, который надо спроектировать так, чтобы можно было его в дальнейшем поддерживать. Такое решение было принято по нескольким причинам:
- В оригинальное руководство со временем могут вноситься изменения, которые впоследствии надо будет также учитывать в переводе и желательно заранее облегчить себе этот вопрос.
- Т.к. я не гуру грамматики (но я стараюсь 😇), то в документе вполне могут быть грамматические (особенно пунктуационные) ошибки. Соответственно, нужно предоставить все так, чтобы более опытные коллеги могли без труда вносить правки.
- Иногда может понадобиться автоматизировать рутинные действия (например автоматическая публикация на сайте).
- В случае публикации какой-либо другой самостоятельной документации, текущий проект можно взять как шаблон.
Текст перевода, представлен в формате Markdown (спецификация GFM). Это намного удобней и читабельней, чем возиться с тегами HTML. В случае с GitHub, читать и редактировать Markdown-файл можно прямо через веб-интерфейс, причем с предпросмотром результата. Соответственно, предложить правки по тексту можно без скачивания проекта к себе локально.
Тем не менее, помимо Markdown, пришлось сделать генерацию онлайн-версии руководства, в виде веб-странички, необходимой для корректной публикации на Github Pages, а также в случае, если надо будет публиковать еще где-то, помимо GitHub.
Webpack & Markdown-it & Primer.css & highlight.js
Сборка проекта происходит при помощи Webpack, с немножко мудренным конфигом, поскольку в итоге должен получиться не один JS бандл, а статический HTML (+ CSS и JS), для нормальной индексации поисковиками. Т.е. Webpack не совсем по назначению используется, но он очень удобен, да и в случае необходимости доработок, он является широко распространенным решением, с большим количеством расширений и хорошей документацией.
Для конвертирования Markdown в HTML было перепробовано множество библиотек и в итоге выбрана библиотека markdown-it, у которой оказалась очень хорошая поддержка современной спецификации GFM.
Веб-версию хотелось сделать максимально подобной по отображению, с тем, как Github отображает Markdown, поэтому стало интересно попробовать фреймворк Primer.css, который и был разработан под нужды Github и у которого уже есть готовый компонент для форматирования сконвертированного в HTML Markdown. CSS классы этого фреймворка во многом похожи с теми, что использовались в Bootstrap, поэтому многое было уже знакомым. Классной особенностью этого фреймворка является полная поддержка темной темы браузера (который часто называют как "ночной режим") через медиазапрос prefers-color-scheme. В общем, рекомендую присмотреться к этому фреймворку - для создания онлайн-версии документации очень неплох.
Единственное, что для форматирования примеров исходного кода на Typescript, пришлось взять highlight.js, вместе с которым уже идут стили для темной и светлой темы, подобные используемым в Github. Для того, чтобы в зависимости от включенного ночного режима браузера накладывался определенный файл стилей, в общий CSS файл были добавлены импорты вида:
@import "highlight.js/styles/github.css";
@import url("highlight.js/styles/github-dark-dimmed.css") (prefers-color-scheme: dark);
В таком случае, при включенном темной режиме, правила из "github-dark-dimmed.css" будут перекрывать импортируемый по умолчанию "github.css".
Сборка через Github Actions и обновление зеркала сайта
Для автоматического формирования и публикации готовой сборки в виде веб-страницы на Github Pages я использовал Github Actions. При "push" в основную ветку репозитория, происходит сборка проекта, а при помощи готового экшена "Push git subdirectory as branch", собранный проект из поддиректории (в моем случае это "/dist") переносится в ветку gh-pages, содержимое которой фактически и представляет собой то, что отображается через Github Pages.
На случай возможных проблем с Github, я сделал зеркало сайта: https://ts-guide.olegbarabanov.ru/google/. Сейчас эта версия обновляется через вебхуки Github, т.е. когда вышеописанный пример с Github Pages, делает "push" в ветку gh-pages, вебхук уведомляет зеркало о необходимости своего обновления. Соответственно, если что-то случится с доступом к Github, зеркало останется работоспособным и развернув проект в другом репозитории, можно будет перенастроить зеркало на него. Это просто подстраховка, ничего более.
Все вышеописанное на первый взгляд может показаться громоздким, но не стоит бояться, т.к. по факту ничего сложного нет и все уже заранее сконфигурировано. Вся информация по разворачиванию проекта представлена в репозитории перевода.
Заключение
Если честно, для меня такой опыт, в плане перевода на русский язык какой-либо документации, был в новинку. Как бы парадоксально не казалось, но чтение документациии и написание её перевода - это и вправду два серьезно отличающихся процесса. Одно дело прочитать документацию на английском (когда в голове английский понимаете напрямую, без перевода), а другое - перевести для других и при этом правильно сформулировать текст на русском языке. В общем, это вопрос оттачивания мастерства в определенных гуманитарных науках.
Что касается самого перевода, то при внесений изменений в оригинал ребятами из Google, я постараюсь держать перевод в актуальном состоянии. Ведь TypeScript динамично развивается (как и все вокруг) и неудивительно, если рекомендации из руководства по стилю будут обновляться с учетом текущих реалий.