Flutter ARB - Lingo.dev CLI

Что такое Flutter ARB?

Flutter ARB (Application Resource Bundle) — это формат на основе JSON, используемый фреймворком Flutter от Google для управления локализованными строками. Он поддерживает метаданные, заполнители и форматирование сообщений ICU для создания нативно скомпилированных приложений.

Что такое Lingo.dev CLI?

Lingo.dev CLI — это бесплатный инструмент с открытым исходным кодом для перевода приложений и контента с помощью ИИ. Он разработан для замены традиционного программного обеспечения для управления переводами, интегрируясь с существующими конвейерами.

Чтобы узнать больше, см. Обзор.

О данном руководстве

Это руководство объясняет, как переводить ARB-файлы Flutter с помощью Lingo.dev CLI.

Вы узнаете, как:

Создать проект с нуля
Настроить конвейер перевода
Генерировать переводы с помощью ИИ

Предварительные требования

Для использования Lingo.dev CLI убедитесь, что установлена версия Node.js v18+:

❯ node -v
v22.17.0

Шаг 1. Настройте проект

В каталоге вашего проекта создайте файл i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Этот файл определяет поведение конвейера перевода, включая языки для перевода и расположение локализуемого контента в файловой системе.

Чтобы узнать больше о доступных свойствах, см. i18n.json.

Шаг 2. Настройте исходную локаль

Исходная локаль — это оригинальный язык и регион, на которых был написан ваш контент. Чтобы настроить исходную локаль, установите свойство locale.source в файле i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Исходная локаль должна быть указана в виде языкового тега BCP 47.

Для полного списка кодов локалей, поддерживаемых Lingo.dev CLI, см. Поддерживаемые коды локалей.

Шаг 3. Настройка целевых локалей

Целевые локали — это языки и регионы, на которые вы хотите перевести ваш контент. Чтобы настроить целевые локали, задайте свойство locale.targets в файле i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Шаг 4. Создание исходного контента

Если вы ещё этого не сделали, создайте один или несколько ARB-файлов, содержащих контент для перевода. Эти файлы должны находиться в пути, который включает исходную локаль (например, в названии директории, как en/, или в имени файла, как messages.en.arb).

Для ARB-файлов Flutter применяются следующие требования:

Каждый ключ сообщения должен иметь соответствующее значение перевода
Метаданные (начинающиеся с @) сохраняются, но не переводятся
Поле метаданных @@locale указывает локаль
Заполнители ({name}) сохраняются во время перевода
Поддерживается формат сообщений ICU для множественного числа и выбора

Например:

{
  "@@locale": "en",
  "welcome_message": "Добро пожаловать в наше Flutter-приложение",
  "@welcome_message": {
    "description": "Основное приветственное сообщение, отображаемое на главном экране"
  },
  "login_button": "Войти",
  "greeting_with_name": "Привет, {name}!",
  "@greeting_with_name": {
    "placeholders": {
      "name": {
        "type": "String"
      }
    }
  }
}

Шаг 5. Создание bucket

В файле i18n.json добавьте объект "flutter" в объект buckets:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "flutter": {}
  }
}

