Области перевода
Выбирайте файлы и стабильные ключи, отдельно управляя инкрементальными обновлениями, охватом целевых локалей и принудительным обновлением переводов.
Изменения в локализации могут затрагивать файл, язык или набор сообщений. CLI выбирает их по-разному: конфигурация проекта задаёт файлы и целевые локали, позиционные шаблоны сужают набор файлов и меняют план обработки, а --key выбирает сообщения по стабильному ключу.
Выбор файлов меняет план #
lingo push 'locales/en.json' --waitШаблон сужает набор исходных файлов, заданных в конфигурации. Для формата с отдельными файлами переводов эта команда создаёт недостающие целевые файлы и не меняет существующие, даже если исходный текст изменился. Если часть настроенных локалей не попадает в задание, команда сохраняет существующую базовую версию исходного текста, чтобы следующий обычный push мог обработать эти правки. Если базовой версии ещё нет, команда может её создать.
Для обычных правок исходного текста используйте lingo push --wait без дополнительных параметров. Чтобы целиком заменить файл в форматах с отдельными файлами переводов, задайте область обработки позиционным шаблоном вместе с --force. Учтите: принудительная замена отбрасывает контекст существующего перевода. Каталоги XCStrings при этом могут повторно использовать встроенные переводы. См. обновление каталогов. Целевые локали всегда берутся из targetLocales. У push нет флагов --locale и --target-locale.
Обновление по стабильным ключам #
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --waitЧтобы выбрать несколько ключей или групп ключей, повторите --key. Ключ — это путь с точками или скобками, например checkout.title или items[0].title. Выбор объекта включает все строки внутри него. Поэтому auth.login включает auth.login.title, но не auth.login_url. * обозначает один целый сегмент, а [] — каждый элемент массива. Частичные подстановки, например auth.log*, не допускаются. Шаблон, начинающийся с $. или $[, передаётся как запрос JSONPath. Заключайте шаблоны с подстановочными знаками в кавычки.
Шаблоны с /, написанные для прежней версии CLI, тоже работают. Шаблон, содержащий /, разделяется только по /, а каждое имя обрабатывается целиком: auth/login выбирает те же ключи, что и auth.login, а common/error.message выбирает ключ error.message внутри common. Имена с процентным кодированием, например legal/Terms%20of%20use, декодируются. Шаблон без / считается путём с точками и не декодируется, поэтому отдельное закодированное имя записывайте как JSONPath, например $['Terms of use']. Так как все шаблоны с / обрабатываются именно так, для ключа с / в имени нужен JSONPath, например $.routes['/about'].title. В этой форме * обозначает одно целое имя, а * в конце, как в auth/*, выбирает значения непосредственно внутри auth, но не вложенные объекты и массивы — как и в прежней версии CLI. /** в конце охватывает всё внутри предшествующего имени: auth/** равнозначно auth, а auth/*/** также охватывает объекты и массивы внутри auth, которые не включает auth/*. Число, например items/0, выбирает элемент массива или ключ объекта "0" — в зависимости от структуры документа. Подстановочные шаблоны внутри имени, ** не в конце, скобки и пустые имена, например a//b, не допускаются.
| Форматы | область видимости ключей |
|---|---|
| JSON/JSONC, PHP, TypeScript, файлы свойств Java | Заново создаёт выбранные строки, даже если исходные значения не изменились. |
| YAML/YAML с корневым ключом | Выбирает стабильные ключи, но для выбранных строк с неизменившимся исходным текстом может повторно использовать существующие переводы. |
| gettext, ARB, Apple strings, XCStrings, CSV, Android, XLIFF | Не поддерживается. --key останавливает push с ошибкой. |
| Markdown, MDX, Markdoc, HTML, OpenAPI YAML, SubRip, обычный текст, Apple stringsdict | Нет стабильных ключей. Пропускаются с сообщением. |
Для обновления по ключам нужны существующие целевые файлы. Недостающие локали и форматы без стабильных ключей пропускаются с сообщениями, а не создаются с нуля. Дозаполнение создаёт недостающие обычные файлы, но не заполняет пропуски внутри существующих. Добавление --force не меняет планирование по ключам и не мешает повторно использовать переводы YAML.
Обновление по ключам не меняет базовую версию всего исходного текста — независимо от того, забирает ли результат push --wait или отдельный pull. Поэтому ещё не обработанные обычные правки исходного текста попадут в следующий обычный push.
Обновление после изменения рекомендаций #
Правки глоссария или правил движка локализации не меняют байты исходного файла. Поэтому обычный push может ничего не сделать. Для JSON, JSONC, TypeScript и PHP выберите затронутые стабильные ключи. Для YAML внесите точечную правку прямо в целевой файл или сохраните принятые переводы и заново создайте их с помощью --force для выбранных файлов целиком, без --key. Проверьте весь полученный файл: такая замена может изменить и соседние сообщения. Параметры управления ключами определяют, какие исходные или целевые значения сохраняются при пересборке, но не задают, что обрабатывать.
Для масштабного изменения выберите небольшую область, которую будет удобно проверить и восстановить, а затем оцените её перед отправкой. При оценке загружаются все необходимые файлы и составляется план обработки, но задание на перевод не создаётся.
Как заново перевести одну локаль #
Если в проекте для каждого языка используется отдельный файл, удалите целевые файлы нужного языка и создайте недостающие с помощью дозаполнения. Сначала завершите отложенные обновления исходного текста и сохраните принятые переводы. Очистка с фильтром сохраняет базовые версии исходного текста и записи Lockfile для других языков.
Для исходного файла, заданного в конфигурации по пути locales/en.json, предварительно проверьте удаление французского целевого файла:
lingo purge --locale fr --file locales/en.jsonПроверьте выведенные пути. Если это нужные целевые файлы, подтвердите удаление и создайте недостающие переводы:
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --waitЕсли в конфигурации используются подстановочные шаблоны, например locales/en/*.json, передайте конкретные пути исходных файлов, повторив параметр --file для каждого пути в обеих командах purge. Сама команда purge не раскрывает такие шаблоны. Укажите все исходные файлы, для которых нужно заново создать французский перевод. Перед дозаполнением убедитесь, что другие целевые файлы на месте: дозаполнение создаёт все недостающие целевые файлы, заданные в конфигурации.
После завершения проверьте французский перевод и добавьте его в коммит вместе с обновлённым Lockfile. Существующие целевые файлы других языков останутся без изменений. Правила выбора см. в разделе Очистка. Этот способ не подходит для каталогов XCStrings, где исходный текст и все целевые локали хранятся в одном файле.