Как локализовать приложение для iOS

Переведите каталоги строк Apple или ресурсы старого формата, сохранив локали в общем файле, а затем проверьте результат в Xcode и приложении.

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

Используйте формат, который проект уже загружает. Каталоги строк хранят несколько языков в одном файле .xcstrings, а ресурсы .strings и .stringsdict — в отдельных файлах для каждой локали. От этого зависит, куда записывается результат и что нужно защитить при обновлении.

Определите, какие ресурсы считать основными #

В проекте с каталогами строк определите язык разработки, поддерживаемые целевые языки и каталоги, которые загружает приложение. В Xcode 15 появился формат .xcstrings. Обычно такой каталог называется Localizable.xcstrings. Несколько каталогов могут разделять сообщения по функциям или пакетам. Включите все каталоги, которые используются на экране, который вы локализуете.

Для ресурсов старого формата определите нужные каталоги .lproj, таблицы строк и словари форм множественного числа. В Base.lproj могут храниться базовые ресурсы интерфейса, но само наличие этого каталога не указывает переводчику, какой исходный язык или таблицу строк использовать. Следите, чтобы настройка языка разработки проекта и конфигурация файлов соответствовали друг другу.

Перед переводом свяжите текст на экране с вызовами для получения локализованных строк. Перевод файлов не заменяет строки, заданные прямо в коде интерфейса, и не добавляет ресурсы в целевой объект Xcode. Сохраняйте комментарии, которые поясняют, кто говорит и на каком экране: они пригодятся при проверке. Текущий обработчик каталогов строк сохраняет эти комментарии, но не включает их в подсказки для единиц перевода. Поэтому контекст, необходимый для генерации, укажите в рекомендациях, которые поддерживает движок локализации.

Настройте общий каталог строк #

Установите актуальную версию CLI и выполните привязку из корня проекта:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'App/Localizable.xcstrings' --yes
lingo link

Для каталога по этому пути итоговый .lingo/config.json должен выглядеть так:

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

Используйте идентификаторы, созданные при привязке, а не копируйте значения-заглушки. Расширение определяет выбор xcode-xcstrings. Перевод для каждого целевого языка записывается в тот же каталог по тому же пути: новые записи локали добавляются, а исходный текст и другие локали сохраняются. Для этого формата с общим файлом отдельный targetPath недопустим.

Исходное значение хранится внутри общей структуры:

json
{
  "sourceLanguage": "en",
  "strings": {
    "Welcome": {
      "comment": "Greeting on the signed-in home screen",
      "localizations": {
        "en": { "stringUnit": { "state": "translated", "value": "Welcome" } }
      }
    }
  },
  "version": "1.0"
}

После перевода найдите записи запрошенных локалей рядом с en. Обработчик также поддерживает конечные значения исходных вариантов для форм множественного числа и типов устройств и пропускает записи с отметкой shouldTranslate: false. Если у записи нет исходной локализации, её ключ используется как исходный текст. Технический ключ не заменяет текст нужного сообщения. В разделе Каталоги строк Apple описаны эти правила выбора и объясняется, почему текущий исходный текст должен соответствовать существующему каталогу.

Храните файлы старого формата по отдельным путям #

В проекте с ресурсами старого формата используйте эти записи файлов вместо записи общего каталога:

json
[{ "pattern": "App/en.lproj/Localizable.strings" }, { "pattern": "App/en.lproj/Localizable.stringsdict" }]

Включайте только ресурсы, которые действительно есть в проекте. Расширения определяют выбор обработчиков. Результат перевода на испанский должен находиться в App/es.lproj/. Настройка языка разработки проекта должна соответствовать выбранному источнику.

Ключи строк и плейсхолдеры форматирования — часть правил, от которых зависит работа приложения. Сохраняйте %@, позиционные аргументы и типы, которые ожидает вызывающий код. В .stringsdict содержится структура переменных для форм множественного числа. Она должна соответствовать строке формата. Соблюдайте отдельные правила из разделов Строки Apple и Словари строк, а не рассматривайте эти файлы как произвольный XML или текст.

Переведите и проверьте результат слияния #

Перед заменой сохраните текущий каталог в системе контроля версий или сделайте отдельную копию. Чтобы защитить локальные правки, отправьте запрос без --wait и проверьте lingo pull --dry-run перед получением результата. Устраните расхождения, а не перезаписывайте файл принудительно. В отличие от pull, запись результата после ожидания не проверяет конфликты заново. См. Как сохранить проверенные переводы.

Для первого перевода с чистого состояния используйте следующую команду, только если каталог не будет меняться во время ожидания. Прежде чем добавлять локали в существующий проект, завершите обычные обновления исходного текста для текущих локалей, получите и проверьте результаты. Затем сохраняйте эту версию исходного текста без изменений, пока добавляете локали и заполняете недостающие переводы. Нужный порядок описан в разделе Как добавить язык:

bash
lingo push --backfill-missing --wait

Для общих каталогов работа планируется отдельно по каждой локали, даже если файл уже существует. Проверяйте записи запрошенных локалей, а не ищите новый файл. Первая обычная отправка может зафиксировать базовую версию исходного текста без перевода. После обычных изменений исходного текста используйте lingo push --wait. Если вы не дожидаетесь завершения, получите сохранённый результат с помощью lingo pull в том checkout, из которого отправляли запрос.

Чтобы исправить формулировку, измените запись целевого языка в Xcode. Команда CLI --force всё ещё может повторно использовать переводы из неизменённого каталога. Чтобы заново сгенерировать одну запись после изменения рекомендаций, следуйте инструкции по исправлению каталога: исходный текст и соседние переводы сохранятся.

lingo purge пропускает каталоги строк, потому что исходный текст и переводы хранятся по одному пути. Чтобы заново сгенерировать выбранный перевод, используйте рабочий процесс исправления каталога строк.

Проверьте результат в Xcode и на типичных экранах #

Откройте результат в Xcode и убедитесь, что каталог или файл старого формата включён в нужный целевой объект и пакет. Соберите проект с существующей схемой. Запустите конфигурацию с целевым языком и проверьте экран, где есть простая надпись, форматированное значение и вариант для формы множественного числа или типа устройства.

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

Проверки при сборке в Xcode могут выявить проблемы с ресурсами, а специалист по языку или подходящее измерение — проверить смысл. lingo check не подтверждает полноту .xcstrings или правильную работу форм множественного числа по правилам Apple.

Настройте автоматизацию так, чтобы сохранять общий файл #

Храните исходные тексты, принятые переводы, конфигурацию и .lingo/lock.json вместе. Для регулярной работы выберите GitHub App или средство запуска CI. Средство запуска само управляет аутентификацией, состоянием и записью результатов, которые можно проверить. Рассматривайте различия в каталоге строк как изменения общего файла: прежде чем принять их, определите версию исходного текста, изменённые и сохранённые локали.

В кроссплатформенных проектах используйте отдельные рабочие процессы для Android и Flutter, чтобы работать с квалификаторами XML и генерировать ARB. На каждой платформе всё равно нужно отдельно проверять загрузку ресурсов и отображение экранов.