Flutterアプリをローカライズする

ARBメッセージを翻訳し、Flutterリソースを生成して、各ターゲットロケールで画面を確認します。

Flutterのローカライゼーションツールは、ARBメッセージをウィジェットから呼び出すメソッドに変換します。Lingo.devはそのARBリソースを翻訳するので、生成されたAPIをそのまま使いながら、対応言語を追加できます。まずは挨拶と項目数を表示する画面を一つ選び、テキスト、変数、複数形の動作をまとめて確認しましょう。

この手順は、プロジェクトがすでにFlutterのローカライゼーション生成機能を通じてソースのARBを読み込んでいることを前提としています。既存の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

このコマンドは処理の完了を待ってファイルを取得します。実行がレビュー待ちになった場合や失敗した場合は、その状態を解消してからリリース用リソースを生成してください。初回は通常のプッシュだけを行うことで、不足している翻訳を依頼せずにソースの基準状態を確立できます。

ターゲットのキー、説明、プレースホルダーの名前と型、および@@localeを確認します。続いて、プロジェクトのFlutterローカライゼーション生成、解析、テスト、ビルドを実行します。無効なICU式、プレースホルダーの欠落、互換性のない型があれば、修正してから先に進んでください。ARBの再構築ではメタデータは保持されますが、翻訳されたすべてのメッセージについて、Flutterのジェネレーターとの適合性が検証されるわけではありません。

ドイツ語とフランス語で画面を開きます。短い名前と長い名前を入力し、項目数には0、1、2、さらに大きな数を指定します。数字が表示されるかどうかだけでなく、複数形の表現も読んで確認してください。言語によっては英語のソースにない複数形の区分が必要になるため、ターゲット言語で必要な形式を確認します。ロケールの選択、フォールバック、翻訳によるテキストの長さの変化に加え、必要に応じて表示方向も確認してください。日付と数値の書式は、引き続きFlutterが実行時に決定します。

その後の更新もソースに連動させる #

設定、ソース、採用した翻訳、および.lingo/lock.jsonは一緒に管理します。ソースメッセージを変更したら、lingo push --waitを実行し、そのメッセージを変更していない隣のメッセージと並べて確認します。説明だけを編集しても、それだけでメッセージ本文が新たな翻訳タスクになるわけではありません。修正した文脈を反映して再翻訳したい場合は、範囲を限定した更新を使ってください。

書き戻しが保留中の間は、ターゲットファイルを編集しないでください。ローカルで修正した翻訳を保護するには、--waitを付けずに送信し、lingo pull --dry-runを確認してから、送信に使ったチェックアウトでlingo pullを使って取得します。別のマシンでは、直近の実行結果が共有されていると想定せず、コミット済みの翻訳を使うか、成果物を明示的に受け渡す必要があります。復旧方法の詳細は、レビュー済みの翻訳を保持するを参照してください。

このサイクルが機能することを確認したら、GitHub Appまたは継続的インテグレーションによる自動化を使い、レビュー前に翻訳とリソース生成を繰り返し実行します。ネイティブのアンドロイド向けXMLとアップル向けリソースでは、ファイル形式と実行時の仕様が異なります。クロスプラットフォームのプロジェクトでは、これらをARBの生成とは分けて管理してください。