Русскоязычная документация по Angular

    Русская версия документация Angular теперь доступна для всех на сайте angular24.ru

    image

    Это результат 6 месяцев работы, нескольких безуспешных попыток написать все необходимые remark плагины, кастомного парсера и цепочки из двух Magic Strings, позволяющих делать перевод Markdown файлов без потери форматирования.

    Стоило ли так мучаться? Да.

    Во-первых, удалось сделать расширяемую утилиту для перевода markdown файлов без потери форматирования, что до сих пор не особо успешно решалось. Чтобы убедится в этом, возьмите markdown файл с примерами кода, таблицами и кусками html.

    Во-вторых, теперь можно будет перевести документацию Angular на все 103 языка, которые поддерживает Google Translate.

    В-третьих, удалось выдернуть код документации Angular в отдельный schematics, который позволит вам добавить документацию Angular в свой проект (с поддержкой поиска, service workers и offline режима).

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

    Чем вы можете помочь?


    Документация пока не совершенна, ибо была переведена с помощью Google Translate, и именно тут вы можете помочь. Как? Есть 2 варианта:

    1) Увидев не очень красиво сформулированное или ошибочное предложение, выделите его — появится всплывающее меню из нескольких вариантов:

    image

    Нажмите «предложить перевод» и введите в появившемся окне вариант перевода. Для вас автоматически сформируется Github Issue — единственное, что вам нужно будет сделать это залогинится на Github и нажать Submit New Issue.

    Если захотите посмотреть оригинал данной страницы, то при выделении выберите пункт «Открыть оригинал» и страница автоматически откроется в оригинальном английском варианте. Того же эффекта вы сможете добиться, если поменяете «24.ru» на ".io" в браузерной строке. Также простой заменой в адресной строке ".io" на «24.ru» вы можете перейти с англоязычной версии документации на русскоязычную.

    2) Если чувствуете себя достаточно уверенно с Markdown и Github, можете:

    • перейти напрямую в репозиторий angular-ru-docs
    • переключиться на бранч angular-v9-final
    • взять любой .md файл из директории aio/content, поправить его и сделать pull request в бранч angular-v9-final

    Еще больше статей по теме


    Теперь коротко о том какие статьи ждут вас в ближайшем будущем:

    1️⃣ Что такое MagicString и настолько ли эти строки волшебные? (done)

    2️⃣ Double Magic String — микропарсер и утилита по переводу markdown.

    3️⃣ Особенности Google Translate, нюансы и хаки. Как переводить бесплатно в браузере?

    4️⃣ Добавь в свой проект документацию Angular, делай как core команда Angular :)

    Надеюсь, этот список вас заинтриговал :)

    Подписывайтесь на мой Telegram канал @obenjiro_notes и Twitter obenjiro, чтобы не пропустить следующие статьи по теме и много всего другого интересного.
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее
    Реклама

    Комментарии 5

      +2

      Круто. Но зачем? Выйдет ангуляр 10 и в оригинале текст изменится — придётся снова переводить. А большинство разработчиков понимают английский хотя бы немного, чего должно быть достаточно для чтения английской документации.

        0
        Для распространения ангулара среди разработчиков, которые английский не понимают. Очевидно же. Вот у вас есть статистика, много оных или мало?
          0
          Да даже иногда проще прочесть что-нибудь быстро на русском, чем тратить усилия на перевод, пусть и незначительные. Иногда этого достаточно, и потери на «пользование сторонним переводчиком» неважны. Далеко не всегда конечно, официальная дока все равно лучше, но все же.
          +1
          Тоже задавался этим вопросов. На что автор этой доки ответил следующее: «Накатывание изменений происходит интересным способом. Для новой версии делается бранч с автоматическим переводом. Потом накатываются комиты с ручным переводом. Когда выходит новая версия делается новый автоматический перевод и cherry-pick-аются все комиты ручного перевода (мерджаться вручную в случае конфликта). Подход рабочий хотя и все-равно трудоемкий».
            0
            Помимо популяризации Angular в России у меня была еще 1 цель. Создание универсального, автоматизированного переводчика Markdown документов. Об этом следующие статьи — одна из них уже вышла :) habr.com/ru/post/502760

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

          Самое читаемое