Mobilni razvoj
FlutterInternacionalizacijaLokalizacijaCI/CDRazvoj mobilnih aplikacija

Flutter vodič za i18n/L10n: množine, RTL, fallbackovi localea i CI provjere

AO
Adrijan Omićević
·12 min čitanja

# Što ćete izgraditi u ovom vodiču za Flutter internacionalizaciju#

Ovaj vodič prikazuje produkcijski spremno postavljanje lokalizacije u Flutteru pomoću ARB datoteka, Flutter gen-l10n i ICU sintakse poruka. Implementirat ćete množine i rod, rasporede s desna na lijevo (RTL), ponašanje fallbacka localea te formatiranje datuma i brojeva.

Također ćete dodati CI provjere koje ruše build kada su ARB datoteke neispravne, ključevi nedostaju ili je generirani localization kod izvan sinkronizacije. To je važno jer su greške u lokalizaciji visoko utjecajne i lako promaknu code reviewu, posebno kada se promjene često isporučuju.

# Preduvjeti#

ZahtjevVerzijaNapomene
Flutter3.22 ili novijigen-l10n je stabilan i široko podržan
DartDolazi s FlutteromDržite SDK prikovan (pinned) preko FVM-a ili CI-ja
intl0.19 ili novijiZa formatiranje datuma i brojeva
GitHub ActionsBilo kojaPrimjer CI workflowa koristi Ubuntu runner

ℹ️ Napomena: Ako već imate robustan pipeline, integrirajte provjere iz ovog vodiča u postojeći graf poslova. Za širi pregled pipelinea pogledajte Flutter CI/CD: GitHub Actions, Codemagic, Fastlane.

# Korak 1: Omogućite Flutter lokalizaciju i generirajte AppLocalizations#

Flutterov ugrađeni workflow za lokalizaciju koristi ARB datoteke i generira snažno tipiziran localization API. Time izbjegavate krhke string-based lookupove i nedostajući ključevi postaju očiti već pri kompilaciji.

1) Dodajte ovisnosti#

Dodajte localization SDK i intl:

YAML
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: ^0.19.0

Pokrenite:

Bash
flutter pub get

2) Konfigurirajte gen-l10n#

Dodajte l10n konfiguracijsku datoteku:

YAML
# l10n.yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-class: AppLocalizations
synthetic-package: false
nullable-getter: false

Kreirajte direktorij i prvu ARB datoteku:

JSON
// lib/l10n/app_en.arb
{
  "@@locale": "en",
  "appTitle": "Acme Wallet",
  "@appTitle": {
    "description": "App name shown in the system app switcher"
  }
}

Generirajte lokalizacije:

Bash
flutter gen-l10n

3) Povežite lokalizaciju u MaterialApp#

Ažurirajte ulaznu točku aplikacije:

Dart
// lib/main.dart
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'l10n/app_localizations.dart';
 
void main() => runApp(const MyApp());
 
class MyApp extends StatelessWidget {
  const MyApp({super.key});
 
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      onGenerateTitle: (context) => AppLocalizations.of(context)!.appTitle,
      localizationsDelegates: const [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: AppLocalizations.supportedLocales,
      home: const Scaffold(body: Center(child: HomeTitle())),
    );
  }
}
 
class HomeTitle extends StatelessWidget {
  const HomeTitle({super.key});
 
  @override
  Widget build(BuildContext context) {
    final l10n = AppLocalizations.of(context)!;
    return Text(l10n.appTitle);
  }
}

Zašto je ovo važno: dobivate compile-time nazive metoda za svoje stringove, a Flutter automatski bira ispravan locale iz postavki uređaja kada je podržan.

💡 Savjet: Commitajte generiranu localization datoteku u repozitorij kada timu koristi lakše praćenje diffa i konzistentni buildovi. Zatim to provedite u CI-ju tako da build padne ako generiranje promijeni verzionirane datoteke.

# Korak 2: Dodajte fallbackove localea koji se ponašaju predvidljivo#

Problemi s fallbackom localea uzrokuju najuočljivije bugove u produkciji: korisnici vide prazne oznake, pogrešne jezike ili djelomične prijevode. Flutterovu rezoluciju možete kontrolirati i trebate definirati kako se ponašati s regionalnim varijantama.

Preporučena strategija za supported locales#

Podržite localee samo s jezikom te mali set regionalno specifičnih localea kada je potrebno:

LocaleKada koristitiPrimjer
enZadani za engleskiVećina aplikacija
en_GBRegionalni pravopis i formati datumaUK tržište
ptBrazilski i europski portugalski dijele dovoljno tekstaRani stadij
pt_BR i pt_PTTerminologija se bitno razlikujeFintech, aplikacije s puno pravnih tekstova

Dodajte callback za rezoluciju localea#

To vam daje eksplicitna fallback pravila, npr. fallback s en_AU na en:

Dart
// inside MaterialApp
localeResolutionCallback: (deviceLocale, supportedLocales) {
  if (deviceLocale == null) return const Locale('en');
 
  for (final locale in supportedLocales) {
    final sameLanguage = locale.languageCode == deviceLocale.languageCode;
    final sameCountry = locale.countryCode == deviceLocale.countryCode;
 
    if (sameLanguage && (locale.countryCode == null || sameCountry)) {
      return locale;
    }
  }
 
  for (final locale in supportedLocales) {
    if (locale.languageCode == deviceLocale.languageCode) return locale;
  }
 
  return const Locale('en');
},

Zašto je ovo važno: fallback “samo jezik” pomaže izbjeći isporuku desetaka regionalnih ARB datoteka u ranoj fazi, a ipak u većini slučajeva poštuje očekivanja korisnika.

⚠️ Upozorenje: Izbjegavajte globalno forsirati locale tijekom razvoja i zatim zaboraviti ukloniti. Hard-codeani locale može završiti u produkciji i uzrokovati da aplikacija ignorira korisničke postavke.

# Korak 3: ICU množine i rod — ispravno#

Pravila množine značajno se razlikuju po jezicima. Engleski ima dva oblika, arapski šest, a slavenski jezici više oblika ovisno o broju. Oslanjanje na ručnu logiku tipa if count == 1 brzo puca.

Flutterove ARB poruke podržavaju ICU sintaksu. Generator ih pretvara u tipizirane Dart metode.

Množine s ICU-om#

Dodajte poruku s množinama:

JSON
// lib/l10n/app_en.arb
{
  "@@locale": "en",
  "itemsInCart": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemsInCart": {
    "description": "Label showing number of items in the cart",
    "placeholders": {
      "count": { "type": "int" }
    }
  }
}

Hrvatski primjer s više oblika množine:

JSON
// lib/l10n/app_hr.arb
{
  "@@locale": "hr",
  "itemsInCart": "{count, plural, =0{Nema stavki} one{{count} stavka} few{{count} stavke} other{{count} stavki}}",
  "@itemsInCart": {
    "description": "Broj stavki u košarici",
    "placeholders": {
      "count": { "type": "int" }
    }
  }
}

Koristite u kodu:

Dart
final l10n = AppLocalizations.of(context)!;
Text(l10n.itemsInCart(cartCount));

Zašto je ovo važno: ICU kategorije množine poput one, few i other su specifične po jeziku. Lokalizacijski sustav odlučuje koji je oblik ispravan.

Rod ili druga selekcijska logika#

Praktičan pristup je select sa string selektorom. Držite ga jednostavnim i konzistentnim kroz jezike.

JSON
// lib/l10n/app_en.arb
{
  "invitedUser": "{gender, select, male{He invited you} female{She invited you} other{They invited you}}",
  "@invitedUser": {
    "placeholders": {
      "gender": { "type": "String" }
    }
  }
}

Pozovite:

Dart
Text(l10n.invitedUser(userGender)); // "male", "female", or "other"

🎯 Ključna poruka: Množine i rod su prevoditeljski problem, ne problem UI logike. Grananje držite izvan widgeta i unutar ICU poruka.

# Korak 4: RTL podrška bez regresija u layoutu#

RTL nije samo smjer teksta. Utječe na poravnanje, padding, ikone, animacije i ponekad prijelaze navigacije. Ako RTL ne testirate eksplicitno, isporučit ćete odrezane headere i krivo poravnate gumbe.

Koristite razmake svjesne smjera (direction-aware)#

Preferirajte direction-aware API-je:

Što trebateKoristite ovoIzbjegavajte ovo
Horizontalni paddingEdgeInsetsDirectional.only(start: 16, end: 16)EdgeInsets.only(left: 16, right: 16)
PoravnanjeAlignmentDirectional.centerStartAlignment.centerLeft
Positioned offsetiPositionedDirectional(start: 0)Positioned(left: 0)
Redoslijed u RowRow(textDirection: ...) samo kad je nužnoRučno okretanje listi posvuda

Primjer:

Dart
Padding(
  padding: const EdgeInsetsDirectional.only(start: 16, end: 16),
  child: Align(
    alignment: AlignmentDirectional.centerStart,
    child: Text(l10n.appTitle),
  ),
)

Dodajte RTL locale i testirajte ga#

Dodajte arapski ili hebrejski ARB, čak i ako je u početku minimalan:

JSON
// lib/l10n/app_ar.arb
{
  "@@locale": "ar",
  "appTitle": "محفظة أكمي"
}

Pokrenite flutter gen-l10n i aplikacija se sada može prikazati u RTL kada je locale uređaja arapski.

Hvatanje regresija golden testovima#

Golden testovi su najbrži način da spriječite drift RTL layouta. Dodajte golden test za isti widget u LTR i RTL te usporedite snapshotove.

Ako želite strukturiranu test strategiju oko ovoga, uskladite je s testnom piramidom. Pogledajte Flutter testing pyramid: unit, widget, integration, golden.

# Korak 5: Formatiranje datuma, vremena, brojeva i valuta#

Hard-codeanje formata globalno puca. SAD koristi MM/dd, većina Europe dd/MM, a decimalni separatori variraju po localeu. Formatiranje također utječe na povjerenje u fintech i e-commerce aplikacijama, gdje pogrešan format valute može brzo povećati broj upita podršci.

Formatiranje datuma i vremena#

Koristite intl s aktivnim localeom:

Dart
import 'package:intl/intl.dart';
 
String formatOrderDate(DateTime dt, String locale) {
  final df = DateFormat.yMMMd(locale);
  return df.format(dt);
}

U widgetu:

Dart
final locale = Localizations.localeOf(context).toLanguageTag();
Text(formatOrderDate(order.createdAt, locale));

Formatiranje brojeva i valuta#

Dart
import 'package:intl/intl.dart';
 
String formatPrice(num value, String locale, String currencyCode) {
  final nf = NumberFormat.simpleCurrency(locale: locale, name: currencyCode);
  return nf.format(value);
}

Zašto je ovo važno: ispravno formatiranje smanjuje zbunjenost korisnika i povećava konverziju. Istraživanja Baymard Institutea o upotrebljivosti checkouta dosljedno ističu jasnoću i povjerenje kao pokretače konverzije, a lokalizirani prikaz valute je ključni dio te jasnoće.

ℹ️ Napomena: Vrijednosti poslovne logike držite u kanonskim jedinicama, a formatirajte samo na prezentacijskom sloju. Spremajte 1234.56 kao broj, ne kao unaprijed formatiran string.

# Korak 6: Dodajte CI provjere za valjanost ARB-a i ključeve koji nedostaju#

Lokalizacijski kvarovi su skupi jer često neprimijećeni dođu do produkcije. Ključ koji nedostaje može se pojaviti samo u jednom localeu, na jednom ekranu, iza jednog feature flaga. CI treba uhvatiti problem čim se ARB datoteka promijeni.

Cilj je srušiti build kada se dogodi bilo što od sljedećeg:

  • ARB JSON nije valjan
  • ICU poruke nisu valjane i ne mogu se generirati
  • Locale datotekama nedostaju ključevi u odnosu na template
  • Generirani localization output se promijeni, ali nije commit-an

Što validirati#

ProvjeraZašto je važnaGdje pokretati
JSON parse ARB datotekaSprječava runtime ili generation failureCI i pre-commit
Paritet ključeva s templateomSprječava nedostajuće stringove po localeuCI
gen-l10n generiranjeOsigurava da se ICU poruke kompajlirajuCI
Nema necommit-anih generiranih promjenaOdržava build determinističnimCI

Primjer GitHub Actions workflowa#

Kreirajte ovu workflow datoteku:

YAML
# .github/workflows/l10n-checks.yml
name: L10n checks
 
on:
  pull_request:
    paths:
      - "lib/l10n/**"
      - "l10n.yaml"
      - "pubspec.yaml"
      - ".github/workflows/l10n-checks.yml"
 
jobs:
  l10n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: "3.24.0"
          cache: true
 
      - name: Pub get
        run: flutter pub get
 
      - name: Validate ARB JSON and key parity
        run: dart run tool/arb_check.dart
 
      - name: Generate localizations
        run: flutter gen-l10n
 
      - name: Fail if generated files changed
        run: |
          git status --porcelain
          test -z "$(git status --porcelain)"

Zašto je ovo važno: zadnji korak pretvara nedostajuće commitove generiranja u hard failure, što sprječava suptilne nesukladnosti između developer strojeva i CI-ja.

💡 Savjet: Ako vaš pipeline već pokreće Flutter build korake, držite ovaj job odvojeno i brzo. Namjenski l10n job obično se završi za manje od 2 minute na GitHub runnerima i daje jasnu povratnu informaciju na PR-ovima.

Skripta za validaciju ARB-a s paritetom ključeva#

Napravite malu Dart skriptu koja provjerava JSON parsing i nameće da svaki locale sadrži sve ključeve iz templatea. Držite je strogom. Ako želite djelomične prijevode, riješite to eksplicitnom politikom, ne tihim izostavljanjem.

Dart
// tool/arb_check.dart
import 'dart:convert';
import 'dart:io';
 
void main() {
  final dir = Directory('lib/l10n');
  final files = dir
      .listSync()
      .whereType<File>()
      .where((f) => f.path.endsWith('.arb'))
      .toList();
 
  if (files.isEmpty) {
    stderr.writeln('No ARB files found in lib/l10n');
    exit(1);
  }
 
  final template = File('lib/l10n/app_en.arb');
  final templateJson = jsonDecode(template.readAsStringSync()) as Map;
  final templateKeys = templateJson.keys.where((k) => !k.startsWith('@')).toSet();
 
  var ok = true;
 
  for (final file in files) {
    final map = jsonDecode(file.readAsStringSync()) as Map;
    final keys = map.keys.where((k) => !k.startsWith('@')).toSet();
    final missing = templateKeys.difference(keys);
 
    if (missing.isNotEmpty) {
      ok = false;
      stderr.writeln('Missing keys in ${file.path}: ${missing.join(', ')}');
    }
  }
 
  if (!ok) exit(2);
  stdout.writeln('ARB checks passed for ${files.length} files.');
}

Dodajte je u pubspec.yaml kao dev tool ovisnost samo ako trebate dodatne pakete. Ova skripta koristi samo dart:convert i dart:io, pa radi bez dodatnih ovisnosti.

Spriječite prijevode koji nedostaju, a ipak nastavite isporučivati#

Ako želite privremeno dopustiti neprevedene stringove, koristite namjernu politiku placeholdera. Primjerice, zahtijevajte da stringovi postoje, ali smiju sadržavati marker poput TODO:. Tada CI može padati tek kada se kreira release grana ili kada TODO: markeri ostanu.

Praktična tablica politike:

FazaDopušteno u non-template localeimaPonašanje CI-ja
Feature granaPlaceholder tekst poput TODO: translateUpozori, ne ruši
Main granaBez placeholderaRuši
Release tagBez placeholdera i paritet ključeva obvezanRuši

Implementacija upozorenja naspram rušenja ovisi o vašoj branching strategiji, ali ključna poanta je da odluku donosite eksplicitno.

Za šire CI obrasce za Flutter aplikacije, uključujući caching i paralelne jobove, pogledajte Flutter CI/CD: GitHub Actions, Codemagic, Fastlane.

# Korak 7: Česte zamke koje uzrokuju produkcijske bugove u lokalizaciji#

Ovo su problemi koje najčešće viđamo u stvarnim Flutter codebaseovima.

Hard-codeane pretpostavke o left i right#

Korištenje left i right ruši RTL. Koristite directional varijante kroz cijeli UI, posebno u zajedničkim komponentama.

Ako održavate UI kit, ugradite direction-aware razmake u widgete dizajnerskog sustava. To se dobro nadovezuje na konzistentne tipografske i theming prakse opisane u Flutter design system theming: Material 3, dynamic color, typography.

Formatiranje s pogrešnim locale stringom#

intl formatiranje očekuje locale identifikatore poput en, en_US ili BCP-47 language tagove. Koristite toLanguageTag() radi konzistentnosti i izbjegnite miješanje formata u kodu.

Nedostajući placeholder metadata#

Bez tipova placeholdera generator može pogrešno zaključiti tipove ili proizvesti manje korisne API-je. Uvijek definirajte placeholder-e za ICU poruke, posebno za count, price ili datume.

Ne testiranje non-English localea dovoljno rano#

Već i jedan RTL locale u aplikaciji prisiljava layout da bude ispravan posvuda. Dodajte arapski rano, čak i ako je samo za smoke testove i golden snapshote.

# Ključne poruke#

  • Koristite Flutter gen-l10n s ARB datotekama kako biste dobili snažno tipizirane localization metode i smanjili runtime bugove string lookupova.
  • Implementirajte množine i rod ICU sintaksom u ARB vrijednostima, ne grananjem na razini widgeta.
  • Osigurajte RTL stabilnost korištenjem directional padding i alignment API-ja te dodajte barem jedan RTL locale za kontinuirano testiranje.
  • Formatirajte datume, brojeve i valutu pomoću intl i aktivnog localea, a sirove vrijednosti držite u poslovnoj logici.
  • Dodajte CI provjere koje validiraju ARB JSON, provjeravaju paritet ključeva s templateom, pokreću gen-l10n i ruše build kod necommit-anih generiranih promjena.

# Zaključak#

Pouzdano postavljanje lokalizacije je kombinacija ispravnih ICU poruka, UI koda svjesnog smjera, predvidljivih fallbackova localea i CI provedbe. Ako implementirate korake iznad, spriječit ćete najčešće i18n regresije i učiniti promjene prijevoda sigurnima za kontinučnu isporuku.

Ako želite da Samioda napravi audit vašeg Flutter lokalizacijskog workflowa, doda RTL i golden pokrivenost ili poveže ove provjere u vaš pipeline, javite se putem naših usluga razvoja mobilnih aplikacija i pomoći ćemo vam isporučivati višejezične Flutter aplikacije bez iznenađenja.

FAQ

Share
A
Adrijan OmićevićOsnivač i senior developer

Osnivač i senior developer u Samiodi. 8+ godina iskustva u izradi React, Next.js, Flutter i n8n rješenja za klijente diljem Europe.

Trebate pomoć s projektom?

Gradimo prilagođena rješenja koristeći tehnologije iz ovog članka. Senior tim, fiksne cijene.