GitHub

Переводите контент репозитория с помощью GitHub App и проверяйте как изменения исходников, так и готовые переводы.

GitHub App от Lingo.dev включает переведённые файлы в историю изменений репозитория. Вы коммитите исходный контент и конфигурацию перевода. Приложение читает выбранные файлы, переводит их с помощью движка локализации и возвращает diff, который команда может проверить в GitHub.

В меню Studio 2.5 откройте Интеграции в разделе Studio 2.5, а не в разделе Настройки. Прежние ссылки для подключения и настройки работают как раньше.

При изменениях в ветке по умолчанию создаётся пул-реквест с переводом. Если включить обработку пул-реквестов, переводы будут добавляться в ветку соответствующего пул-реквеста. Эта страница начинается с рабочего процесса для ветки по умолчанию. Добавление перевода и решение о его слиянии рассматриваются отдельно. Чтобы запускать CLI на своём раннере, используйте инструкцию для GitHub Actions.

Чтобы агент для программирования мог подключиться к приложению, см. Настройка с помощью агента для программирования.

Подключите репозиторий и настройте перевод #

В Lingo.dev откройте подраздел Интеграции в разделе Настройки и выберите Подключить для GitHub. Свяжите установленное приложение со своей организацией и предоставьте доступ к репозиториям, которые нужно обрабатывать. Возможно, установку потребуется одобрить администратору организации в GitHub. Доступ к репозиториям определяется областью доступа, выбранной при установке.

Выберите доступный движок локализации в подключённой организации. Его конфигурация определяет модели, глоссарий, правила, голос бренда и применимые настройки проверки. Разрешения установленного приложения в GitHub дают доступ к работе с репозиторием, а разрешения в Lingo.dev — к использованию движка локализации.

Чтобы посмотреть данные об установке и состояние подключения, откройте подключение в подразделе Интеграции раздела Настройки. Кнопка Управлять в GitHub открывает настройки доступа установленного приложения к репозиториям. В Studio выберите репозиторий в разделе Подключённые. Затем отслеживайте конкретное изменение исходников в разделе Запуски рабочих процессов, сверяясь с проверкой и коммитами в GitHub.

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

Создайте .lingo/config.json в корне репозитория. В этом примере выбираются английские каталоги JSON в locales/en/, а французские файлы создаются по соответствующим путям locales/fr/. Замените eng_example на ИД своего движка локализации:

json
{
  "engineId": "eng_example",
  "sourceLocale": "en",
  "targetLocales": ["fr"],
  "files": [
    {
      "pattern": "locales/en/**/*.json",
      "format": "json"
    }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": false }
    },
    "safety": { "requireApproval": true }
  }
}

Выполните один запуск и проверьте результат #

В этом примере перед началом перевода требуется одобрение. Чтобы протестировать настройку:

  1. Закоммитьте конфигурацию и небольшое изменение исходников в ветку по умолчанию, например одно сообщение в locales/en/checkout.json.
  2. Откройте ожидающую одобрения проверку в GitHub и одобрите запуск. Если одобрение недоступно, посмотрите правила одобрения.
  3. Откройте пул-реквест с переводом, который создало или обновило приложение. Найдите locales/fr/checkout.json и сравните изменённое сообщение с исходным.
  4. Соберите или запустите приложение с переведённым файлом. Проверьте формулировки, переменные и выбор локали. Затем проверьте и слейте пул-реквест по обычным правилам работы с репозиторием.

Одобрение на шаге 2 разрешает перевод и связанное с ним использование ресурсов. Оно не подтверждает итоговые формулировки и не выполняет слияние пул-реквеста. Если результата нет, найдите незавершённый этап с помощью раздела о проверке и восстановлении.

Настройте конфигурацию под структуру файлов #

Шаблоны исходников должны выбирать только исходные файлы. Например, locales/en/**/*.json исключает сгенерированные французские файлы из последующего поиска исходников. Шаблоны задаются относительно корня репозитория. Абсолютные пути и .. не допускаются. В каждой записи о файлах нужен pattern или список include. Конфигурация поддерживает до 100 записей о файлах и 50 уникальных целевых локалей.

По умолчанию место для целевых файлов определяет исходная локаль в пути. Если в путях нет локали, задайте targetPath: [locale] подставляет целевую локаль, а [path] — исходный путь без необязательного префикса sourceRoot. Например, sourceRoot: "content" и targetPath: "translations/[locale]/[path]" превращают путь content/help/start.md в translations/fr/help/start.md для французского языка. Шаблону на основе glob нужны оба заполнителя. sourceRoot требует targetPath и должен быть префиксом выбранных исходных путей. Форматы, где все локали хранятся в одном файле, например каталоги строк Xcode и CSV, не поддерживают шаблоны выходных путей, так как переводы остаются в исходном файле.

Используйте localeFormat, если приложению нужны обозначения локалей в путях в формате BCP-47, с подчёркиваниями или в формате Android. Для ресурсов Android по умолчанию используются квалификаторы Android. Прежде чем добавлять другие локали, убедитесь, что первый путь вывода подходит загрузчику приложения.

Выберите, когда запускать перевод и куда его записывать #

Обработка пушей в ветку по умолчанию включена по умолчанию. Обработка пул-реквестов отключена — её нужно явно включить в конфигурации.

Прежде чем включать обработку пул-реквестов, закоммитьте корректный .lingo/config.json в ветку по умолчанию. Приложение берёт ИД движка, github.workflows и github.safety из этой доверенной ревизии ветки по умолчанию. Изменения этих настроек в пул-реквесте не разрешают использовать другой движок и не меняют политику одобрения для запуска этого пул-реквеста. Исходная локаль, выбор файлов и целевые локали берутся из переводимой ревизии.

ТриггерКуда попадает перевод
Пуш в ветку по умолчаниюСоздаёт коммиты в lingo/translations/<default-branch> и открывает или обновляет пул-реквест в ветку по умолчанию.
Включённый рабочий процесс для пул-реквестовЗаписывает результат перевода коммитами в головную ветку пул-реквеста.
Команда перевода в пул-реквестеЗаписывает запрошенный результат перевода в головную ветку этого пул-реквеста.

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

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

Настройте одобрение до начала расходов на запуск #

По умолчанию github.safety.requireApproval имеет значение false. Задайте true в конфигурации ветки по умолчанию, если запуск нужно разрешить до начала перевода. Для пушей в ветку по умолчанию в проверке появляются кнопки Одобрить и Отклонить. Для пул-реквестов приложение публикует комментарий, на который специалист с правом проверки отвечает командой /lingo approve.

Если одобрение обязательно, а проверку для аудита создать не удалось, рабочий процесс блокируется. Прежде чем повторять попытку одобрения, устраните проблему с созданием проверки или доступом.

Любая команда /lingo translate — с glob-шаблонами файлов или без них — разрешает запрошенную работу без этого предварительного одобрения. Перед публикацией команды проверьте, какие файлы и локали она охватывает.

Запускайте команды в пул-реквесте #

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

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

Без glob-шаблонов и --key команда работает с файлами, изменёнными в пул-реквесте, поэтому выполняется, даже если обработка пул-реквестов отключена в конфигурации. С glob-шаблонами она работает с файлами в ветке независимо от изменений в пул-реквесте. Glob-шаблоны задаются относительно корня репозитория, учитывают регистр и охватывают только файлы, выбранные настроенным pattern. --locales принимает список через запятую. Коды сопоставляются с настроенными целевыми локалями без учёта регистра. В ответе отмечаются коды, которые не совпали ни с одной из них.

Подробнее о командах с glob-шаблонами и ключами — в разделах Заполните пропуски для выбранного файла или локали и Повторно переведите ключи с контекстом.

Заполните пропуски для выбранного файла или локали #

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

text
/lingo translate locales/en/checkout.json --locales fr

Для форматов с отдельным файлом на каждую локаль эта команда создаёт недостающий французский целевой файл. Она не заполняет недостающие ключи в существующем целевом файле. Если добавить --force, выбранный результат будет создан заново без повторного использования существующего перевода. При этом принятые правки людей могут быть заменены. Ограничьте выбор нужными файлами и локалями, а затем проверьте итоговый diff.

Каталоги строк Xcode и файлы CSV хранят исходный текст и переводы в одном файле. Обычная команда с заданной областью заполняет недостающие записи локалей и сохраняет существующие, в том числе те, у которых изменился исходный текст. Чтобы перевести изменения исходного текста в пул-реквесте, используйте /lingo translate без шаблона файлов. При этом существующие переводы изменённых записей могут быть заменены, включая ручные правки. Если вы хотите заново сгенерировать существующие переводы, добавьте --force и выберите конкретные файлы и локали. Принудительная команда для приложения пересоздаёт выбранный контент, а локали за пределами запрошенной области сохраняются. Чтобы обновить переводы через CLI, следуйте инструкции по исправлению для каталогов строк или CSV.

Повторно переведите ключи с контекстом #

Используйте --key, чтобы повторно перевести выбранные именованные ключи в существующих переводах. Для файлов JSON и JSONC добавьте --context, чтобы объяснить их смысл или дать указания по тону и регистру для этого запуска:

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

Для --context нужен --key. Укажите контекст один раз — он применяется ко всем выбранным ключам и локалям в файлах JSON и JSONC. Другие подходящие форматы переводятся без этого контекста. Для нескольких шаблонов повторите --key. Чтобы сузить запрос, используйте glob-шаблоны файлов или --locales. Без glob-шаблонов файлов команда выбирает все настроенные исходные файлы. Ключи сопоставляются точно, по префиксу или по glob-шаблону. Остальные переводы сохраняются. Форматы без именованных ключей и локали без существующих переводов пропускаются.

Команды GitHub App для работы с ключами также заново создают выбранные неизменённые строки в YAML и YAML с локалью в корне. В рабочем процессе CLI с областью видимости ключей для этих форматов действуют другие правила повторного использования базовых переводов.

Пишите команду в одну строку. Заключайте контекст с пробелами в одинарные или двойные кавычки. --context="button label" тоже подходит. Чтобы включить в текст такую же кавычку, экранируйте её обратной косой чертой, например --context "Use \"Save\" as a button label". Контекст сохраняется вместе с запуском для повторных попыток и истории, но не становится инструкцией движка и не передаётся последующим запускам. Правила глоссария, заполнителей и формата вывода продолжают действовать.

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

Защитите контент, который не должен меняться #

Приложение поддерживает структурированные каталоги, документы семейства Markdown, HTML, субтитры, обычный текст, таблицы CSV, файлы свойств Java и ресурсы платформ. Обработчики для каждого формата описаны в разделе Форматы. Payload недоступен для выбора в качестве формата файлов GitHub.

Выбирайте HTML с помощью шаблонов, например pages/en/**/*.html и pages/en/**/*.htm. По обоим расширениям автоматически определяется html. Можно также явно указать "format": "html". Вывод HTML вставляет переведённый текст и выбранные атрибуты в исходный файл, сохраняя остальную разметку, комментарии и форматирование. Если элемент <html> явно присутствует, в его lang записывается целевая локаль. К фрагментам не добавляются обёртки документа.

Чтобы выбрать обычные текстовые файлы, используйте шаблон, который заканчивается на .txt, например metadata/en/*.txt, или укажите "format": "txt". Файл .txt относится только к такой записи, а запись с "format": "txt" выбирает только файлы .txt. Поэтому общий шаблон вроде docs/en/**/* пропускает LICENSE.txt, а общая запись txt пропускает изображения рядом с текстом. Обработчик Обычный текст переводит каждую строку, сохраняя её на месте.

Файлы CSV выбираются так же: с помощью шаблона, который заканчивается на .csv, например i18n/strings.csv, или с помощью "format": "csv". Файл .csv относится только к такой записи, а запись с "format": "csv" выбирает только файлы .csv. CSV заполняет столбцы целевых локалей прямо в исходном файле.

Выбирайте файлы свойств Java так же: укажите шаблон, который заканчивается на .properties, например src/main/resources/messages_en.properties, или используйте "format": "properties", чтобы общий шаблон вроде src/main/resources/**/* пропускал application.properties. Для исходного файла messages_en.properties создаются целевые файлы с именами вроде messages_de.properties. Обработчик Свойства Java переводит каждое значение прямо в файле, сохраняет комментарии и оформление и сопоставляет lockedKeys, preservedKeys, ignoredKeys и lockedPatterns так же, как прежняя версия CLI.

Для документа выберите поля frontmatter и свойства компонентов с переводимым текстом. Для каталога в формате, подобном JSON, используйте заблокированные пути для копирования исходных значений, сохраняемые пути — для сохранения существующих целевых значений, а игнорируемые — для исключения значений из вывода. Так текст, идентификаторы и ссылки могут храниться в одном каталоге, не требуя одинакового подхода к переводу. Внедрение локали записывает целевую локаль в настроенное поле вывода.

Параметры записи о файлах #

Размещайте следующие поля прямо в объекте массива files в .lingo/config.json, а не внутри options. Приложение строго проверяет корневые поля, записи о файлах, настройки GitHub, правила компонентов и объекты внедрения локали. Необязательный раздел i18n оно игнорирует и допускает в нём дополнительные поля. Машиночитаемая схема доступна по адресу GET https://api.lingo.dev/github-app/schema.json.

