Как локализовать приложение на Flutter
Переведите сообщения ARB, сгенерируйте ресурсы Flutter и проверьте экран в каждой целевой локали.
Инструменты локализации Flutter превращают сообщения ARB в методы, которые вызывают виджеты. Lingo.dev переводит эти ресурсы ARB, так что вы можете добавлять языки, сохраняя прежний сгенерированный API. Начните с одного экрана с приветствием и количеством элементов: так вы сможете заодно проверить текст, переменные и формы множественного числа.
Для этой инструкции проект должен уже загружать исходный ARB-файл с помощью генератора локализации Flutter. Оставьте существующие l10n.yaml, генератор и вызовы из виджетов без изменений. Здесь Lingo.dev переводит файлы, а Flutter по-прежнему выбирает локаль и выводит сообщения.
Добавьте к каждому сообщению нужную информацию #
Для исходного файла по пути lib/l10n/app_en.arb используйте, например, такой каталог:
{
"@@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 и пройдите аутентификацию:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets de,fr --files 'lib/l10n/app_en.arb' --yes
lingo linkinit записывает .lingo/config.json, а link выбирает организацию и движок локализации. Сохраните сгенерированные идентификаторы. Поля локализации должны выбирать только исходный файл:
{
"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. Не рассчитывайте, что любая строка локали подойдёт для имени файла без изменений.
Переведите сообщения и сгенерируйте целевые ресурсы #
Если целевых файлов ещё нет, выполните:
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.