Localizzazione Flutter: file ARB, intl e gen-l10n spiegati

Usa un solo generatore di localizzazione e rendi espliciti i percorsi di input e output. L'esempio seguente presuppone un'applicazione Flutter esistente con i propri vincoli sull'SDK e una normale configurazione di progetto.

Unisci le voci pertinenti in pubspec.yaml; non duplicare le sezioni dependencies o flutter:

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

flutter:
  generate: true

Risolvi le dipendenze con flutter pub get. La voce intl: any segue lo schema di configurazione ufficiale e consente alla risoluzione delle dipendenze di scegliere la versione compatibile con l'SDK Flutter; mantieni il lockfile dell'applicazione e il normale processo di revisione delle dipendenze.

Crea l10n.yaml nella radice del progetto:

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

Usa la guida all'internazionalizzazione di Flutter aggiornata per la configurazione specifica dell'SDK. Nel processo moderno i file di localizzazione generati appartengono all'albero dei sorgenti dell'applicazione. L'esempio importa da lib/l10n; evita di copiare in una nuova configurazione un vecchio import sintetico package:flutter_gen. Consulta la nota sulla migrazione dei sorgenti generati.

Crea lib/l10n/app_en.arb:

{
  "@@locale": "en",
  "appTitle": "Reading room",
  "@appTitle": {
    "description": "Title of the sample reading application"
  },
  "welcomeName": "Welcome, {name}",
  "@welcomeName": {
    "description": "Greeting on the home screen",
    "placeholders": {
      "name": {"type": "String", "example": "Sam"}
    }
  },
  "savedBooks": "{count, plural, =0{No saved books} one{1 saved book} other{{count} saved books}}",
  "@savedBooks": {
    "description": "Number of books saved to the user's library",
    "placeholders": {
      "count": {"type": "int"}
    }
  },
  "readingState": "{state, select, active{Reading now} paused{Reading paused} other{Ready to read}}",
  "@readingState": {
    "description": "Reading status; state is active, paused or another value",
    "placeholders": {
      "state": {"type": "String"}
    }
  }
}

Crea lib/l10n/app_es.arb:

{
  "@@locale": "es",
  "appTitle": "Sala de lectura",
  "welcomeName": "Te damos la bienvenida, {name}",
  "savedBooks": "{count, plural, =0{No hay libros guardados} one{1 libro guardado} other{{count} libros guardados}}",
  "readingState": "{state, select, active{Leyendo ahora} paused{Lectura en pausa} other{Todo listo para leer}}"
}

Il modello contiene i metadati dei segnaposto usati dal generatore. Il file localizzato conserva le chiavi dei messaggi, i nomi dei segnaposto e gli identificatori di select, modificando la formulazione visibile agli utenti. Questi esempi in spagnolo illustrano il meccanismo; i testi di produzione devono ricevere una revisione madrelingua nel loro contesto di prodotto reale.

Esegui flutter gen-l10n dopo aver aggiunto o modificato le risorse. Considera gli errori del generatore come problemi concreti delle risorse e risolvili prima di integrare i file in una release.

L'esempio seguente va inserito in lib/main.dart dopo la generazione:

import 'package:flutter/material.dart';
import 'l10n/app_localizations.dart';

void main() => runApp(const ReadingApp());

class ReadingApp extends StatelessWidget {
  const ReadingApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: const ReadingHome(),
    );
  }
}

class ReadingHome extends StatelessWidget {
  const ReadingHome({super.key});

  @override
  Widget build(BuildContext context) {
    final messages = AppLocalizations.of(context)!;
    return Scaffold(
      appBar: AppBar(title: Text(messages.appTitle)),
      body: Padding(
        padding: const EdgeInsetsDirectional.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(messages.welcomeName('Sam')),
            Text(messages.savedBooks(3)),
            Text(messages.readingState('active')),
          ],
        ),
      ),
    );
  }
}

L'API generata rende visibile nel codice la differenza tra un messaggio semplice e un messaggio con argomenti. appTitle si legge come valore; welcomeName, savedBooks e readingState ricevono i valori necessari per comporre i rispettivi messaggi.

Prima di scegliere, consulta la documentazione di easy_localization e la documentazione di GetX aggiornate. Testa con i tuoi messaggi reali il comportamento di fallback, i parametri, le categorie di plurale e i processi di estrazione. Un'API comoda per le stringhe in inglese non garantisce la copertura di tutte le lingue che intendi rilasciare.

intl non è una piattaforma di gestione delle traduzioni alternativa. Fornisce utility di internazionalizzazione usate nei processi di localizzazione. gen-l10n genera gli accessor dell'applicazione dalle risorse ARB. Anche il pacchetto intl_utils genera codice di localizzazione, ma la sua pagina risultava contrassegnata come discontinued alla verifica del 30 ottobre 2026. Controlla lo stato di manutenzione prima di adottarlo in un nuovo progetto.

Usa una matrice di test pratica:

Le FAQ web di Flutter descrivono la sua attenzione alle esperienze applicative e consigliano un approccio orientato ai documenti per i contenuti web statici e ricchi di testo. Valuta pagine marketing, di assistenza ed editoriali separate basate su HTML quando devono posizionarsi nella ricerca organica.

Mantieni la terminologia allineata tra l'app e queste pagine pubbliche. Un visitatore arrivato dalla ricerca deve riconoscere il nome della funzionalità passando dalla landing page localizzata all'applicazione, anche quando le due superfici usano sistemi di rendering diversi.

I formati documentati per i progetti software di Smartcat includono importazioni JSON, YAML, XML Android, .strings iOS e LocJSON. La documentazione consultata per questa guida non conferma il supporto nativo dell'ARB né un processo di conversione da ARB a JSON già testato. Non dare per scontato che cambiare l'estensione di un file ne dimostri la compatibilità. Consulta la documentazione sui progetti software.

Usa quanto segue come procedura di convalida da proporre al tuo team di implementazione, non come ricetta di connettore già testata: