511 lines
12 KiB
Markdown
511 lines
12 KiB
Markdown
|
# Localization
|
|||
|
|
|
|||
|
|
Internationalization (i18n) patterns using flutter_localizations and intl package for Flutter applications.
|
|||
|
|
|
|||
|
|
## Setup
|
|||
|
|
|
|||
|
|
### Dependencies
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# pubspec.yaml
|
|||
|
|
dependencies:
|
|||
|
|
flutter:
|
|||
|
|
sdk: flutter
|
|||
|
|
flutter_localizations:
|
|||
|
|
sdk: flutter
|
|||
|
|
intl: ^0.19.0
|
|||
|
|
|
|||
|
|
flutter:
|
|||
|
|
generate: true
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### l10n Configuration
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# l10n.yaml
|
|||
|
|
arb-dir: lib/l10n
|
|||
|
|
template-arb-file: app_en.arb
|
|||
|
|
output-localization-file: app_localizations.dart
|
|||
|
|
output-class: AppLocalizations
|
|||
|
|
nullable-getter: false
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## ARB Files
|
|||
|
|
|
|||
|
|
### English (Template)
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
// lib/l10n/app_en.arb
|
|||
|
|
{
|
|||
|
|
"@@locale": "en",
|
|||
|
|
"appTitle": "My App",
|
|||
|
|
"@appTitle": {
|
|||
|
|
"description": "The application title"
|
|||
|
|
},
|
|||
|
|
"hello": "Hello",
|
|||
|
|
"welcome": "Welcome, {name}!",
|
|||
|
|
"@welcome": {
|
|||
|
|
"description": "Welcome message with user name",
|
|||
|
|
"placeholders": {
|
|||
|
|
"name": {
|
|||
|
|
"type": "String",
|
|||
|
|
"example": "John"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
"itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
|
|||
|
|
"@itemCount": {
|
|||
|
|
"description": "Number of items",
|
|||
|
|
"placeholders": {
|
|||
|
|
"count": {
|
|||
|
|
"type": "int"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
"lastUpdated": "Last updated: {date}",
|
|||
|
|
"@lastUpdated": {
|
|||
|
|
"description": "Last update timestamp",
|
|||
|
|
"placeholders": {
|
|||
|
|
"date": {
|
|||
|
|
"type": "DateTime",
|
|||
|
|
"format": "yMMMd"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
"price": "Price: {amount}",
|
|||
|
|
"@price": {
|
|||
|
|
"description": "Product price",
|
|||
|
|
"placeholders": {
|
|||
|
|
"amount": {
|
|||
|
|
"type": "double",
|
|||
|
|
"format": "currency",
|
|||
|
|
"optionalParameters": {
|
|||
|
|
"symbol": "$",
|
|||
|
|
"decimalDigits": 2
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
"gender": "{gender, select, male{He} female{She} other{They}} liked this",
|
|||
|
|
"@gender": {
|
|||
|
|
"description": "Gender-specific message",
|
|||
|
|
"placeholders": {
|
|||
|
|
"gender": {
|
|||
|
|
"type": "String"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Chinese
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
// lib/l10n/app_zh.arb
|
|||
|
|
{
|
|||
|
|
"@@locale": "zh",
|
|||
|
|
"appTitle": "我的应用",
|
|||
|
|
"hello": "你好",
|
|||
|
|
"welcome": "欢迎，{name}！",
|
|||
|
|
"itemCount": "{count, plural, =0{没有项目} other{{count} 个项目}}",
|
|||
|
|
"lastUpdated": "最后更新：{date}",
|
|||
|
|
"price": "价格：{amount}",
|
|||
|
|
"gender": "{gender, select, male{他} female{她} other{Ta}}喜欢了这个"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Japanese
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
// lib/l10n/app_ja.arb
|
|||
|
|
{
|
|||
|
|
"@@locale": "ja",
|
|||
|
|
"appTitle": "マイアプリ",
|
|||
|
|
"hello": "こんにちは",
|
|||
|
|
"welcome": "ようこそ、{name}さん！",
|
|||
|
|
"itemCount": "{count, plural, =0{アイテムなし} other{{count}件}}",
|
|||
|
|
"lastUpdated": "最終更新：{date}",
|
|||
|
|
"price": "価格：{amount}",
|
|||
|
|
"gender": "{gender, select, male{彼} female{彼女} other{その人}}がいいねしました"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## App Configuration
|
|||
|
|
|
|||
|
|
```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',
|
|||
|
|
localizationsDelegates: const [
|
|||
|
|
AppLocalizations.delegate,
|
|||
|
|
GlobalMaterialLocalizations.delegate,
|
|||
|
|
GlobalWidgetsLocalizations.delegate,
|
|||
|
|
GlobalCupertinoLocalizations.delegate,
|
|||
|
|
],
|
|||
|
|
supportedLocales: const [
|
|||
|
|
Locale('en'),
|
|||
|
|
Locale('zh'),
|
|||
|
|
Locale('ja'),
|
|||
|
|
],
|
|||
|
|
locale: const Locale('en'),
|
|||
|
|
home: const HomePage(),
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Using Translations
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
|
|||
|
|
|
|||
|
|
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: Column(
|
|||
|
|
children: [
|
|||
|
|
Text(l10n.hello),
|
|||
|
|
Text(l10n.welcome('John')),
|
|||
|
|
Text(l10n.itemCount(5)),
|
|||
|
|
Text(l10n.lastUpdated(DateTime.now())),
|
|||
|
|
Text(l10n.price(29.99)),
|
|||
|
|
Text(l10n.gender('female')),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Extension for Convenience
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
extension LocalizationExtension on BuildContext {
|
|||
|
|
AppLocalizations get l10n => AppLocalizations.of(this);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Usage
|
|||
|
|
Text(context.l10n.hello)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Dynamic Locale Switching
|
|||
|
|
|
|||
|
|
### With Riverpod
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
@riverpod
|
|||
|
|
class LocaleNotifier extends _$LocaleNotifier {
|
|||
|
|
@override
|
|||
|
|
Locale build() {
|
|||
|
|
final saved = ref.watch(sharedPreferencesProvider).getString('locale');
|
|||
|
|
if (saved != null) {
|
|||
|
|
return Locale(saved);
|
|||
|
|
}
|
|||
|
|
return const Locale('en');
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
void setLocale(Locale locale) {
|
|||
|
|
ref.read(sharedPreferencesProvider).setString('locale', locale.languageCode);
|
|||
|
|
state = locale;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class MyApp extends ConsumerWidget {
|
|||
|
|
const MyApp({super.key});
|
|||
|
|
|
|||
|
|
@override
|
|||
|
|
Widget build(BuildContext context, WidgetRef ref) {
|
|||
|
|
final locale = ref.watch(localeNotifierProvider);
|
|||
|
|
|
|||
|
|
return MaterialApp(
|
|||
|
|
localizationsDelegates: AppLocalizations.localizationsDelegates,
|
|||
|
|
supportedLocales: AppLocalizations.supportedLocales,
|
|||
|
|
locale: locale,
|
|||
|
|
home: const HomePage(),
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Language Selector
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
class LanguageSelector extends ConsumerWidget {
|
|||
|
|
const LanguageSelector({super.key});
|
|||
|
|
|
|||
|
|
static const languages = [
|
|||
|
|
(Locale('en'), 'English'),
|
|||
|
|
(Locale('zh'), '中文'),
|
|||
|
|
(Locale('ja'), '日本語'),
|
|||
|
|
];
|
|||
|
|
|
|||
|
|
@override
|
|||
|
|
Widget build(BuildContext context, WidgetRef ref) {
|
|||
|
|
final currentLocale = ref.watch(localeNotifierProvider);
|
|||
|
|
|
|||
|
|
return PopupMenuButton<Locale>(
|
|||
|
|
initialValue: currentLocale,
|
|||
|
|
onSelected: (locale) {
|
|||
|
|
ref.read(localeNotifierProvider.notifier).setLocale(locale);
|
|||
|
|
},
|
|||
|
|
itemBuilder: (context) => languages.map((lang) {
|
|||
|
|
return PopupMenuItem(
|
|||
|
|
value: lang.$1,
|
|||
|
|
child: Row(
|
|||
|
|
children: [
|
|||
|
|
if (currentLocale == lang.$1)
|
|||
|
|
const Icon(Icons.check, size: 18),
|
|||
|
|
const SizedBox(width: 8),
|
|||
|
|
Text(lang.$2),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
);
|
|||
|
|
}).toList(),
|
|||
|
|
child: const Icon(Icons.language),
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Date and Number Formatting
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
import 'package:intl/intl.dart';
|
|||
|
|
|
|||
|
|
class FormattingUtils {
|
|||
|
|
static String formatDate(DateTime date, String locale) {
|
|||
|
|
return DateFormat.yMMMd(locale).format(date);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
static String formatDateTime(DateTime dateTime, String locale) {
|
|||
|
|
return DateFormat.yMMMd(locale).add_jm().format(dateTime);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
static String formatRelativeTime(DateTime dateTime, String locale) {
|
|||
|
|
final now = DateTime.now();
|
|||
|
|
final diff = now.difference(dateTime);
|
|||
|
|
|
|||
|
|
if (diff.inDays > 7) {
|
|||
|
|
return DateFormat.yMMMd(locale).format(dateTime);
|
|||
|
|
} else if (diff.inDays > 0) {
|
|||
|
|
return '${diff.inDays}d ago';
|
|||
|
|
} else if (diff.inHours > 0) {
|
|||
|
|
return '${diff.inHours}h ago';
|
|||
|
|
} else if (diff.inMinutes > 0) {
|
|||
|
|
return '${diff.inMinutes}m ago';
|
|||
|
|
} else {
|
|||
|
|
return 'Just now';
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
static String formatCurrency(double amount, String locale, {String? symbol}) {
|
|||
|
|
return NumberFormat.currency(
|
|||
|
|
locale: locale,
|
|||
|
|
symbol: symbol,
|
|||
|
|
decimalDigits: 2,
|
|||
|
|
).format(amount);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
static String formatNumber(num number, String locale) {
|
|||
|
|
return NumberFormat.decimalPattern(locale).format(number);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
static String formatPercent(double value, String locale) {
|
|||
|
|
return NumberFormat.percentPattern(locale).format(value);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
static String formatCompact(num number, String locale) {
|
|||
|
|
return NumberFormat.compact(locale: locale).format(number);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Usage with Locale
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
class FormattedContent extends StatelessWidget {
|
|||
|
|
const FormattedContent({super.key});
|
|||
|
|
|
|||
|
|
@override
|
|||
|
|
Widget build(BuildContext context) {
|
|||
|
|
final locale = Localizations.localeOf(context).toString();
|
|||
|
|
|
|||
|
|
return Column(
|
|||
|
|
children: [
|
|||
|
|
Text(FormattingUtils.formatDate(DateTime.now(), locale)),
|
|||
|
|
Text(FormattingUtils.formatCurrency(1234.56, locale, symbol: '\$')),
|
|||
|
|
Text(FormattingUtils.formatNumber(1234567, locale)),
|
|||
|
|
Text(FormattingUtils.formatPercent(0.75, locale)),
|
|||
|
|
Text(FormattingUtils.formatCompact(1500000, locale)),
|
|||
|
|
],
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## RTL Support
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
class RtlAwareWidget extends StatelessWidget {
|
|||
|
|
const RtlAwareWidget({super.key});
|
|||
|
|
|
|||
|
|
@override
|
|||
|
|
Widget build(BuildContext context) {
|
|||
|
|
final isRtl = Directionality.of(context) == TextDirection.rtl;
|
|||
|
|
|
|||
|
|
return Row(
|
|||
|
|
children: [
|
|||
|
|
Icon(isRtl ? Icons.arrow_back : Icons.arrow_forward),
|
|||
|
|
const Expanded(child: Text('Content')),
|
|||
|
|
Padding(
|
|||
|
|
padding: EdgeInsetsDirectional.only(start: 16),
|
|||
|
|
child: const Icon(Icons.settings),
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Directional Widgets
|
|||
|
|
|
|||
|
|
| Standard | Directional |
|
|||
|
|
|----------|-------------|
|
|||
|
|
| `EdgeInsets` | `EdgeInsetsDirectional` |
|
|||
|
|
| `Padding` | `Padding` with `EdgeInsetsDirectional` |
|
|||
|
|
| `Align` | `AlignmentDirectional` |
|
|||
|
|
| `Positioned` | `PositionedDirectional` |
|
|||
|
|
| `BorderRadius` | `BorderRadiusDirectional` |
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
// Use directional
|
|||
|
|
Padding(
|
|||
|
|
padding: const EdgeInsetsDirectional.only(start: 16, end: 8),
|
|||
|
|
child: child,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
Container(
|
|||
|
|
alignment: AlignmentDirectional.centerStart,
|
|||
|
|
child: child,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
Container(
|
|||
|
|
decoration: const BoxDecoration(
|
|||
|
|
borderRadius: BorderRadiusDirectional.only(
|
|||
|
|
topStart: Radius.circular(8),
|
|||
|
|
bottomStart: Radius.circular(8),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Organized Translations
|
|||
|
|
|
|||
|
|
### Split by Feature
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
lib/
|
|||
|
|
l10n/
|
|||
|
|
app_en.arb # Common translations
|
|||
|
|
app_zh.arb
|
|||
|
|
features/
|
|||
|
|
auth_en.arb # Auth feature translations
|
|||
|
|
auth_zh.arb
|
|||
|
|
settings_en.arb # Settings feature translations
|
|||
|
|
settings_zh.arb
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Namespaced Keys
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
// app_en.arb
|
|||
|
|
{
|
|||
|
|
"auth_login": "Login",
|
|||
|
|
"auth_logout": "Logout",
|
|||
|
|
"auth_forgotPassword": "Forgot Password?",
|
|||
|
|
|
|||
|
|
"settings_title": "Settings",
|
|||
|
|
"settings_language": "Language",
|
|||
|
|
"settings_theme": "Theme",
|
|||
|
|
|
|||
|
|
"error_network": "Network error. Please try again.",
|
|||
|
|
"error_unknown": "An unknown error occurred."
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Testing
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
void main() {
|
|||
|
|
testWidgets('shows localized text', (tester) async {
|
|||
|
|
await tester.pumpWidget(
|
|||
|
|
MaterialApp(
|
|||
|
|
localizationsDelegates: AppLocalizations.localizationsDelegates,
|
|||
|
|
supportedLocales: AppLocalizations.supportedLocales,
|
|||
|
|
locale: const Locale('en'),
|
|||
|
|
home: const HomePage(),
|
|||
|
|
),
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
expect(find.text('Hello'), findsOneWidget);
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
testWidgets('switches locale', (tester) async {
|
|||
|
|
await tester.pumpWidget(
|
|||
|
|
ProviderScope(
|
|||
|
|
child: MaterialApp(
|
|||
|
|
localizationsDelegates: AppLocalizations.localizationsDelegates,
|
|||
|
|
supportedLocales: AppLocalizations.supportedLocales,
|
|||
|
|
locale: const Locale('zh'),
|
|||
|
|
home: const HomePage(),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
expect(find.text('你好'), findsOneWidget);
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## ARB Placeholders Reference
|
|||
|
|
|
|||
|
|
| Type | Format Options |
|
|||
|
|
|------|----------------|
|
|||
|
|
| `String` | None |
|
|||
|
|
| `int` | `compact`, `compactCurrency`, `compactLong`, `compactSimpleCurrency` |
|
|||
|
|
| `double` | `compact`, `compactCurrency`, `currency`, `decimalPattern`, `decimalPercentPattern`, `percentPattern`, `scientificPattern`, `simpleCurrency` |
|
|||
|
|
| `DateTime` | Any `DateFormat` pattern (yMd, yMMMd, jm, etc.) |
|
|||
|
|
| `num` | Same as `int` and `double` |
|
|||
|
|
|
|||
|
|
## Localization Checklist
|
|||
|
|
|
|||
|
|
| Item | Implementation |
|
|||
|
|
|------|----------------|
|
|||
|
|
| Dependencies | `flutter_localizations`, `intl` |
|
|||
|
|
| l10n.yaml | Configure ARB paths and output |
|
|||
|
|
| ARB files | Create for each supported locale |
|
|||
|
|
| App config | Add delegates and supported locales |
|
|||
|
|
| Generate | Run `flutter gen-l10n` |
|
|||
|
|
| Use translations | `AppLocalizations.of(context)` |
|
|||
|
|
| Date/number formatting | Use `intl` formatters with locale |
|
|||
|
|
| RTL support | Use directional widgets |
|
|||
|
|
| Persist preference | Save user's locale choice |
|
|||
|
|
| Testing | Test with different locales |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
*Flutter is a trademark of Google LLC. intl is an open-source package by the Dart team.*
|