Flutter ローカリゼーション: ARB ファイル、Intl、オートメーション
Flutter の組み込みローカリゼーションシステムは、Application Resource Bundle (ARB) ファイルと intl パッケージを使い、あらゆる言語で完全にネイティブな体験を提供します。このガイドでは、プロジェクト設定や ARB 形式の詳細から言語切替、複数形対応、l10n.dev を使った翻訳の自動化までを網羅しています。
Flutter ローカリゼーションとは？
Flutter ローカリゼーションは、アプリを複数の言語や地域に対応させる公式の方法です。翻訳済み文字列は ARB ファイルに保存され、flutter_gen コードジェネレーターが型安全な Dart アクセサを生成します。実行時にはデバイスのロケールに基づいて正しい ARB ファイルが選択され、ロケールをプログラムで切り替えても再起動は不要です。
プロジェクト設定
Flutter のローカリゼーションパイプラインは、pubspec.yaml と l10n.yaml の 2 つの設定ファイルで制御されます。pubspec.yaml でコード生成を有効にし、ARB ディレクトリを指定しましょう。
flutter_localizations と intl を依存関係に追加し、generate フラグを有効にして Flutter が ARB ファイルから Dart のローカリゼーションクラスを自動生成するようにします。
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any
flutter:
generate: true
プロジェクトのルートに l10n.yaml ファイルを置き、ARB ディレクトリ、テンプレートファイル、生成される出力ファイル名を設定します。
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dartARB ファイル形式
ARB (Application Resource Bundle) は Flutter の国際化向けに設計された JSON ベースの形式です。各キーは翻訳可能な文字列に対応し、@ で始まるオプションのメタデータキーは説明やプレースホルダー定義、翻訳者向けのコンテキストを保持します。
- @@locale: ファイルのロケールを宣言します（例: "en", "fr", "zh_CN"）。l10n.dev が自動的にターゲット言語コードに更新します。
- @@last_modified: 最終更新日時のタイムスタンプ。l10n.dev は翻訳ファイル生成時に現在の UTC タイムスタンプに自動設定します。
- @key メタデータ: description、example、placeholders などのメタデータ項目はデフォルトで翻訳されず、そのまま残して翻訳者のコンテキストを保持します。translateMetadata 設定を有効にすると翻訳されます。
- プレースホルダーと ICU メッセージ: 文字列には名前付きプレースホルダー（{name}）や複数形・選択のための ICU メッセージ構文を含められ、翻訳時に正しく保持されます。
元の ARB ファイル（英語）
{
"@@locale": "en",
"@@last_modified": "2026-01-15T10:30:00Z",
"appTitle": "My App",
"@appTitle": {
"description": "The title of the application"
},
"welcome": "Welcome, {name}!",
"@welcome": {
"description": "Welcome message shown on the home screen",
"placeholders": {
"name": {
"type": "String",
"example": "Alice"
}
}
},
"unreadMessages": "{count, plural, =0{No unread messages} =1{1 unread message} other{{count} unread messages}}",
"@unreadMessages": {
"description": "Number of unread messages",
"placeholders": {
"count": {
"type": "int"
}
}
}
}翻訳済み ARB ファイル（フランス語）
翻訳後、UI 文字列はローカライズされ、メタデータ構造はそのまま保持されます。l10n.dev は @@locale と @@last_modified を自動更新します。
{
"@@locale": "fr",
"@@last_modified": "2026-01-15T10:30:01Z",
"appTitle": "Mon Application",
"@appTitle": {
"description": "The title of the application"
},
"welcome": "Bienvenue, {name} !",
"@welcome": {
"description": "Welcome message shown on the home screen",
"placeholders": {
"name": {
"type": "String",
"example": "Alice"
}
}
},
"unreadMessages": "{count, plural, =0{Aucun message non lu} =1{1 message non lu} other{{count} messages non lus}}",
"@unreadMessages": {
"description": "Number of unread messages",
"placeholders": {
"count": {
"type": "int"
}
}
}
}ファイル命名規則
ARB ファイルはシンプルな命名パターンに従います。デフォルトで app_ をプレフィックスにし、ロケールコードと .arb 拡張子を続けます。Flutter と l10n.dev は言語コードと地域コードの区切りにアンダースコアを使います。
# Default pattern (recommended)
app_en.arb
app_fr.arb
app_en_US.arb # Locale with region (underscore format)
app_zh_CN.arb # Chinese Simplified
# Custom prefix patterns also supported
my_app_en.arb
my_app_fr.arb
# Note: ARB files use underscores, not hyphens
# ✓ app_en_US.arb
# ✗ app_en-US.arbプロジェクト構成
すべての ARB ファイルは lib/ 内の専用 l10n フォルダにまとめましょう。Flutter のコードジェネレーターは l10n.yaml の arb-dir 設定に基づいて自動的に読み込み、すぐ使える Dart クラスを出力します。
lib/
├── l10n/
│ ├── app_en.arb ← Source (English)
│ ├── app_fr.arb ← French
│ ├── app_de.arb ← German
│ ├── app_ja.arb ← Japanese
│ ├── app_zh_CN.arb ← Chinese Simplified
│ └── app_es.arb ← Spanish
├── main.dart
└── ...
# Generated output (do not edit manually)
.dart_tool/
└── flutter_gen/
└── gen_l10n/
└── app_localizations.dart初期化
生成された Dart ローカリゼーションクラスを MaterialApp に接続し、localizationsDelegates と supportedLocales を指定します。Flutter はデバイスのロケールに合った ARB データを解決します。
生成された AppLocalizations.delegate と Flutter SDK の 3 つのデリゲートを渡し、アプリが対応するすべてのロケールを supportedLocales にリストアップします。ウィジェットツリー内のどこでも AppLocalizations.of(context)! を使って翻訳文字列にアクセス可能です。
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'My App',
// Required delegates
localizationsDelegates: const [
AppLocalizations.delegate,
GlobalMaterialLocalizations.delegate,
GlobalWidgetsLocalizations.delegate,
GlobalCupertinoLocalizations.delegate,
],
// Supported locales
supportedLocales: AppLocalizations.supportedLocales,
home: const HomePage(),
);
}
}
// Use in a widget
class HomePage extends StatelessWidget {
const HomePage({super.key});
@override
Widget build(BuildContext context) {
final l10n = AppLocalizations.of(context)!;
return Scaffold(
appBar: AppBar(title: Text(l10n.appTitle)),
body: Center(child: Text(l10n.welcome('Alice'))),
);
}
}実行時の言語切替
MaterialApp の locale プロパティを更新することで、実行時にアプリのロケールを切り替えられます。一般的には StatefulWidget や状態管理で Locale を保持し、切り替え用のコールバックを公開します。ウィジェットツリーは新しいロケールで自動的に再構築されます。
// Manage locale state at the app level
class MyApp extends StatefulWidget {
const MyApp({super.key});
@override
State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
Locale _locale = const Locale('en');
void _changeLocale(Locale locale) {
setState(() => _locale = locale);
}
@override
Widget build(BuildContext context) {
return MaterialApp(
locale: _locale,
localizationsDelegates: const [
AppLocalizations.delegate,
GlobalMaterialLocalizations.delegate,
GlobalWidgetsLocalizations.delegate,
GlobalCupertinoLocalizations.delegate,
],
supportedLocales: AppLocalizations.supportedLocales,
home: SettingsPage(onLocaleChange: _changeLocale),
);
}
}
// Language selector widget
class LanguageSelector extends StatelessWidget {
final void Function(Locale) onLocaleChange;
const LanguageSelector({super.key, required this.onLocaleChange});
@override
Widget build(BuildContext context) {
return DropdownButton<Locale>(
value: Localizations.localeOf(context),
items: AppLocalizations.supportedLocales
.map((locale) => DropdownMenuItem(
value: locale,
child: Text(locale.toLanguageTag()),
))
.toList(),
onChanged: (locale) {
if (locale != null) onLocaleChange(locale);
},
);
}
}複数形対応
Flutter は ARB ファイル内で ICU メッセージ構文を使って複数形を扱います。intl パッケージはすべての CLDR 複数形カテゴリを処理し、ターゲット言語のルールに基づいて正しい形を自動適用します。
- ARB の文字列値内で {count, plural, =0{...} =1{...} other{...}} 構文を使います。
- @key メタデータで count プレースホルダーを int 型として宣言します。
- l10n.dev はアラビア語、ロシア語、ポーランド語など複雑な言語も含め、ターゲット言語ごとに必要な複数形をすべて生成します。手動対応は不要です。
{
"cartItems": "{count, plural, =0{Your cart is empty} =1{1 item in your cart} other{{count} items in your cart}}",
"@cartItems": {
"description": "Cart item count",
"placeholders": {
"count": { "type": "int" }
}
},
"daysLeft": "{days, plural, =1{1 day left} other{{days} days left}}",
"@daysLeft": {
"description": "Days remaining",
"placeholders": {
"days": { "type": "int" }
}
}
}l10n.dev による完全な ARB サポート
l10n.dev は Flutter の ARB ワークフローにシームレスに対応するよう設計されています。元の ARB ファイルをアップロードすると、正確で構造が正しい翻訳を受け取れます。
- メタデータの自動更新: @@locale はターゲット言語コードに更新され、@@last_modified は現在の UTC タイムスタンプに自動設定されます。
- メタデータ翻訳の制御: デフォルトでは @key メタデータ項目（description、example、context）は翻訳されず、そのまま残ります。translateMetadata 設定を有効にすると UI 文字列と一緒に翻訳されます。
- カスタムファイルプレフィックス: app_en.arb、my_app_en_US.arb、strings_fr.arb など、任意の命名パターンに対応します。
- アンダースコアのロケール形式: ARB のロケールコードはハイフンではなくアンダースコア（en_US、zh_CN）を使います。l10n.dev はこれを正しく処理し、生成ファイルはそのまま Flutter プロジェクトに配置可能です。
- 複数形対応: CLDR ルールに従った ICU 複数形がすべてのターゲット言語で生成されるため、翻訳後の複数形編集は不要です。
npm で翻訳を自動化
ai-l10n npm パッケージを使い、コマンドラインや CI/CD パイプラインの一部として元の ARB ファイルを翻訳しましょう。一度インストールすれば、単一コマンドで複数言語に翻訳可能です。
# Install the CLI
npm install ai-l10n
# Translate your source ARB to multiple languages
npx ai-l10n translate lib/l10n/app_en.arb \
--languages fr,de,ja,zh_CN,es,koFlutterビルドへの統合
ai-l10nをFlutterのビルドプロセスに直接組み込むことで、アプリのコンパイル前に翻訳を常に最新の状態に保つことができます。一般的な方法として、package.jsonスクリプトを使用する方法とMakefileを使用する方法の2つがあります。
package.jsonスクリプト経由
translateスクリプトを追加し、npmのprebuildライフサイクルフックを使用して、ビルドのたびに自動的に実行されるようにします。npm run build:android（または build:ios / build:web）を実行すると、ai-l10nが先に翻訳を行い、その後Flutterに引き継がれます。
{
"scripts": {
"translate": "ai-l10n translate lib/l10n/app_en.arb --languages fr,de,ja,zh_CN,es,ko --update",
"prebuild": "npm run translate",
"build:android": "flutter build apk",
"build:ios": "flutter build ios",
"build:web": "flutter build web"
}
}Makefile経由
チームでMakeを使用している場合は、translateターゲットを宣言し、各ビルドターゲットがそれに依存するようにします。make build-android（または build-ios / build-all）を実行すると、flutter buildが呼び出される前に、すべてのターゲット言語が翻訳されます。
LANGUAGES = fr,de,ja,zh_CN,es,ko
translate:
npx ai-l10n translate lib/l10n/app_en.arb --languages $(LANGUAGES) --update
build-android: translate
flutter build apk
build-ios: translate
flutter build ios
build-web: translate
flutter build web
build-all: translate
flutter build apk
flutter build ios
flutter build webCI/CD 統合、増分更新、複数ファイルの一括翻訳、GitHub Actions ワークフロー例については、ローカリゼーション自動化ガイド をご覧ください。
VS Code 拡張機能
l10n.dev の VS Code 拡張機能は Flutter ARB 翻訳をエディターに直接取り込みます。ARB ファイルを右クリックして、VS Code を離れずにターゲット言語へ翻訳できます。
VS Code での使い方:
- ソースの ARB ファイル（例: app_en.arb）をエディターで開きます。
- エディター内を右クリックし、「Translate JSON」を選択します。
- ターゲット言語を 1 つまたは複数選びます（例: フランス語、日本語、ドイツ語）。
- 拡張機能がソースの横にローカライズ済みの ARB ファイルを作成し、@@locale と @@last_modified を自動更新します。
実際の動作を見る
こちらは VS Code 内で Flutter ARB ファイルをウズベク語に翻訳するライブ例です。
Flutter アプリのローカリゼーションを始めよう
世界中のユーザーに届く準備はできましたか？l10n.dev ワークスペースで直接 ARB ファイルを翻訳したり、npm CLI で自動化したり、VS Code で手軽に翻訳できます。
l10n.dev を使って Flutter アプリをローカライズしていただきありがとうございます！🚀
このガイドが役に立ったら、グローバルに届けたい他の Flutter 開発者にもぜひ共有してください。
一緒に、Flutter アプリをよりインクルーシブで世界に対応したものにしましょう。