Localizzazione Flutter: file ARB, intl e automazione

Il sistema di localizzazione integrato di Flutter utilizza file ARB (Application Resource Bundle) e il pacchetto intl per offrire esperienze completamente native in qualsiasi lingua. Questa guida copre tutto, dalla configurazione del progetto e i dettagli del formato ARB al cambio di lingua, alla pluralizzazione e all'automazione delle traduzioni con l10n.dev.

Cos'è la localizzazione Flutter?

La localizzazione Flutter è l'approccio ufficiale per adattare la tua app a più lingue e regioni. Si basa sui file ARB per archiviare le stringhe tradotte e sul generatore di codice flutter_gen per produrre accessors Dart type-safe. In fase di esecuzione, Flutter seleziona il file ARB corretto in base alla lingua del dispositivo: non è necessario riavviare quando si cambiano le impostazioni locali a livello di codice.

Configurazione del progetto

La pipeline di localizzazione di Flutter è guidata da due file di configurazione: pubspec.yaml e l10n.yaml. Abilita la generazione del codice in pubspec.yaml e indica a Flutter la tua directory ARB.

1. Aggiorna pubspec.yaml

Aggiungi flutter_localizations e intl come dipendenze, quindi abilita il flag generate in modo che Flutter generi automaticamente le classi di localizzazione Dart dai tuoi file ARB.

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

2. Crea l10n.yaml

Posiziona un file l10n.yaml nella root del tuo progetto per configurare la directory ARB, il file modello e il nome del file di output generato.

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Il formato file ARB

ARB (Application Resource Bundle) è un formato basato su JSON progettato specificamente per l'internazionalizzazione di Flutter. Ogni chiave è mappata su una stringa traducibile e le chiavi di metadati opzionali (con prefisso @) contengono descrizioni, definizioni di segnaposti e contesto per i traduttori.

• @@locale: Dichiara la lingua per il file (es. "en", "fr", "zh_CN"). l10n.dev aggiorna automaticamente questo valore con il codice della lingua di destinazione.
• @@last_modified: Timestamp dell'ultima modifica. l10n.dev lo imposta automaticamente sul timestamp UTC corrente durante la generazione dei file tradotti.
• @key metadata: Le voci di metadati come descrizione, esempio e segnaposti NON vengono tradotte per impostazione predefinita: rimangono invariate per preservare il contesto per i traduttori. Abilita l'impostazione translateMetadata se desideri che vengano tradotte.
• Segnaposti e messaggi ICU: Le stringhe possono contenere segnaposti denominati ({name}) e la sintassi dei messaggi ICU per la pluralizzazione e la selezione: tutto ciò viene preservato correttamente durante la traduzione.

File ARB sorgente (inglese)

{
  "@@locale": "en",
  "@@last_modified": "2026-01-15T10:30:00Z",

  "appTitle": "My App",
  "@appTitle": {
    "description": "The title of the application"
  },

  "welcome": "Welcome, {name}!",
  "@welcome": {
    "description": "Welcome message shown on the home screen",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  },

  "unreadMessages": "{count, plural, =0{No unread messages} =1{1 unread message} other{{count} unread messages}}",
  "@unreadMessages": {
    "description": "Number of unread messages",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

File ARB tradotto (francese)

Dopo la traduzione, le stringhe dell'interfaccia utente sono localizzate mentre la struttura dei metadati rimane intatta. l10n.dev aggiorna automaticamente @@locale e @@last_modified.

{
  "@@locale": "fr",
  "@@last_modified": "2026-01-15T10:30:01Z",

  "appTitle": "Mon Application",
  "@appTitle": {
    "description": "The title of the application"
  },

  "welcome": "Bienvenue, {name} !",
  "@welcome": {
    "description": "Welcome message shown on the home screen",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  },

  "unreadMessages": "{count, plural, =0{Aucun message non lu} =1{1 message non lu} other{{count} messages non lus}}",
  "@unreadMessages": {
    "description": "Number of unread messages",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

Convenzioni di denominazione dei file

I file ARB seguono uno schema di denominazione semplice: un prefisso (per impostazione predefinita app_) seguito dal codice della lingua e dall'estensione .arb. Flutter e l10n.dev utilizzano i trattini bassi per separare i codici di lingua e regione.

# Default pattern (recommended)
app_en.arb
app_fr.arb
app_en_US.arb          # Locale with region (underscore format)
app_zh_CN.arb          # Chinese Simplified

# Custom prefix patterns also supported
my_app_en.arb
my_app_fr.arb

# Note: ARB files use underscores, not hyphens
# ✓  app_en_US.arb
# ✗  app_en-US.arb

Struttura del progetto

Organizza tutti i tuoi file ARB all'interno di una cartella l10n dedicata in lib/. Il generatore di codice di Flutter li rileva automaticamente in base all'impostazione arb-dir in l10n.yaml e genera classi Dart pronte all'uso.

lib/
├── l10n/
│   ├── app_en.arb        ← Source (English)
│   ├── app_fr.arb        ← French
│   ├── app_de.arb        ← German
│   ├── app_ja.arb        ← Japanese
│   ├── app_zh_CN.arb     ← Chinese Simplified
│   └── app_es.arb        ← Spanish
├── main.dart
└── ...

# Generated output (do not edit manually)
.dart_tool/
└── flutter_gen/
    └── gen_l10n/
        └── app_localizations.dart

Inizializzazione

Collega la classe di localizzazione Dart generata con MaterialApp fornendo localizationsDelegates e supportedLocales. Flutter risolverà quindi i dati ARB corretti per la lingua del dispositivo.

Configurazione MaterialApp

Passa i quattro delegati richiesti (il tuo AppLocalizations.delegate generato più i tre delegati dell'SDK Flutter) ed elenca ogni lingua supportata dalla tua app. Usa AppLocalizations.of(context)! ovunque nell'albero dei widget per accedere alle stringhe tradotte.

import 'package:flutter/material.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',

      // Required delegates
      localizationsDelegates: const [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],

      // Supported locales
      supportedLocales: AppLocalizations.supportedLocales,

      home: const HomePage(),
    );
  }
}

// Use in a widget
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: Center(child: Text(l10n.welcome('Alice'))),
    );
  }
}

Cambio lingua a runtime

Flutter ti consente di cambiare la lingua dell'app a runtime aggiornando la proprietà locale su MaterialApp. Un pattern comune consiste nel mantenere una Locale in uno StatefulWidget o in una soluzione di gestione dello stato ed esporre un callback per modificarla. L'albero dei widget si ricostruisce automaticamente con la nuova lingua.

// Manage locale state at the app level
class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  Locale _locale = const Locale('en');

  void _changeLocale(Locale locale) {
    setState(() => _locale = locale);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      locale: _locale,
      localizationsDelegates: const [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: AppLocalizations.supportedLocales,
      home: SettingsPage(onLocaleChange: _changeLocale),
    );
  }
}

// Language selector widget
class LanguageSelector extends StatelessWidget {
  final void Function(Locale) onLocaleChange;

  const LanguageSelector({super.key, required this.onLocaleChange});

  @override
  Widget build(BuildContext context) {
    return DropdownButton<Locale>(
      value: Localizations.localeOf(context),
      items: AppLocalizations.supportedLocales
          .map((locale) => DropdownMenuItem(
                value: locale,
                child: Text(locale.toLanguageTag()),
              ))
          .toList(),
      onChanged: (locale) {
        if (locale != null) onLocaleChange(locale);
      },
    );
  }
}

Pluralizzazione

Flutter utilizza la sintassi dei messaggi ICU per la pluralizzazione all'interno dei file ARB. Il pacchetto intl gestisce tutte le categorie plurali CLDR, applicando automaticamente la forma corretta in base alle regole della lingua di destinazione.

• Usa la sintassi {count, plural, =0{...} =1{...} other{...}} all'interno dei valori delle stringhe ARB.
• Dichiara il segnaposto count con tipo int nei metadati @key.
• l10n.dev genera tutte le forme plurali richieste per ogni lingua di destinazione, incluse lingue complesse come arabo, russo e polacco, senza intervento manuale.

{
  "cartItems": "{count, plural, =0{Your cart is empty} =1{1 item in your cart} other{{count} items in your cart}}",
  "@cartItems": {
    "description": "Cart item count",
    "placeholders": {
      "count": { "type": "int" }
    }
  },

  "daysLeft": "{days, plural, =1{1 day left} other{{days} days left}}",
  "@daysLeft": {
    "description": "Days remaining",
    "placeholders": {
      "days": { "type": "int" }
    }
  }
}

Supporto ARB completo in l10n.dev

l10n.dev è progettato appositamente per funzionare perfettamente con il flusso di lavoro ARB di Flutter. Carica il tuo file ARB sorgente e ricevi traduzioni accurate e correttamente strutturate:

