GitHub App
GitHub App от Lingo.dev настраивает непрерывную локализацию репозитория с помощью .lingo/config.json.
Что понадобится#
Перед установкой приложения убедитесь, что у вас есть:
- Организация в Lingo.dev с включённой интеграцией с GitHub
- Движок локализации в этой организации
- Права администратора в организации GitHub или в репозитории, который вы хотите подключить
Если вы не администратор организации GitHub, вместо установки можно отправить запрос. Администратор организации GitHub должен одобрить его, прежде чем Lingo.dev получит доступ к выбранным репозиториям.
Установите приложение GitHub#
- В Lingo.dev откройте свою организацию.
- Перейдите в Studio > All integrations.
- На карточке GitHub выберите Install on GitHub.
- В GitHub выберите аккаунт или организацию, в которую нужно установить приложение.
- Выберите All repositories или Only select repositories.
- Нажмите Install.
GitHub вернёт вас в Lingo.dev, на экран Подключить GitHub:
- Выберите организацию Lingo.dev, через которую этот аккаунт GitHub выполняет локализацию. По умолчанию выбрана последняя открытая организация.
- Нажмите Подключить.
- Когда появится сообщение 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 в репозитории, где установлено приложение:
{
"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. Выполните команды по порядку:
- Выполните
npx @lingo.dev/cli init, чтобы записать исходную локаль, целевые локали и шаблоны файлов в.lingo/config.json. - Выполните
npx @lingo.dev/cli login, чтобы войти и сохранить учётные данные локально в~/.lingo/credentials.json. - Выполните
npx @lingo.dev/cli link, чтобы выбрать организацию и движок. Команда добавитorgIdиengineIdв.lingo/config.json.
Команда init не записывает раздел github. Если этот раздел вам нужен, скопируйте его из примера выше. См. краткое руководство по CLI.
Шаблоны файлов#
Шаблоны files указывают на исходные файлы, то есть файлы локали по умолчанию. Приложение сверяет изменённые файлы с этими шаблонами и обрабатывает только поддерживаемые исходные файлы, которые им соответствуют.
Шаблоны задаются относительно репозитория, чувствительны к регистру и могут использовать:
*— для совпадения внутри одного сегмента пути**/— для совпадения на любой глубине директорий
Шаблоны не могут начинаться с / и не могут содержать ...
{
"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 или вместо него. |
translateFrontmatterFields | Markdown, MDX, Markdoc | Ключи frontmatter, которые нужно переводить. По умолчанию используются title и description. |
translateComponentProps | MDX, Markdoc | Свойства компонентов MDX и атрибуты тегов Markdoc, которые нужно переводить. |
lockedKeys | JSON, JSONC | Пути ключей, для которых сохраняется исходное значение без перевода. |
preservedKeys | JSON, JSONC | Пути ключей, для которых сохраняется текущее целевое значение без повторного перевода. |
injectLocale | JSON, JSONC | Записывает код целевой локали в выходной файл по указанному ключу (по умолчанию language). |
Записи translateComponentProps — это либо имя свойства, которое применяется к этому свойству в любом компоненте или теге, либо объект, который ограничивает свойства указанными компонентами или тегами:
{
"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.md | es | docs/es/guide.md |
docs/en-US/guide.md | fr-FR | docs/fr-FR/guide.md |
locales/en.json | de | locales/de.json |
README.md | es | es/README.md |
Localizable.xcstrings | es-MX | Localizable.xcstrings (тот же файл) |
Используйте полное имя директории или файла как код локали. Например, если исходные файлы находятся в docs/en-US/, укажите "sourceLocale": "en-US", а не "en". Если исходные строки находятся в messages/en.json, укажите "sourceLocale": "en".
Если исходный путь содержит директорию локали, приложение заменяет эту директорию. Если исходный путь — это файл с именем локали, приложение заменяет имя файла. Если ни один из этих вариантов не подходит, приложение поместит переведённый файл в новую директорию целевой локали рядом с исходным файлом.
String Catalogs — исключение из этого правила. Один файл .xcstrings хранит все локали, поэтому целевой путь совпадает с исходным: приложение записывает каждую локаль в тот же файл, не создавая ни папки локали, ни отдельного файла.
Рабочие процессы#
Push в ветку по умолчанию#
Когда подходящий исходный файл добавляется или изменяется в ветке по умолчанию, приложение переводит его и коммитит локализованные файлы в:
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 приложение публикует комментарий с предложением перевода; ответьте с помощью:
/lingo approveКоманды /lingo translate с ограниченной областью действия не требуют этого этапа одобрения.
Ручная команда для PR#
Используйте /lingo в комментарии к пул-реквесту, чтобы перевести изменения в исходных файлах, создать недостающие целевые файлы или повторно перевести выбранные ключи.
Переведите изменения в исходных файлах пул-реквеста, сохранив переводы там, где исходный текст не изменился:
/lingo translateЧтобы создать недостающие целевые файлы, укажите glob-шаблоны файлов:
/lingo translate docs/en/**/*.md/lingo translate docs/en/**/*.mdx --locales fr,es/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, чтобы обновить выбранные ключи по именам, не заменяя остальные переводы, в том числе принятые правки в других ключах:
/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-шаблоны файлов, будут выбраны все исходные файлы из настроек:
/lingo translate --key "auth.*" --key "checkout.submit" --locales frДля перевода с ограничением по ключам нужен формат с именованными ключами и существующий перевод для каждой выбранной целевой локали. Форматы без именованных ключей и локали без существующих переводов пропускаются. Чтобы сначала создать недостающие целевые файлы, запустите /lingo translate <glob>... без --key. Если добавить --force в команду с ограничением по ключам, область видимости ключей не расширится, а остальные переводы не будут заменены.
Как задать контекст для отдельного запуска#
Добавьте --context, чтобы объяснить смысл выбранного ключа или дать рекомендации по тону и регистру букв:
/lingo translate --key "keyname" --context "button label, keep sentence case"Для --context требуется --key. Укажите контекст один раз: он применяется ко всем выбранным ключам и локалям в этом запуске. Контекст сохраняется вместе с запуском для повторных попыток и истории, но не меняет сохранённые правила и инструкции движка и не передаётся следующим запускам. Существующие правила глоссария, плейсхолдеров и формата вывода по-прежнему действуют.
Пишите команду в одну строку. Заключайте контекст с пробелами в одинарные или двойные кавычки. Также можно использовать --context="button label". Чтобы включить в текст кавычку того же типа, что и внешние, экранируйте её обратной косой чертой:
/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" в шаблоне файла:
{
"files": [
{ "pattern": "openapi/en.yaml", "format": "yaml-openapi" }
]
}Xcode String Catalogs#
Xcode String Catalog хранит все локали в одном файле .xcstrings — приложение переводит его на месте, без отдельного файла для каждой локали. Целевой путь совпадает с исходным: каждая целевая локаль записывается в тот же файл, рядом с исходным языком и уже переведёнными локалями. Укажите исходный шаблон прямо на каталог и задайте для sourceLocale язык разработки:
{
"sourceLocale": "en",
"targetLocales": ["es-MX", "fr-CA", "pt-BR"],
"files": [{ "pattern": "**/*.xcstrings" }]
}Крупные обновления#
Приложение может разбивать результаты перевода на несколько коммитов. Это происходит, если за один запуск нужно записать более 100 файлов в одном коммите или более 5 МБ содержимого переведённых файлов в одном коммите.
В этом случае в сообщениях коммитов будет указан номер пакета, например:
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>.