Skip to main content

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.

1

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.

easy_localization tilbyr kontekstutvidelser som context.tr() og 'key'.tr() for kortfattet tilgang til oversettelser. Pakken håndterer innlasting og lagring av språkinnstillinger samt hot reload av oversettelsesfiler under utvikling.
pubspec.yaml
dependencies:
  easy_localization: ^3.0.7
  flutter_localizations:
    sdk: flutter
2

Opprett 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.

assets/translations/en.arb
{
  "@@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"
      }
    }
  }
}
Nøklene med @-prefiks (som @greeting) er metadata: De beskriver strengen over dem. Inkluder plassholdertyper og eksempler for å hjelpe oversettere med å lage presise oversettelser. Disse metadatanøklene fjernes ved kjøretid og medfører ingen ekstra ressursbruk.
3

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.

lib/main.dart
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(),
    );
  }
}
"Easy Localization not initialized": Denne feilen betyr at du har glemt å kalle EasyLocalization.ensureInitialized() før runApp(). Du må bruke await på kallet etter WidgetsFlutterBinding.ensureInitialized() og før runApp().
4

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')).

lib/widgets/home_page.dart
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)),
        ],
      ),
    );
  }
}
Hvis oversettelser returnerer rå nøkler i stedet for oversatt tekst, sjekk: 1) At EasyLocalization-widgeten pakker inn MaterialApp, ikke omvendt. 2) At oversettelsesfilene dine er deklarert under assets i pubspec.yaml. 3) At filstien i EasyLocalization samsvarer med den faktiske mappestrukturen din.
5

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.

Plural forms by language
// 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} товаров}}"
Variables and named arguments
// 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}));
Hardkod aldri entall-/flertallslogikk med if (count == 1). Språk som fransk behandler 0 som entall. Russisk, polsk og arabisk har flertallsformer som engelsk mangler helt. Bruk alltid ICU-flertallssyntaks, og la rammeverket velge riktig form.
6

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.

lib/widgets/adaptive_layout.dart
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,
          ),
        ],
      ),
    );
  }
}
RTL-aware widget patterns
// 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 locale
Test RTL ved å midlertidig sette applokaliteten til arabisk (Locale('ar')). Flutter speilvender hele brukergrensesnittet: navigasjonsskuffer åpnes fra høyre, tilbakepiler snus, og tekst høyrejusteres. Bruk EdgeInsetsDirectional, AlignmentDirectional og BorderRadiusDirectional for å sikre at de egendefinerte layoutene dine speilvendes riktig.
7

Smarte 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.

lib/main.dart with LocaleChain
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.
Custom fallback configuration
// 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
);
locale_chain inkluderer innebygde reservekjeder for regionale varianter av portugisisk, spansk, fransk, tysk, italiensk, nederlandsk, norsk og malayisk. En pt-BR-bruker vil se pt-PT-innhold før engelsk. En es-MX-bruker vil se es-419, deretter es, før standardlokaliteten.
8

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.

Terminal
# 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,de
Oversett trinnvis: når du legger til nye nøkler i kilde-ARB-filen din, bør du bare oversette differansen i stedet for å regenerere alle filene. Dette bevarer eventuelle menneskelig gjennomgåtte oversettelser og holder ARB-metadataene dine intakte.

Automatiser oversettelseskvalitet

Fang opp manglende nøkler og ødelagte plassholdere før de sendes ut, med i18n-validate. Test brukergrensesnittet ditt med pseudo-oversettelser ved hjelp av i18n-pseudo før de ekte oversettelsene er klare.

Vanlige fallgruver

Oversettelsesfiler blir ikke funnet ved kjøretid

ARB-/JSON-filene dine må deklareres under assets-seksjonen i pubspec.yaml. Mangler du dette trinnet, kan ikke Flutter finne filene ved kjøretid selv om de finnes på disken. Legg til: assets: - assets/translations/

Ugyldig syntaks i ARB-fil

ARB-filer følger streng JSON-syntaks: ingen avsluttende kommaer, ingen enkle anførselstegn og ingen kommentarer. Én syntaksfeil kan hindre hele filen i å lastes inn uten å gi noen feilmelding. Valider ARB-filene dine med en JSON-linter før du feilsøker oversettelsesproblemer.

Oversettelsesendringer vises ikke ved hot reload

easy_localization mellomlagrer oversettelser i minnet. Å legge til nye nøkler eller endre eksisterende oversettelser kan kreve en fullstendig hot restart (ikke hot reload) for å tre i kraft. Under utvikling bør du bruke hot restart (Shift+R) etter at du har redigert oversettelsesfiler.

Hardkodet venstre/høyre ødelegger RTL

Å bruke EdgeInsets.only(left: 16) i stedet for EdgeInsetsDirectional.only(start: 16) hindrer Flutter i å speilvende layouten din for RTL-språk. Søk gjennom kodebasen din etter EdgeInsets, Alignment og BorderRadius uten Directional-suffikset.

Anbefalt filstruktur

Project Structure
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.yaml

Prøv i18n Agent nå

Slipp oversettelsesfilen din her

JSON, YAML, PO, XML, CSV, Markdown, Properties

eller klikk for å bla gjennom

Målspråk

Ingen registrering krevesUmiddelbart estimat

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.

Terminal
flutter pub add locale_chain
Configuration
import '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 →

Ofte stilte spørsmål