• Aggiornamenti automatici dei metadati: @@locale viene aggiornato con il codice della lingua di destinazione e @@last_modified viene impostato automaticamente sul timestamp UTC corrente.
• Controllo della traduzione dei metadati: Per impostazione predefinita, le voci di metadati @key (descrizione, esempio, contesto) NON vengono tradotte e rimangono invariate, mantenendo intatte le note del traduttore. Abilita l'impostazione translateMetadata per tradurle insieme alle stringhe dell'interfaccia utente.
• Prefissi file personalizzati: È supportato qualsiasi schema di denominazione: app_en.arb, my_app_en_US.arb, strings_fr.arb e altro ancora.
• Formato lingua con trattino basso: I codici lingua ARB utilizzano trattini bassi (en_US, zh_CN) invece di trattini: l10n.dev gestisce questo aspetto correttamente in modo che i file generati vengano inseriti direttamente nel tuo progetto Flutter.
• Consapevolezza della pluralizzazione: Le forme plurali ICU vengono generate per ogni lingua di destinazione secondo le regole CLDR, quindi non è necessaria alcuna modifica manuale del plurale dopo la traduzione.

Automatizza le traduzioni con npm

Usa il pacchetto npm ai-l10n per tradurre il tuo file ARB sorgente dalla riga di comando o come parte di una CI/CD pipeline. Installa una volta, quindi traduci in qualsiasi numero di lingue con un singolo comando.

# Install the CLI
npm install ai-l10n

# Translate your source ARB to multiple languages
npx ai-l10n translate lib/l10n/app_en.arb \
  --languages fr,de,ja,zh_CN,es,ko

Integrazione in una build Flutter

Puoi collegare ai-l10n direttamente al tuo processo di build Flutter in modo che le traduzioni siano sempre aggiornate prima che l'app venga compilata. Due approcci comuni sono uno script package.json o un Makefile.

Tramite script package.json

Aggiungi uno script di traduzione e usa l'hook del ciclo di vita prebuild di npm per eseguirlo automaticamente prima di ogni build. Esegui npm run build:android (o build:ios / build:web) e ai-l10n tradurrà per primo, quindi passerà il controllo a Flutter.

{
  "scripts": {
    "translate": "ai-l10n translate lib/l10n/app_en.arb --languages fr,de,ja,zh_CN,es,ko --update",
    "prebuild": "npm run translate",
    "build:android": "flutter build apk",
    "build:ios": "flutter build ios",
    "build:web": "flutter build web"
  }
}

Tramite Makefile

Se il tuo team usa Make, dichiara un target di traduzione e fai in modo che ogni target di build dipenda da esso. L'esecuzione di make build-android (o build-ios / build-all) tradurrà tutte le lingue di destinazione prima di invocare flutter build.

LANGUAGES = fr,de,ja,zh_CN,es,ko

translate:
	npx ai-l10n translate lib/l10n/app_en.arb --languages $(LANGUAGES) --update

build-android: translate
	flutter build apk

build-ios: translate
	flutter build ios

build-web: translate
	flutter build web

build-all: translate
	flutter build apk
	flutter build ios
	flutter build web

Per l'integrazione CI/CD, aggiornamenti incrementali, traduzione batch su più file ed esempi di workflow GitHub Actions, consulta la Guida all'automazione della localizzazione.

Estensione VS Code

L'estensione VS Code di l10n.dev porta la traduzione ARB di Flutter direttamente nel tuo editor. Fai clic destro su qualsiasi file ARB e traducilo nelle tue lingue di destinazione senza lasciare VS Code.

Come funziona in VS Code:

1. Apri il tuo file ARB sorgente (es. app_en.arb) nell'editor.
2. Fai clic destro nell'editor e seleziona "Translate JSON".
3. Scegli una o più lingue di destinazione (es. francese, giapponese, tedesco).
4. L'estensione crea file ARB localizzati insieme al tuo sorgente, con @@locale e @@last_modified aggiornati automaticamente.

Vedilo in azione

Ecco un esempio dal vivo della traduzione di un file ARB Flutter in uzbeko all'interno di VS Code:

Inizia a localizzare la tua app Flutter

Pronto a raggiungere utenti globali? Puoi tradurre i file ARB direttamente nell'area di lavoro l10n.dev, automatizzare con la CLI npm o tradurre direttamente all'interno di VS Code: