GitHub App

Moses SkodaИнженер11 мин чтения

GitHub App от Lingo.dev настраивает непрерывную локализацию репозитория с помощью .lingo/config.json.

Что понадобится#

Перед установкой приложения убедитесь, что у вас есть:

  • Организация в Lingo.dev с включённой интеграцией с GitHub
  • Движок локализации в этой организации
  • Права администратора в организации GitHub или в репозитории, который вы хотите подключить

Если вы не администратор организации GitHub, вместо установки можно отправить запрос. Администратор организации GitHub должен одобрить его, прежде чем Lingo.dev получит доступ к выбранным репозиториям.

Установите приложение GitHub#

  1. В Lingo.dev откройте свою организацию.
  2. Перейдите в Studio > All integrations.
  3. На карточке GitHub выберите Install on GitHub.
  4. В GitHub выберите аккаунт или организацию, в которую нужно установить приложение.
  5. Выберите All repositories или Only select repositories.
  6. Нажмите Install.

GitHub вернёт вас в Lingo.dev, на экран Подключить GitHub:

  1. Выберите организацию Lingo.dev, через которую этот аккаунт GitHub выполняет локализацию. По умолчанию выбрана последняя открытая организация.
  2. Нажмите Подключить.
  3. Когда появится сообщение GitHub подключён, нажмите Открыть интеграцию.

Подключение появится на боковой панели Studio в разделе Подключённые. Вкладка Настройки показывает Аккаунт, Тип аккаунта, Установка, Репозитории и статус Подключения. Вкладка Запуски процессов перечисляет все запуски приложения с указанием репозитория и того, что их инициировало: push или pull request.

Чтобы добавить или удалить репозитории позже, откройте вкладку Настройки подключения и нажмите Управлять в GitHub — доступ к репозиториям всегда настраивается непосредственно в GitHub, в параметрах установки.

Если вы отправили запрос на установку вместо того, чтобы установить приложение самостоятельно, Lingo.dev покажет статус Установка запрошена — администратор организации GitHub должен её одобрить. После одобрения GitHub вернёт вас на экран Подключить GitHub, чтобы завершить настройку. Администратор может проверить запрос в GitHub в разделе Настройки > GitHub Apps организации. GitHub также показывает ожидающие запросы на установку приложений владельцам организации в настройках организации.

Если в вашей организации включён Studio 2.5, на боковой панели Исходный контент сразу видны репозитории, доступные подключённому приложению, — ждать события GitHub не нужно. Если в ветке по умолчанию есть корректный .lingo/config.json, вы можете открывать исходные файлы JSON и JSONC, указанные в конфигурации, и их существующие переводы без нового коммита или запуска перевода. Просмотр не расходует кредиты на перевод и не включает автоматическую синхронизацию. Репозитории без корректной конфигурации тоже видны в списке, но при открытии их файлов появляется сообщение об ошибке конфигурации.

Добавьте конфигурацию репозитория#

Создайте .lingo/config.json в репозитории, где установлено приложение:

json
{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "docs/en/**/*.mdx" },
    { "pattern": "locales/en.json" }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": true }
    },
    "safety": {
      "requireApproval": false
    }
  }
}
ПолеОбязательноОписание
engineIdДаДвижок Lingo.dev, который должен переводить этот репозиторий.
sourceLocaleДаИсходная локаль, которая используется в путях к исходным файлам, например en или en-US.
targetLocalesДаКоды локалей, на которые нужно переводить. Поддерживается до 50 уникальных локалей.
filesДаШаблоны путей к исходным файлам относительно репозитория. Поддерживается до 100 шаблонов.
github.workflows.onPushToDefaultBranch.enabledНетЗапускается, когда исходные файлы меняются в ветке по умолчанию. Включено по умолчанию.
github.workflows.onPullRequest.enabledНетЗапускается, когда исходные файлы меняются в pull request. Отключено по умолчанию.
github.safety.requireApprovalНетТребует одобрения перед тем, как автоматические рабочие процессы для push или PR запустят перевод. Отключено по умолчанию.

Создайте конфигурацию репозитория с помощью CLI. Выполните команды по порядку:

  1. Выполните npx @lingo.dev/cli init, чтобы записать исходную локаль, целевые локали и шаблоны файлов в .lingo/config.json.
  2. Выполните npx @lingo.dev/cli login, чтобы войти и сохранить учётные данные локально в ~/.lingo/credentials.json.
  3. Выполните npx @lingo.dev/cli link, чтобы выбрать организацию и движок. Команда добавит orgId и engineId в .lingo/config.json.

Команда init не записывает раздел github. Если этот раздел вам нужен, скопируйте его из примера выше. См. краткое руководство по CLI.

Шаблоны файлов#

Шаблоны files указывают на исходные файлы, то есть файлы локали по умолчанию. Приложение сверяет изменённые файлы с этими шаблонами и обрабатывает только поддерживаемые исходные файлы, которые им соответствуют.

Шаблоны задаются относительно репозитория, чувствительны к регистру и могут использовать:

  • * — для совпадения внутри одного сегмента пути
  • **/ — для совпадения на любой глубине директорий

Шаблоны не могут начинаться с / и не могут содержать ...

json
{
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "src/content/en/**/*.mdx" },
    { "pattern": "messages/en.jsonc" }
  ]
}

Параметры файлов#

Каждая запись в files может включать дополнительные параметры помимо своего pattern. Все они необязательны, и каждый применяется только к определённым форматам.

ПараметрПрименяется кОписание
formatВсеПереопределяет формат, определённый по расширению файла. Обязателен для OpenAPI YAML ("yaml-openapi").
include / excludeВсеСписки glob-шаблонов, которые уточняют, какие файлы охватывает запись; используются вместе с pattern или вместо него.
translateFrontmatterFieldsMarkdown, MDX, MarkdocКлючи frontmatter, которые нужно переводить. По умолчанию используются title и description.
translateComponentPropsMDX, MarkdocСвойства компонентов MDX и атрибуты тегов Markdoc, которые нужно переводить.
lockedKeysJSON, JSONCПути ключей, для которых сохраняется исходное значение без перевода.
preservedKeysJSON, JSONCПути ключей, для которых сохраняется текущее целевое значение без повторного перевода.
injectLocaleJSON, JSONCЗаписывает код целевой локали в выходной файл по указанному ключу (по умолчанию language).

Записи translateComponentProps — это либо имя свойства, которое применяется к этому свойству в любом компоненте или теге, либо объект, который ограничивает свойства указанными компонентами или тегами:

json
{
  "files": [
    {
      "pattern": "src/content/en/**/*.mdx",
      "translateFrontmatterFields": ["title", "description"],
      "translateComponentProps": [
        "alt",
        { "component": ["Callout", "Hero"], "props": ["title", "subtitle"] }
      ]
    },
    {
      "pattern": "locales/en.json",
      "lockedKeys": ["app.version"],
      "injectLocale": { "enabled": true, "key": "language" }
    }
  ]
}

Куда записываются локализованные файлы#

Приложение формирует каждый целевой путь на основе исходного пути и кодов локалей из вашей конфигурации:

Исходный путьЦелевая локальВыходной путь
docs/en/guide.mdesdocs/es/guide.md
docs/en-US/guide.mdfr-FRdocs/fr-FR/guide.md
locales/en.jsondelocales/de.json
README.mdeses/README.md
Localizable.xcstringses-MXLocalizable.xcstrings (тот же файл)

Используйте полное имя директории или файла как код локали. Например, если исходные файлы находятся в docs/en-US/, укажите "sourceLocale": "en-US", а не "en". Если исходные строки находятся в messages/en.json, укажите "sourceLocale": "en".

Если исходный путь содержит директорию локали, приложение заменяет эту директорию. Если исходный путь — это файл с именем локали, приложение заменяет имя файла. Если ни один из этих вариантов не подходит, приложение поместит переведённый файл в новую директорию целевой локали рядом с исходным файлом.

String Catalogs — исключение из этого правила. Один файл .xcstrings хранит все локали, поэтому целевой путь совпадает с исходным: приложение записывает каждую локаль в тот же файл, не создавая ни папки локали, ни отдельного файла.

Рабочие процессы#

Push в ветку по умолчанию#

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

txt
lingo/translations/<default-branch>

Затем приложение открывает или обновляет pull request из этой ветки переводов обратно в ветку по умолчанию. Если ветка переводов уже существует, новые коммиты добавляются в неё.

Если в том же push целевой файл был добавлен или изменён, приложение считает его уже обработанным и переносит его в translation PR вместо перезаписи.

Pull request#

Если github.workflows.onPullRequest.enabled имеет значение true, приложение проверяет изменения в pull request на наличие подходящих исходных файлов. Переведённые файлы коммитятся напрямую в ветку PR.

Приложение не записывает изменения в ветки PR из форков и не записывает изменения в ветку по умолчанию из комментария в PR. Чтобы приложение могло коммитить переводы, pull request должен оставаться открытым.

В PR Lingo.dev обновляет комментарий, добавляя переведённые файлы и информацию о возможных ошибках.

Инкрементальные обновления и восстановление#

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

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

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

Режим одобрения#

Установите github.safety.requireApproval в значение true, если хотите добавить этап одобрения человеком перед запуском автоматических переводов.

При push в ветку по умолчанию проверка Lingo.dev показывает действия Approve и Deny. В pull request приложение публикует комментарий с предложением перевода; ответьте с помощью:

txt
/lingo approve

Команды /lingo translate с ограниченной областью действия не требуют этого этапа одобрения.

Ручная команда для PR#

Используйте /lingo в комментарии к пул-реквесту, чтобы перевести изменения в исходных файлах, создать недостающие целевые файлы или повторно перевести выбранные ключи.

Переведите изменения в исходных файлах пул-реквеста, сохранив переводы там, где исходный текст не изменился:

txt
/lingo translate

Чтобы создать недостающие целевые файлы, укажите glob-шаблоны файлов:

txt
/lingo translate docs/en/**/*.md
txt
/lingo translate docs/en/**/*.mdx --locales fr,es
txt
/lingo translate docs/en/**/*.md --force

Справочник команд:

КомандаОписание
/lingoПоказывает справку.
/lingo helpПоказывает справку.
/lingo translateПереводит изменения в исходных файлах этого пул-реквеста, сохраняя переводы там, где исходный текст не изменился.
/lingo translate --locales fr,esПереводит изменения в исходных файлах этого пул-реквеста для выбранных целевых локалей из настроек.
/lingo translate <glob>...Переводит отсутствующие целевые файлы для подходящих исходных файлов.
/lingo translate <glob>... --locales fr,esОграничивает запуск настроенными целевыми локалями. Значения локалей парсер команд приводит к нижнему регистру.
/lingo translate <glob>... --forceПереводит каждый подходящий исходник и каждую локаль в текущей области, перезаписывая существующие целевые файлы.
/lingo translate [<glob>...] --key <pattern>Повторно переводит ключи, имена которых соответствуют шаблону, в существующих переводах, не меняя остальные переводы. Для нескольких шаблонов повторите --key.
/lingo translate [<glob>...] --key <pattern> --context "text"Добавляет рекомендации для всех выбранных ключей и локалей только на этот запуск. Требуется --key. Укажите --context один раз.
/lingo approveОдобряет ожидающее предложение перевода в PR.

Команда должна быть на отдельной строке. Glob-шаблоны сопоставляются только с файлами, которые также соответствуют настроенным исходным шаблонам files. Как и шаблоны в конфигурации, glob-шаблоны команды не могут начинаться с / и не могут содержать ...

Если glob-шаблоны файлов указаны явно, а --key не указан, /lingo translate <glob>... работает в режиме заполнения пропусков: создаёт только те целевые файлы, которых нет в ветке пул-реквеста. Добавьте --force, чтобы заново создать уже существующие целевые файлы.

Повторный перевод выбранных ключей#

Используйте --key, чтобы обновить выбранные ключи по именам, не заменяя остальные переводы, в том числе принятые правки в других ключах:

txt
/lingo translate locales/en.json --key "auth.login" --locales fr,es

Шаблоны ключей поддерживают точные совпадения, префиксы и glob-шаблоны:

ШаблонВыбранные ключи
auth.loginВыбирает ключ с именем auth.login и все вложенные ключи с этим префиксом.
authВыбирает auth и вложенные ключи, например auth.login и auth.logout.
auth.*Выбирает ключи по glob-шаблону, например auth.login и auth.logout.

