Локализация iOS-приложения через Xcode String Catalogs

Lingo.dev CLI переводит Xcode String Catalogs (.xcstrings) через настроенный движок локализации. String Catalogs — это современный формат локализации от Apple, представленный в Xcode 15, где все языки хранятся в одном JSON-файле. CLI изменяет этот файл напрямую — отдельные папки для каждой локали не нужны.

Это руководство проведёт вас через полную локализацию iOS-приложения: настройка CLI, перевод на локальной машине и автоматизация через GitHub App, чтобы переводы выходили с каждым пушем.

Как работают String Catalogs#

До Xcode 15 локализация iOS требовала поддерживать отдельные файлы .strings и .stringsdict в каталогах [locale].lproj/. String Catalogs заменяют всё это одним файлом Localizable.xcstrings, который Xcode поддерживает автоматически.

Когда вы помечаете строку как локализуемую в SwiftUI или UIKit, Xcode обнаруживает её во время сборки и добавляет запись в String Catalog. В каждой записи хранится исходная строка, её переводы для всех настроенных локалей и необязательное поле комментария, которое даёт переводчикам дополнительный контекст.

CLI определяет формат .xcstrings по расширению файла, разбирает JSON-структуру, переводит каждую запись через движок локализации и записывает результаты обратно в тот же файл — комментарии, правила множественного числа и метаданные сохраняются.

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

node -v

Установка и конфигурация CLI#

Установите CLI, пройдите аутентификацию и настройте проект. Полное пошаговое руководство — в разделе Быстрый старт.

npm install -g @lingo.dev/cli
lingo login

Запустите lingo init в корне проекта и ответьте на вопросы (исходная локаль, целевые локали и шаблон пути к вашему String Catalog), затем lingo link, чтобы привязать проект к организации и движку. В итоге будет создан файл .lingo/config.json:

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "MyApp/Localizable.xcstrings" }]
}

Зафиксируйте .lingo/config.json — это источник истины о том, что переводится. Формат .xcstrings определяется по расширению файла. Поскольку String Catalogs хранят все локали в одном файле, плейсхолдер локали в шаблоне не нужен: CLI читает записи исходного языка и записывает все целевые языки обратно в тот же файл. Полная схема — в справочнике по конфигурации.

{
  "files": [
    { "pattern": "MyApp/Localizable.xcstrings" },
    { "pattern": "MyAppWidgets/Localizable.xcstrings" }
  ]
}

Локальный перевод#

Запустите первый перевод из корня проекта:

lingo push --backfill-missing

CLI читает ваш String Catalog, переводит все недостающие записи через движок локализации, ждёт завершения и записывает результаты обратно в файл .xcstrings. Откройте его в Xcode — переводы будут заполнены для каждой настроенной локали.

После редактирования исходных строк обычный lingo push переводит только изменения — записи, исходный текст которых не изменился, пропускаются на стороне сервера и отслеживаются через lockfile:

lingo push

Заметки для переводчиков#

String Catalogs поддерживают поле комментария для каждой записи, и CLI включает его в запросы на перевод. Эти комментарии дают контекст движку локализации: помогают снять неоднозначность терминов, задать нужный тон или объяснить, где строка отображается в интерфейсе.

В Xcode выберите строку в редакторе String Catalog и добавьте комментарий в панели инспектора. Комментарий сохраняется в JSON .xcstrings:

{
  "sourceLanguage": "en",
  "strings": {
    "Set": {
      "comment": "Refers to a collection of items, not the verb",
      "localizations": { }
    }
  }
}

CLI отправляет этот комментарий вместе со строкой, помогая модели выбрать правильную интерпретацию. Без контекста "Set" во многих языках может переводиться как глагол — комментарий снимает эту неоднозначность. Больше примеров — в разделе Translator Notes.

Множественное число#

String Catalogs изначально поддерживают формы множественного числа на основе CLDR plural rules. Когда вы задаёте вариант множественного числа в Xcode, String Catalog сохраняет правила для каждой категории множественного числа (zero, one, two, few, many, other), которая нужна целевому языку.

CLI сохраняет эту структуру при переводе и создаёт правильные категории множественного числа для каждой целевой локали. В английском их две (one и other), в арабском — шесть, в польском — четыре, а в японском — одна. Движок локализации учитывает эти различия автоматически.

Автоматизация через GitHub App#

Установите GitHub App Lingo.dev в репозиторий для непрерывной локализации — без CI-раннера, секрета с API-ключом и lockfile. После установки и привязки к .lingo/config.json (с его engineId) он автоматически реагирует на пуши и пул-реквесты: находит изменённые исходные строки, переводит их через ваш движок и коммитит обновлённый .xcstrings в ветку или открывает пул-реквест.

Проверка перед деплоем#

Используйте lingo check как условие деплоя, чтобы непереведённые строки не попали в продакшен. Команда сообщает об отсутствующих или устаревших переводах и завершается с ненулевым кодом, если работа ещё не завершена:

lingo check

Добавьте её отдельным шагом CI перед сборкой.

Что дальше#