Как локализовать приложение на Flutter

Переведите сообщения ARB, сгенерируйте ресурсы Flutter и проверьте экран в каждой целевой локали.

Инструменты локализации Flutter превращают сообщения ARB в методы, которые вызывают виджеты. Lingo.dev переводит эти ресурсы ARB, так что вы можете добавлять языки, сохраняя прежний сгенерированный API. Начните с одного экрана с приветствием и количеством элементов: так вы сможете заодно проверить текст, переменные и формы множественного числа.

Для этой инструкции проект должен уже загружать исходный ARB-файл с помощью генератора локализации Flutter. Оставьте существующие l10n.yaml, генератор и вызовы из виджетов без изменений. Здесь Lingo.dev переводит файлы, а Flutter по-прежнему выбирает локаль и выводит сообщения.

Добавьте к каждому сообщению нужную информацию #

Для исходного файла по пути lib/l10n/app_en.arb используйте, например, такой каталог:

json
{
  "@@locale": "en",
  "welcome": "Welcome, {name}",
  "@welcome": {
    "description": "Greeting on the signed-in account screen",
    "placeholders": { "name": { "type": "String" } }
  },
  "itemCount": "{count, plural, =0{No items} =1{One item} other{{count} items}}",
  "@itemCount": {
    "description": "Number of items in the cart",
    "placeholders": { "count": { "type": "int" } }
  }
}

Описание помогает переводчику понять, как используется сообщение. Определения плейсхолдеров сообщают Flutter, какие значения передаёт вызывающий код. Обработчик ARB переводит две строки сообщений, сохраняет метаданные и меняет значение существующего поля @@locale на целевую локаль.

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

В корневой папке проекта установите актуальную версию CLI и пройдите аутентификацию:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets de,fr --files 'lib/l10n/app_en.arb' --yes
lingo link

init записывает .lingo/config.json, а link выбирает организацию и движок локализации. Сохраните сгенерированные идентификаторы. Поля локализации должны выбирать только исходный файл:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    { "pattern": "lib/l10n/app_en.arb", "format": "flutter" }
  ]
}

Это фрагмент связанной конфигурации, который отвечает за локализацию. Он не заменяет идентификаторы организации и движка локализации. Расширение .arb также автоматически выбирает flutter. При такой структуре создаются app_de.arb и app_fr.arb. Убедитесь, что генератор проекта читает эти файлы. Для другой структуры задайте явный путь к целевому файлу.

Не используйте для исходных файлов шаблон вроде app_*.arb, который захватывает и переведённые каталоги. Для региональных локалей согласуйте написание имён файлов с конфигурацией проекта Flutter. Не рассчитывайте, что любая строка локали подойдёт для имени файла без изменений.

Переведите сообщения и сгенерируйте целевые ресурсы #

Если целевых файлов ещё нет, выполните:

sh
lingo push --backfill-missing --wait

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

Проверьте ключи, описания, имена и типы плейсхолдеров в целевых файлах, а также @@locale. Затем запустите генерацию локализации Flutter, анализ, тесты и сборку проекта. Прежде чем продолжить, исправьте некорректные выражения ICU, недостающие плейсхолдеры и несовместимые типы. Восстановление структуры ARB сохраняет метаданные, но не проверяет каждое переведённое сообщение на совместимость с генератором Flutter.

Откройте экран на немецком и французском. Передайте короткое и длинное имя, затем значения количества: 0, 1, 2 и число побольше. Прочитайте текст с формами множественного числа — недостаточно просто убедиться, что число появилось. В целевых языках могут понадобиться категории, которых нет в английском исходнике, поэтому проверьте все нужные формы. Проверьте выбор локали, переход к резервной локали, увеличение длины текста и, где это важно, направление письма. Форматы дат и чисел по-прежнему определяет Flutter во время выполнения.

Сохраняйте связь дальнейших обновлений с исходником #

Храните конфигурацию, исходник, принятые переводы и .lingo/lock.json вместе. После изменения исходного сообщения выполните lingo push --wait и проверьте его рядом с соседним сообщением, которое не менялось. Правка только описания сама по себе не создаёт новую задачу перевода текста сообщения. Если обновлённый контекст требует повторного перевода, используйте обновление с ограниченной областью.

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

Когда этот цикл заработает, используйте GitHub App или автоматизацию CI, чтобы повторять перевод и генерацию ресурсов перед проверкой. У нативных Android XML и ресурсов Apple другие требования к файлам и работе во время выполнения. В кроссплатформенном проекте обрабатывайте их отдельно от генерации ARB.