Локализация Flutter: файлы ARB, intl и gen-l10n

Используйте один генератор локализации и явно укажите расположение его входных и выходных файлов. В примере ниже предполагается существующее приложение Flutter со своими ограничениями SDK и обычной конфигурацией проекта.

Добавьте нужные записи в pubspec.yaml; не дублируйте разделы dependencies и flutter:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

Установите зависимости командой flutter pub get. Запись intl: any соответствует официальному шаблону настройки и позволяет механизму разрешения зависимостей выбрать версию, совместимую с Flutter SDK; сохраняйте lock-файл приложения и обычный процесс проверки зависимостей.

Создайте l10n.yaml в корне проекта:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Для настройки под конкретную версию SDK используйте актуальное руководство по интернационализации Flutter. В современном процессе сгенерированные файлы локализации хранятся в дереве исходного кода приложения. Пример импортирует из lib/l10n; не переносите старый синтетический импорт package:flutter_gen в новую конфигурацию. См. примечание о миграции сгенерированного кода.

Создайте lib/l10n/app_en.arb:

{
  "@@locale": "en",
  "appTitle": "Reading room",
  "@appTitle": {
    "description": "Title of the sample reading application"
  },
  "welcomeName": "Welcome, {name}",
  "@welcomeName": {
    "description": "Greeting on the home screen",
    "placeholders": {
      "name": {"type": "String", "example": "Sam"}
    }
  },
  "savedBooks": "{count, plural, =0{No saved books} one{1 saved book} other{{count} saved books}}",
  "@savedBooks": {
    "description": "Number of books saved to the user's library",
    "placeholders": {
      "count": {"type": "int"}
    }
  },
  "readingState": "{state, select, active{Reading now} paused{Reading paused} other{Ready to read}}",
  "@readingState": {
    "description": "Reading status; state is active, paused or another value",
    "placeholders": {
      "state": {"type": "String"}
    }
  }
}

Создайте lib/l10n/app_es.arb:

{
  "@@locale": "es",
  "appTitle": "Sala de lectura",
  "welcomeName": "Te damos la bienvenida, {name}",
  "savedBooks": "{count, plural, =0{No hay libros guardados} one{1 libro guardado} other{{count} libros guardados}}",
  "readingState": "{state, select, active{Leyendo ahora} paused{Lectura en pausa} other{Todo listo para leer}}"
}

Шаблон содержит метаданные плейсхолдеров, которые использует генератор. Локализованный файл сохраняет ключи сообщений, имена плейсхолдеров и идентификаторы select, меняя только текст для пользователя. Эти испанские примеры иллюстрируют механику; текст для продакшена должен проверить носитель языка в реальном контексте продукта.

Запускайте flutter gen-l10n после добавления или изменения ресурсов. Считайте ошибки генератора проблемами в ресурсах, требующими исправления, и устраняйте их до включения файлов в релиз.

После генерации добавьте следующий пример в lib/main.dart:

import 'package:flutter/material.dart';
import 'l10n/app_localizations.dart';

void main() => runApp(const ReadingApp());

class ReadingApp extends StatelessWidget {
  const ReadingApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: const ReadingHome(),
    );
  }
}

class ReadingHome extends StatelessWidget {
  const ReadingHome({super.key});

  @override
  Widget build(BuildContext context) {
    final messages = AppLocalizations.of(context)!;
    return Scaffold(
      appBar: AppBar(title: Text(messages.appTitle)),
      body: Padding(
        padding: const EdgeInsetsDirectional.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(messages.welcomeName('Sam')),
            Text(messages.savedBooks(3)),
            Text(messages.readingState('active')),
          ],
        ),
      ),
    );
  }
}

Сгенерированный API делает различие между простым сообщением и сообщением с аргументами видимым в коде. appTitle вызывается как значение; welcomeName, savedBooks и readingState получают значения, необходимые для построения сообщений.

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

intl — не конкурирующая платформа управления переводами. Это набор утилит интернационализации, которые используются в процессах локализации. gen-l10n генерирует методы доступа приложения из ресурсов ARB. Отдельный пакет intl_utils тоже генерирует код локализации, но на момент проверки 30 октября 2026 года его страница была помечена как прекращённая. Проверьте статус поддержки, прежде чем использовать его в новом проекте.

Используйте практичную матрицу тестирования:

В FAQ по веб-версии Flutter указано, что он ориентирован на приложения, и для статического веб-контента с большим объёмом текста рекомендуется документно-ориентированный подход. Рассмотрите отдельные HTML-страницы для маркетинга, справки и редакционного контента, если им важно органическое продвижение в поиске.

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

Среди документированных форматов программных проектов Smartcat — импорт JSON, YAML, Android XML, iOS .strings и LocJSON. Документация, изученная для этого руководства, не подтверждает встроенную поддержку ARB или проверенный процесс конвертации ARB в JSON. Не считайте, что смена расширения файла доказывает совместимость. См. документацию по программным проектам.

Используйте следующий порядок как предлагаемую процедуру проверки вместе с командой разработки, а не как уже проверенный рецепт подключения: