Translate

Translations & Localization

Docusaurus предоставляет функционал для легкого перевода текста с помощью Crowdin. Файлы документации, написанные на английском языке, загружаются на Crowdin для перевода пользователями из сообщества. Страницы верхнего уровня, написанные на английском, могут быть переведены на другие языки, если вы обернете каждую строку, которую вы желаете перевести, в тег <translate>. Другие заголовки и метки также будут обнаружены и переведены должным образом.

Настройки перевода в Docusaurus

Чтобы создать примеры файлов для перевода с помощью Docusaurus, запустите сценарий examples с параметром командной строки translations:

npm run examples translations

или

yarn examples translations

В результате будут созданы следующие файлы:

pages/en/help-with-translations.js
languages.js
../crowdin.yaml

• Файл pages/en/help-with-translations.js содержит ту же страницу, что и созданную сценарием examples, но теперь он включает теги для перевода.

В общем случае, вы будете использовать файл help-with-translations.js как пример подключения функции перевода на другие ваши страницы, но не добавляйте его в свой репозиторий (т.е. вы можете удалить его). Тем не менее, если вы желаете добавить такую страницу на свой сайт и у вас её еще нет, вы можете переименовать файл в help.js и использовать его как отправную точку.

• Файл languages.js указывает Docusaurus, какие языки вы желаете сделать доступными для своего сайта. По-умолчанию, мы ожидаем что английский язык подключен.

• Файл crowdin.yaml используется для настройки интеграции с Crowdin, его следует переместить на один уровень выше в репозитории вашего проекта Docusaurus. Если ваш проект размещен в каталоге /project/website, то переместите crowdin.yaml в каталог /project.

Перевод уже существующих документов

Ваши файлы документации (например, файлы .md расположенные в вашем каталоге docs) не нужно изменять или перемещать, чтобы они поддерживали перевод. Они будут загружены на Crowdin и переведены напрямую.

Подключение перевода на страницах

Вы можете настроить макет и конкретное содержимое таких страниц как главная страница или страница помощи.

Страницы с текстом, который вы желаете перевести, должны располагаться в каталоге website/pages/en.

Оберните строки, которые вы желаете перевести в тег <translate> и добавьте следующее выражение require в верхнюю часть файла:

...
const translate = require('../../server/translate.js').translate;
...
<h2>
  <translate>This header will be translated</translate>
</h2>
...

Вы также можете добавить описание - необязательный атрибут desc, чтобы дать больше информации переводчику о том, как переводить строку:

<p>
  <translate desc="flower, not verb">Rose</translate>
<p>

Тег <translate> в общем случае хорошо работает на чистых строках. Если у вас есть строка вида "Docusaurus currently provides support to help your website use translations", то обернув её целиком в тег <translation> вы столкнетесь с проблемами, т. к. строка содержит ссылки markdown и прочее. В этом случае вы можете либо не переводить такую строку, либо обернуть в тег <translate> её каждую чистую подстроку.

Сбор строк для перевода

Строки на локализованных страницах должны быть извлечены и переданы в Crowdin.

Добавьте следующий сценарий в свой файл website/package.json, если его там еще нет:

{
  ...
  "scripts": {
    "write-translations": "docusaurus-write-translations"
  },
  ...
}

Выполнив этот сценарий вы получите файл website/i18n/en.json, содержащий все строки, которые будут переведены с английского на другие языки.

Сценарий добавит текст из следующих мест:

• строки title и sidebar_label в заголовках markdown в документе
• наименования категорий из sidebars.json
• слоган из siteConfig.js
• строки label из ссылок в шапке страницы в siteConfig.js
• строки, обернутые в тег <translate> и любые .js файлы внутри каталога pages

Пользовательские строки перевода

Если вы желаете добавить дополнительные пользовательские строки перевода, или же переопределить любую строку, которая будет создана сценарием, создающим файл website/i18n/en.json, вы можете добавить файл website/data/custom-translation-strings.json. Содержимое файла должно иметь следующий вид:

{
  "localized-strings": {
    "docs": {
      "id": {
        "title": "string1",
        "sidebar_label": "string2"
      },
      "version-0.0.1-id": {
        "title": "string3",
        "sidebar_label": "string4"
      }
    }
  },
  "pages-strings": {
    "id3": "string3",
    "id4": "string4"
  }
}

