# Š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#
| Zahtjev | Verzija | Napomene |
|---|---|---|
| Flutter | 3.22 ili noviji | gen-l10n je stabilan i široko podržan |
| Dart | Dolazi s Flutterom | Držite SDK prikovan (pinned) preko FVM-a ili CI-ja |
| intl | 0.19 ili noviji | Za formatiranje datuma i brojeva |
| GitHub Actions | Bilo koja | Primjer 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:
# pubspec.yaml
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: ^0.19.0Pokrenite:
flutter pub get2) Konfigurirajte gen-l10n#
Dodajte l10n konfiguracijsku datoteku:
# 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: falseKreirajte direktorij i prvu ARB datoteku:
// lib/l10n/app_en.arb
{
"@@locale": "en",
"appTitle": "Acme Wallet",
"@appTitle": {
"description": "App name shown in the system app switcher"
}
}Generirajte lokalizacije:
flutter gen-l10n3) Povežite lokalizaciju u MaterialApp#
Ažurirajte ulaznu točku aplikacije:
// 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:
| Locale | Kada koristiti | Primjer |
|---|---|---|
en | Zadani za engleski | Većina aplikacija |
en_GB | Regionalni pravopis i formati datuma | UK tržište |
pt | Brazilski i europski portugalski dijele dovoljno teksta | Rani stadij |
pt_BR i pt_PT | Terminologija se bitno razlikuje | Fintech, aplikacije s puno pravnih tekstova |
Dodajte callback za rezoluciju localea#
To vam daje eksplicitna fallback pravila, npr. fallback s en_AU na en:
// 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:
// 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:
// 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:
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.
// 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:
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 trebate | Koristite ovo | Izbjegavajte ovo |
|---|---|---|
| Horizontalni padding | EdgeInsetsDirectional.only(start: 16, end: 16) | EdgeInsets.only(left: 16, right: 16) |
| Poravnanje | AlignmentDirectional.centerStart | Alignment.centerLeft |
| Positioned offseti | PositionedDirectional(start: 0) | Positioned(left: 0) |
| Redoslijed u Row | Row(textDirection: ...) samo kad je nužno | Ručno okretanje listi posvuda |
Primjer:
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:
// 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:
import 'package:intl/intl.dart';
String formatOrderDate(DateTime dt, String locale) {
final df = DateFormat.yMMMd(locale);
return df.format(dt);
}U widgetu:
final locale = Localizations.localeOf(context).toLanguageTag();
Text(formatOrderDate(order.createdAt, locale));Formatiranje brojeva i valuta#
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.56kao 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#
| Provjera | Zašto je važna | Gdje pokretati |
|---|---|---|
| JSON parse ARB datoteka | Sprječava runtime ili generation failure | CI i pre-commit |
| Paritet ključeva s templateom | Sprječava nedostajuće stringove po localeu | CI |
| gen-l10n generiranje | Osigurava da se ICU poruke kompajliraju | CI |
| Nema necommit-anih generiranih promjena | Održava build determinističnim | CI |
Primjer GitHub Actions workflowa#
Kreirajte ovu workflow datoteku:
# .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.
// 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:
| Faza | Dopušteno u non-template localeima | Ponašanje CI-ja |
|---|---|---|
| Feature grana | Placeholder tekst poput TODO: translate | Upozori, ne ruši |
| Main grana | Bez placeholdera | Ruši |
| Release tag | Bez placeholdera i paritet ključeva obvezan | Ruš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
Osnivač i senior developer u Samiodi. 8+ godina iskustva u izradi React, Next.js, Flutter i n8n rješenja za klijente diljem Europe.
Više iz kategorije Mobilni razvoj
Sve →Flutter WebView vs nativni ekrani: kada ugraditi web, kako riješiti autentikaciju, plaćanja i deep linkove
Praktična usporedba Flutter WebView-a i nativnih ekrana u 2026.: performanse, sigurnost, UX i održavanje, uz pravila odlučivanja za auth SSO, usklađenost plaćanja, deep linkove i analitičku instrumentaciju.
Flutter Repository Pattern kako treba: DTO-ovi, mapperi, tipizirane greške i testabilnost
Praktičan Flutter repository pattern koji se stvarno može testirati: jasne granice između DTO-a i domene, perzistencija, paginacija, cacheiranje i tipizirani failurei uz unit testove.
Flutter autentifikacija u 2026.: Firebase vs Supabase vs Custom OAuth (prednosti, nedostaci i kriteriji odluke)
Praktična usporedba pristupa autentifikaciji u Flutteru u 2026. — Firebase Auth vs Supabase Auth vs Custom OAuth — s matricom odluke, napomenama za implementaciju i iOS/Android zamkama.
Trebate pomoć s projektom?
Gradimo prilagođena rješenja koristeći tehnologije iz ovog članka. Senior tim, fiksne cijene.
Povezani članci
Strategija testiranja u Flutteru: unit, widget, integracijski i golden testovi za brz i pouzdan CI (2026)
Praktična strategija testiranja u Flutteru temeljena na piramidi testiranja: kada koristiti unit, widget, integracijske i golden testove, kako smanjiti flakiness i kako sve pokretati brzo u CI-u.
Vodič za pristupačnost u Flutteru: Semantics, redoslijed fokusa i dinamički tekst kako treba
Praktičan vodič za pristupačnost u Flutteru za 2026.: Semantics oznake, ispravan redoslijed fokusa, navigacija tipkovnicom, kontrast i skaliranje teksta uz konkretne korake testiranja za TalkBack i VoiceOver.
Flutter navigacija s go_router: duboke poveznice, auth guardovi, ugniježđene rute i podrška za web
Vodič spreman za produkciju za Flutter go_router deep links, uključujući auth preusmjeravanja, ShellRoute layout, ugniježđenu navigaciju, stanje vođeno URL-om i testiranje deep linkova za iOS, Android i web.