В объекте "flutter" определите массив с одним или несколькими шаблонами include:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "flutter": {
      "include": ["./[locale]/example.arb"]
    }
  }
}
```
Эти шаблоны определяют, какие файлы переводить.

Сами шаблоны:
- должны содержать [locale] как заполнитель для настроенной локали
- могут указывать на пути к файлам (например, "[locale]/config.arb")
- могут использовать звездочки в качестве подстановочных знаков (например, "[locale]/*.arb")
Рекурсивные шаблоны (например, **/*.arb) не поддерживаются.

Шаг 6. Настройка LLM

Lingo.dev CLI использует большие языковые модели (LLM) для перевода контента с помощью ИИ. Чтобы использовать одну из этих моделей, вам нужен API-ключ от поддерживаемого провайдера.

Чтобы начать как можно быстрее, мы рекомендуем использовать Lingo.dev Engine — нашу собственную платформу, которая предоставляет 10 000 токенов бесплатного ежемесячного использования:

Зарегистрируйтесь в Lingo.dev.
Выполните следующую команду:
```
npx lingo.dev@latest login
```
Эта команда откроет ваш браузер по умолчанию и запросит аутентификацию.
Следуйте инструкциям.

Шаг 7. Генерация переводов

В каталоге, содержащем файл i18n.json, выполните следующую команду:

npx lingo.dev@latest run

Эта команда:

Считывает файл i18n.json.
Находит файлы, которые нужно перевести.
Извлекает переводимый контент из файлов.
Использует настроенную LLM для перевода извлеченного контента.
Записывает переведенный контент обратно в файловую систему.

При первом создании переводов создается файл i18n.lock. Этот файл отслеживает, какой контент был переведен, предотвращая ненужные повторные переводы при последующих запусках.

Пример

en/example.arb

{
  "@@locale": "en",
  "welcome_message": "Добро пожаловать в наше Flutter-приложение",
  "@welcome_message": {
    "description": "Основное приветственное сообщение, отображаемое на главном экране",
    "context": "приветствие"
  },
  "login_button": "Войти",
  "signup_button": "Зарегистрироваться",
  "greeting_with_name": "Привет, {name}!",
  "@greeting_with_name": {
    "description": "Приветственное сообщение с именем пользователя",
    "placeholders": {
      "name": {
        "type": "String",
        "description": "Отображаемое имя пользователя"
      }
    }
  },
  "item_count": "{count, plural, =0 {Нет элементов} one {# элемент} few {# элемента} many {# элементов} other {# элемента}}",
  "@item_count": {
    "description": "Сообщение, показывающее количество элементов с правильной формой множественного числа",
    "placeholders": {
      "count": {
        "type": "int",
        "description": "Количество элементов"
      }
    }
  }
}

es/example.arb

{
  "@@locale": "es",
  "welcome_message": "Bienvenido a nuestra aplicación Flutter",
  "@welcome_message": {
    "description": "Основное приветственное сообщение, отображаемое на главном экране",
    "context": "приветствие"
  },
  "login_button": "Iniciar sesión",
  "signup_button": "Registrarse",
  "greeting_with_name": "¡Hola {name}!",
  "@greeting_with_name": {
    "description": "Приветственное сообщение с именем пользователя",
    "placeholders": {
      "name": {
        "type": "String",
        "description": "Отображаемое имя пользователя"
      }
    }
  },
  "item_count": "{count, plural, =0 {Sin elementos} one {# elemento} other {# elementos}}",
  "@item_count": {
    "description": "Сообщение, показывающее количество элементов с правильной формой множественного числа",
    "placeholders": {
      "count": {
        "type": "int",
        "description": "Количество элементов"
      }
    }
  }
}

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "flutter": {
      "include": ["./[locale]/example.arb"]
    }
  }
}

i18n.lock

version: 1
checksums:
  88559ecadc7cff52625bd3a47e51dd78:
    welcome_message: 9c56d00796c3c7facba6a25275de5b7b
    login_button: 0029e5a35676c0051e761fcd046ef9ee
    signup_button: 0dd2ae69be4618c1f9e615774a4509ca
    error_network: e0becd5fc88e85a97c6987b96c80fb11
    success_message: e6dcd73052dc41dbe05d86af9887d2c4
    user_profile_title: bee775ff7216747b2111e93cefa57ddc
    settings_screen_title: 8df6777277469c1fd88cc18dde2f1cc3
    cancel_action: 2e2a849c2223911717de8caa2c71bade
    confirm_action: 90930b51154032f119fa75c1bd422d8b
    greeting_with_name: 218521f06746e82ba44d68c8a5bb210c
    item_count: d8d083b56bc155cf0997ea6ae989b83f
    user_status: 903b5a6edde5368dd9089accdc1b1f9d