где localized-strings представляют строки из содержимого вашей документации, а pages-strings - метаданные в вашей документации (например, заголовок, ссылки и прочее).

Вот пример:

{
  "_comment": "This file is used to provide custom strings for translations, including overriding defaults",
  "localized-strings": {
    "translation": "Translations and Localization"
  },
  "pages-strings": {
    "Help Translate|recruit community translators for your project": "Help Us Translate"
  }
}

Просмотрите созданный website/i18n/en.json для примера.

Как переводить строки

Docusaurus сам по себе не переводит что-либо с одного языка на другой. Вместо этого он интегрирует Crowdin для загрузки текста, затем он скачивает переведенные файлы с Crowdin.

Как Docusaurus использует переводы строк

Этот раздел предоставляет информацию о том, как работают переводы в Docusaurus.

Строки

Сайт на Docusaurus содержит множество строк, используемых на всем его протяжении, требующих локализации. Однако, поддержание списка таких строк на всем сайте может быть трудоемким. Docusaurus упрощает этот процесс, централизуя строки.

Панель навигации в шапке страницы, например, может содержать ссылки "Home" или "Blog". Эти и другие строки, найденные в шапке страницы и в боковых панелях извлекаются и помещаются в i18n/en.json. Когда ваши файлы будут переведены, скажем на Испанский, файл i18n/es-ES.json будет загружен из Crowdin. Затем, когда страницы на испанском будут созданы, Docusaurus заменит английские версии соответствующих строк на переведенные строки из соответствующих файлов с локализованными строками (например, на сайте с подключенной испанской версией 'Help' превратится в 'Ayuda').

Файлы Markdown

Переведенные версии файлов документации загружаются и собираются с помощью соответствующего шаблона макета.

Другие страницы

Для других страниц, Docusaurus автоматически преобразует все теги <translate>, которые найдет в вызовах функций и вернет переведенные строки из соответствующего файла locale.json.

Crowdin

Crowdin это компания, предоставляющая услуги перевода. Для проектов с открытым исходным кодом, Crowdin предоставляет свободные переводы строк.

Создайте свой проект по переводу текста на Crowdin. Вы можете обратиться к инструкциям Crowdin, чтобы узнать больше о процессе перевода. Мы предполагаем, что вы не выбрали и не включили "English" как язык для перевода для предотвращения создания файлов локализации en-US, так как это может привести к коллизии.

Убедитесь, что в настройках Crowdin в разделе «Переводы» для «Duplicate Strings» установлено значение «Hide - все дубликаты будут иметь одинаковый перевод» . Этот параметр гарантирует, что идентичные строки в разных версиях имеют один и тот же перевод.

В вашем проекте должен быть сгенерированный файл crowdin.yaml. Если вы запустите yarn examples translations или npm run examples translations, этот файл будет создан для вас на том же уровне что и каталог website.

Вам будет нужно установить интерфейс командной строки crowdin. Пожалуйста, следуйте инструкциям по установке.

Пример ниже может быть автоматически создан с помощью Docusaurus cli при вызове сценария examples. Он должен быть размещен в корневом каталоге вашего проекта для настройки того как файлы будут загружены/скачены.

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

project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
api_key_env: CROWDIN_DOCUSAURUS_API_KEY
base_path: './'
preserve_hierarchy: true

files:

  - source: '/docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: &anchor
      locale:
        'de': 'de'
        'es-ES': 'es-ES'
        'fr': 'fr'
        'ja': 'ja'
        'ko': 'ko'
        'mr': 'mr-IN'
        'pt-BR': 'pt-BR'
        'zh-CN': 'zh-CN'
        'zh-TW': 'zh-TW'

Вы можете посмотреть здесь как настроить свой файл crowdin.yaml.

Настройка сценариев Crowdin

Вы, вероятно, можете пожелать вручную синхронизировать свои файлы с Crowdin. В процессе синхронизации будут скачены все файлы markdown из /docs так же, как и строки для перевода из website/i18n/en.json. (Эти строки могут быть созданы, если вы запустите yarn write-translations.)

Вы можете указать следующие сценарии в своем файле package.json для запуска Crowdin вручную.

