
Den komplette guiden til Flutter-lokalisering
Fra ARB-filer til RTL-støtte: lokaliser Flutter-appen din med easy_localization, håndter flertallsformer for hvert språk, og automatiser oversettelser med AI.
Installer easy_localization
Legg til pakken easy_localization i pubspec.yaml. Dette er den mest populære Flutter i18n-pakken, med støtte for ARB-/JSON-filer, flertallsformer og context-utvidelser. Legg også til flutter_localizations fra SDK-en for lokalitetsbevisst formatering av datoer, tall og tekstretning.
dependencies:
easy_localization: ^3.0.7
flutter_localizations:
sdk: flutterOpprett ARB-oversettelsesfiler
Application Resource Bundle-filer (ARB) er standardformatet for lokalisering i Flutter. Hver fil inneholder nøkkel-verdi-par med valgfrie metadata som beskriver plassholdere, flertallsregler og kontekst for oversettere. Opprett én fil per språkinnstilling i mappen assets/translations.
{
"@@locale": "en",
"appTitle": "My App",
"@appTitle": {
"description": "The title of the application"
},
"greeting": "Hello, {name}!",
"@greeting": {
"description": "Greeting with user name",
"placeholders": {
"name": {
"type": "String",
"example": "Alice"
}
}
},
"itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
"@itemCount": {
"description": "Number of items in the cart",
"placeholders": {
"count": {
"type": "num",
"format": "compact"
}
}
}
}Konfigurer appen
Pakk appen din inn i EasyLocalization-widgeten. Den håndterer språkinnstillingens tilstand, laster inn oversettelser fra ressursfilene dine og tilbyr lokaliseringsdelegatene MaterialApp trenger. De tre påkrevde delegategenskapene er localizationsDelegates, supportedLocales og locale, og alle er tilgjengelige via kontekstutvidelser.
import 'package:flutter/material.dart';
import 'package:easy_localization/easy_localization.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await EasyLocalization.ensureInitialized();
runApp(
EasyLocalization(
supportedLocales: [
Locale('en'),
Locale('ar'),
Locale('ja'),
Locale('de'),
],
path: 'assets/translations', // Path to your ARB/JSON files
fallbackLocale: Locale('en'),
child: MyApp(),
),
);
}
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
localizationsDelegates: context.localizationDelegates,
supportedLocales: context.supportedLocales,
locale: context.locale,
home: HomePage(),
);
}
}Oversett widgeter
Bruk utvidelsesmetoden .tr() på strengnøkler for å hente oversatt tekst i en hvilken som helst widget. For flertallsformer bruker du .plural() med antallsverdien. easy_localization tilbyr både strengutvidelsessyntaksen ('key'.tr()) og context-metodesyntaksen (context.tr('key')).
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter/material.dart';
class HomePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text('appTitle'.tr()), // Simple key
),
body: Column(
children: [
// String with variable interpolation
Text('greeting'.tr(args: ['Alice'])),
// Named arguments
Text('greeting'.tr(namedArgs: {'name': 'Alice'})),
// Plural form
Text('itemCount'.plural(3)),
],
),
);
}
}Håndter flertallsformer og variabler
Flutter bruker ICU MessageFormat for flertallsformer, den samme standarden som brukes av iOS, Android og nettet. Definer flertallsformer med {count, plural, ...}-syntaksen i ARB-filene dine. Hvert språk trenger sitt eget sett med former basert på CLDR-flertallsreglene. Arabisk har 6 former, russisk har 4, japansk har 1.
// English: 3 useful forms (=0, =1, other)
"itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}"
// Arabic: 6 forms (=0, =1, =2, few, many, other)
"itemCount": "{count, plural, =0{لا عناصر} =1{عنصر واحد} =2{عنصران} few{{count} عناصر} many{{count} عنصرًا} other{{count} عنصر}}"
// Japanese: 1 form (other)
"itemCount": "{count, plural, other{{count}個のアイテム}}"
// German: 2 forms (=1, other)
"itemCount": "{count, plural, =1{1 Artikel} other{{count} Artikel}}"
// Russian: 3 forms (one, few, many)
"itemCount": "{count, plural, =0{Нет товаров} one{{count} товар} few{{count} товара} many{{count} товаров} other{{count} товаров}}"// Simple variable
"welcome": "Welcome, {name}!"
// Multiple variables
"orderStatus": "Order #{orderId} — {status}"
// Variable in plural context
"unreadMessages": "{count, plural, =0{No unread messages} =1{1 unread message from {sender}} other{{count} unread messages}}"
// In widgets:
Text('welcome'.tr(namedArgs: {'name': userName}));
Text('orderStatus'.tr(namedArgs: {'orderId': '1234', 'status': 'Shipped'}));
Text('unreadMessages'.plural(count, namedArgs: {'sender': senderName}));Støtt RTL-språk
Flutter speilvender automatisk hele layouten når lokaliteten er et høyre-til-venstre-språk (arabisk, hebraisk, persisk, urdu). Men koden din må bruke retningsbevisste widgeter og egenskaper for at speilvendingen skal fungere riktig. Erstatt hardkodet left/right med tilsvarende start/end.
import 'package:flutter/material.dart';
class AdaptiveLayout extends StatelessWidget {
@override
Widget build(BuildContext context) {
final isRtl = Directionality.of(context) == TextDirection.rtl;
return Scaffold(
body: Row(
children: [
// Use start/end instead of left/right
Expanded(
child: Padding(
padding: EdgeInsetsDirectional.only(
start: 16.0, // Leading edge (left in LTR, right in RTL)
end: 8.0, // Trailing edge
),
child: Text('content'.tr()),
),
),
// Flip icons for RTL
Icon(
isRtl ? Icons.arrow_back : Icons.arrow_forward,
),
],
),
);
}
}// Use Directional widgets for RTL-aware layouts
EdgeInsetsDirectional.only(start: 16, end: 8) // Not EdgeInsets.only(left: 16, right: 8)
AlignmentDirectional.centerStart // Not Alignment.centerLeft
BorderRadiusDirectional.only(topStart: Radius.circular(8))
// Automatically mirrors when locale changes to Arabic, Hebrew, etc.
// No conditional logic needed — Flutter handles text direction from localeSmarte reservekjeder for lokalitet
Når en pt-BR-oversettelse mangler, går Flutter som standard direkte tilbake til engelsk og hopper over fullt brukbare pt-PT-oversettelser. Pakken locale_chain løser dette med konfigurerbare reservekjeder. Én linje med oppsett, ingen migrering: De eksisterende .tr()-kallene dine fungerer som før.
import 'package:locale_chain/locale_chain.dart';
import 'package:locale_chain/easy_localization.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await EasyLocalization.ensureInitialized();
LocaleChain.configure(); // Enable smart fallback chains
runApp(
EasyLocalization(
supportedLocales: [
Locale('en'),
Locale('pt', 'BR'),
Locale('pt', 'PT'),
Locale('es'),
Locale('es', 'MX'),
],
path: 'assets/translations',
assetLoader: LocaleChainAssetLoader( // Swap in the chain loader
baseLoader: RootBundleAssetLoader(),
),
fallbackLocale: Locale('en'),
child: MyApp(),
),
);
}
// Result: pt-BR user sees pt-PT translations when pt-BR keys are missing,
// instead of falling back directly to English.// Override specific chains while keeping built-in defaults
LocaleChain.configure(
fallbacks: {
'pt-BR': ['pt-PT', 'pt'], // pt-BR → pt-PT → pt → en
'es-MX': ['es-419', 'es'], // es-MX → es-419 → es → en
'fr-CA': ['fr'], // fr-CA → fr → en
},
);
// Or replace all defaults with your own chains
LocaleChain.configure(
fallbacks: {
'zh-Hant-HK': ['zh-Hant-TW', 'zh-Hans'],
'pt-BR': ['pt-PT', 'pt'],
},
mergeDefaults: false, // Only your chains, no built-in defaults
);Automatiser oversettelser
Når lokaliseringsoppsettet ditt er fullført, kan du oversette ARB-filene dine med AI. I IDE-en din kan du be AI-assistenten din om å oversette kilde-ARB-filen din, eller bruke i18n Agent-CLI-en i CI/CD-pipelinen din. ARB-metadata (plassholdere, beskrivelser) gir kontekst som forbedrer oversettelseskvaliteten.
# In your IDE, ask your AI assistant:
> Translate assets/translations/en.arb to Arabic, Japanese, and German
✓ ar.arb created (1.4s)
✓ ja.arb created (1.2s)
✓ de.arb created (1.1s)
# Or use the CLI in CI/CD:
npx i18n-agent translate assets/translations/en.arb --lang ar,ja,deAutomatiser oversettelseskvalitet
Vanlige fallgruver
Oversettelsesfiler blir ikke funnet ved kjøretid
Ugyldig syntaks i ARB-fil
Oversettelsesendringer vises ikke ved hot reload
Hardkodet venstre/høyre ødelegger RTL
Anbefalt filstruktur
my_flutter_app/
├── assets/
│ └── translations/
│ ├── en.arb # Source language (English)
│ ├── ar.arb # Arabic (with 6 plural forms)
│ ├── de.arb # German
│ ├── ja.arb # Japanese
│ ├── pt-BR.arb # Brazilian Portuguese
│ └── pt-PT.arb # European Portuguese
├── lib/
│ ├── main.dart # App entry with EasyLocalization
│ ├── app.dart # MaterialApp with locale delegates
│ └── widgets/
│ └── language_switcher.dart
├── pubspec.yaml # Dependencies
└── analysis_options.yamlPrøv i18n Agent nå
Slipp oversettelsesfilen din her
JSON, YAML, PO, XML, CSV, Markdown, Properties
eller klikk for å bla gjennom
Målspråk
Lokalitetsreserve med locale_chain
Når en oversettelsesnøkkel mangler i en regional lokalitet som pt-BR, hopper Flutter rett til malspråket i stedet for å sjekke overordnet lokalitet pt først.
flutter pub add locale_chainimport 'package:locale_chain/locale_chain.dart';
LocaleChain.configure(fallbacks: {
'pt-BR': ['pt', 'en'],
'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
});
LocaleChainAssetLoader(baseLoader: RootBundleAssetLoader());Se vår guide for lokalitetsreserve for den fullstendige listen over støttede rammeverk og 75 innebygde kjeder. Learn more →