ПолеДопустимый видЗначение по умолчанию или область действия
pattern / includeНепустая строка с путём относительно корня репозитория / непустой массив таких строк.Требуется хотя бы одно поле. Указанный include имеет приоритет над pattern. Шаблоны не могут начинаться с / или содержать ...
excludeМассив непустых шаблонов относительно корня репозитория.Необязательно. Применяется к этой записи.
formatСтрока с указанием формата, включая "html".Если не указано, определяется автоматически. .html и .htm выбирают HTML. Payload выбрать нельзя. Это не объект {type,options} документа.
localeFormat"bcp47", "underscore" или "android".Обычно по умолчанию используется BCP-47. Для формата Android применяется запись локалей Android.
targetPath, sourceRootНепустые строки с путями относительно корня репозитория.Необязательно. Действуют описанные выше правила шаблонов вывода.
lockedKeys, preservedKeys, ignoredKeysМассивы непустых строк с путями к ключам в точечной или скобочной записи.Если не указано, используется []. Поведение зависит от обработчика формата. Это не параметры JSONPath для исходного документа.
injectLocaleЛогическое значение или { "enabled": boolean, "key"?: nonempty string }.Если не указано, внедрение отключено. При включённом внедрении без key по умолчанию используется language.
translateFrontmatterFieldsМассив непустых строк.Для документов семейства Markdown без этого поля выбираются title, description. [] не выбирает ничего.
translateComponentPropsМассив непустых строк с именами свойств или объектов с необязательным component и обязательным непустым массивом props.component — непустая строка или непустой массив непустых строк. Без него фильтр по имени не применяется. Значение поля по умолчанию — [].

Например, запись JSON может содержать "lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" } вместе с pattern. В записи Markdoc можно выбрать заголовок компонента с помощью "translateComponentProps": [{ "component": "Callout", "props": ["title"] }]. CLI принимает некоторые пустые значения и лишь предупреждает о некоторых неизвестных полях, которые приложение отклоняет. Проверяйте конфигурацию приложения по этой схеме.

Проверьте первый регулярный запуск и восстановите работу #

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

Что вы видитеЧто проверить перед новым запросом
Конфигурация ветки по умолчанию отсутствует, некорректна или отключает рабочий процессНи проверка, ни комментарий в GitHub не публикуются. Исправьте и закоммитьте .lingo/config.json в ветке по умолчанию, указав нужные настройки рабочего процесса.
Проверки ветки по умолчанию пройдены, но конфигурация ревизии исходников отсутствует или некорректнаЗапуск сообщает об ошибке проверки и, для соответствующего сценария пул-реквеста, публикует комментарий. Исправьте указанную ошибку конфигурации исходников.
Нет подходящих изменений исходников или нужные переводы уже естьПроверьте шаблоны и наличие переводов для выбранного контента. Запуск без изменений — не сбой перевода.
Ранее пропущенное изменение исходников в пул-реквестеПри синхронизации пул-реквеста рабочий процесс может сравнить исходники с базовой версией пул-реквеста и обработать изменения, пропущенные при сравнении с непосредственно предыдущей версией исходников. Проверяйте базовые и текущие исходники вместе с целевыми файлами.
Целевой файл в пул-реквесте отредактирован человекомДля форматов с отдельными целевыми файлами обычная обработка изменений пул-реквеста защищает целевой файл, изменённый относительно базовой версии, если автор последнего коммита в нём — не бот. Проверьте эту правку, прежде чем считать пропущенный результат невыполненной работой.
Часть коммитов создана до последующего сбояРезультат может записываться коммитами по частям. К одному запуску может относиться несколько коммитов. Сбой при обработке следующей части не отменяет предыдущие успешные коммиты. Проверяйте записанные файлы и оставшиеся ошибки по отдельности.

Результат группируется в коммиты с ограничением в 100 файлов и порогом группировки 5 МиБ. При последующем сбое предыдущие коммиты могут сохраниться. Прежде чем повторять или откатывать запуск, проверьте записанные файлы и оставшиеся ошибки.

Чтобы остановить регулярную обработку, отключите соответствующие триггеры. Если приложению больше не нужны права на репозиторий, отзовите доступ к нему или удалите приложение в GitHub. Существующие коммиты, принятые пул-реквесты и данные о прошлом использовании сохранятся. Сохраните или откатите добавленный контент по обычным правилам работы с репозиторием.

Собирайте данные об активности в Radar #

Подключение также передаёт в Radar данные об активности коммитов GitHub. В разделе Сбор переводов для измерений описано, как настроить события и импортировать историю провайдера перед измерением по историческим данным.