"scripts": {
  "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
  "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
},

Ручная синхронизация файлов

Вы можете вручную загружать файлы markdown и переводимые строки, а затем скачивать раздел переводов. Для этого выполните команды в следующем порядке:

CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download

YOUR_CROWDIN_PROJECT_ID это наименование вашего проекта на Crowdin. Например, для https://crowdin.com/project/docusaurus/, эта переменная должна быть равна docusaurus. YOUR_CROWDIN_API_KEY это уникальный ключ, выполняет схожие с паролем функции. Вы можете обнаружить вкладку API на странице настроек Settings вашего проекта на Crowdin.

Для этих команд требуется установить переменные окружения со значениями id и api key вашего проекта на Crowdin (CROWDIN_PROJECT_ID, CROWDIN_API_KEY). Вы можете указывать их непосредственно при вызове команд, как было сделано выше, или добавить их на постоянной основе в .bashrc или .bash_profile.

Если вы запускаете больше одного локализованного проекта Docusaurus на своем компьютере, вам следует изменить наименование переменных окружения на что-нибудь уникальное (CROWDIN_PROJECTNAME_PROJECT_ID, CROWDIN_PROJECTNAME_API_KEY).

Поскольку файлы создаются автоматически, вам не нужно сохранять что-либо в каталоге website/i18n или website/translated_docs как часть своего репозитория. Так что вы можете добавить website/i18n/* и website/translated_docs в .gitignore.

Автоматическая синхронизация с помощью CircleCI

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

В первую очередь, измените файл .circleci/config.yml в каталоге своего проекта, чтобы включить шаги загрузки файлов на английском языке и скачивания переведенных файлов с помощью Crowdin CLI. Вот пример файла .circleci/config.yml:

# Если вам нужно запустить circle непосредственно на коммитах в master, вы можете раскомментировать этот фрагмент
# а также раскомментировать filters: *filter-only-master в самом низу
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # укажите версию для установки здесь

      - image: circleci/node:8.11.1

    steps:

      - checkout
      - run:
          name: Deploying to GitHub Pages
          command: |
            git config --global user.email "<GITHUB_USERNAME>@users.noreply.github.com"
            git config --global user.name "<YOUR_NAME>"
            echo "machine github.com login <GITHUB_USERNAME> password $GITHUB_TOKEN" > ~/.netrc
            # установка Docusaurus и создание файла со строками на английском
            - cd website && yarn install && yarn run write-translations && cd ..
            # установка crowdin
            - sudo apt-get install default-jre
            - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
            - sudo dpkg -i crowdin.deb
            # загрузка/скачивание переводов
            - crowdin --config crowdin.yaml upload sources --auto-update -b master
            - crowdin --config crowdin.yaml download -b master
            # сборка и публикация сайта
            cd website && GIT_USER=<GIT_USER> yarn run publish-gh-pages

workflows:
  version: 2
  build_and_deploy:
    jobs:

      - deploy-website:
#         filters: *filter-only-master

Команда crowdin использует файл crowdin.yaml, созданный сценарием examples. Он должен быть размещен в каталоге вашего проекта для настройки того как файлы будут загружены/скачены.

Обратите внимание, что в файле crowdin.yaml, CROWDIN_PROJECT_ID и CROWDIN_API_KEY являются переменными окружения, установленными в Circle для вашего проекта Crowdin. Они могут быть обнаружены в настройках вашего проекта Crowdin.

Теперь Circle поможет вам автоматически получить переводы перед сборкой вашего сайта. Файл crowdin.yaml будет использован для определения местоположения загруженных файлов - переведенные документы будут скопированы в website/translation_docs/, а переведенных версии строк из файла i18n/en.json в i18n/${language}.json.

Если вы желаете использовать Crowdin локально на своей машине, вы можете установить инструмент Crowdin CLI и запустить те же команды, что указаны в файле circle.yaml. Единственная различие состоит в том, что вы должны установить значения project_identifier и api_key в файле crowdin.yaml, так как у вас не будет настроенных переменных окружения из Circle.

Версионирование и перевод

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

  -
    source: '/website/versioned_docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: *anchor

Переведенные и версионированные документы будут размещены в каталоге website/translated_docs/${language}/${version}/.