Повторите --key, чтобы выбрать несколько шаблонов. Заключайте шаблоны ключей с пробелами в кавычки. Glob-шаблоны файлов и --locales сужают запрос. Если не указать glob-шаблоны файлов, будут выбраны все исходные файлы из настроек:

txt
/lingo translate --key "auth.*" --key "checkout.submit" --locales fr

Для перевода с ограничением по ключам нужен формат с именованными ключами и существующий перевод для каждой выбранной целевой локали. Форматы без именованных ключей и локали без существующих переводов пропускаются. Чтобы сначала создать недостающие целевые файлы, запустите /lingo translate <glob>... без --key. Если добавить --force в команду с ограничением по ключам, область видимости ключей не расширится, а остальные переводы не будут заменены.

Как задать контекст для отдельного запуска#

Добавьте --context, чтобы объяснить смысл выбранного ключа или дать рекомендации по тону и регистру букв:

txt
/lingo translate --key "keyname" --context "button label, keep sentence case"

Для --context требуется --key. Укажите контекст один раз: он применяется ко всем выбранным ключам и локалям в этом запуске. Контекст сохраняется вместе с запуском для повторных попыток и истории, но не меняет сохранённые правила и инструкции движка и не передаётся следующим запускам. Существующие правила глоссария, плейсхолдеров и формата вывода по-прежнему действуют.

Пишите команду в одну строку. Заключайте контекст с пробелами в одинарные или двойные кавычки. Также можно использовать --context="button label". Чтобы включить в текст кавычку того же типа, что и внешние, экранируйте её обратной косой чертой:

txt
/lingo translate --key "checkout.submit" --context "Use \"Save\" as a button label"

В контексте, заключённом в кавычки, декодируются только \\ и обратная косая черта перед кавычкой того же типа, что и внешние. Плейсхолдеры вроде $name и ${name}, последовательности вроде \n и знаки препинания остаются без изменений.

Поддерживаемые форматы#

GitHub App определяет эти форматы по расширению файла:

  • JSON (.json)
  • JSONC (.jsonc)
  • Markdown (.md)
  • MDX (.mdx)
  • Markdoc
  • Xcode String Catalog (.xcstrings)

Документы OpenAPI в YAML тоже поддерживаются, но автоматически не распознаются. Укажите "format": "yaml-openapi" в шаблоне файла:

json
{
  "files": [
    { "pattern": "openapi/en.yaml", "format": "yaml-openapi" }
  ]
}

Xcode String Catalogs#

Xcode String Catalog хранит все локали в одном файле .xcstrings — приложение переводит его на месте, без отдельного файла для каждой локали. Целевой путь совпадает с исходным: каждая целевая локаль записывается в тот же файл, рядом с исходным языком и уже переведёнными локалями. Укажите исходный шаблон прямо на каталог и задайте для sourceLocale язык разработки:

json
{
  "sourceLocale": "en",
  "targetLocales": ["es-MX", "fr-CA", "pt-BR"],
  "files": [{ "pattern": "**/*.xcstrings" }]
}

Крупные обновления#

Приложение может разбивать результаты перевода на несколько коммитов. Это происходит, если за один запуск нужно записать более 100 файлов в одном коммите или более 5 МБ содержимого переведённых файлов в одном коммите.

В этом случае в сообщениях коммитов будет указан номер пакета, например:

txt
feat: Lingo.dev translations (1/3)
feat: Lingo.dev translations (2/3)
feat: Lingo.dev translations (3/3)

Что происходит, если ничего не совпало#

Если .lingo/config.json отсутствует, приложение молча пропускает репозиторий. Когда конфигурация появляется, некорректная конфигурация приводит к ошибке в проверке, а в PR — к комментарию с ошибкой валидации.

Если ни один изменённый файл не соответствует вашим исходным шаблонам, приложение завершит работу без записи переводов. Для /lingo translate бот ответит коротким объяснением, например: нет подходящих файлов, нет подходящих локалей или все целевые файлы уже существуют.

При push, который добавляет .lingo/config.json, переводятся только те исходные файлы, которые соответствуют шаблонам и изменились в этом push. Для существующих исходных файлов без изменений нужно отдельно создать недостающие переводы. Чтобы создать для них недостающие целевые файлы, откройте пул-реквест из ветки в том же репозитории, а не из форка. Оставьте в пул-реквесте комментарий /lingo translate <glob>.

Что дальше#