Localizzazione

Introduzione

La localizzazione ti permette di fornire la tua app in più lingue. Nylo Website v7 rende facile localizzare il testo utilizzando file JSON di lingua.

Ecco un esempio rapido:

lang/en.json

{
  "welcome": "Welcome",
  "greeting": "Hello {{name}}"
}

Nel tuo widget:

Text("welcome".tr())              // "Welcome"
Text("greeting".tr(arguments: {"name": "Anthony"}))  // "Hello Anthony"

Configurazione

La localizzazione è configurata in lib/config/localization.dart:

final class LocalizationConfig {
  // Default language code (matches your JSON file, e.g., 'en' for lang/en.json)
  static final String languageCode =
      getEnv('DEFAULT_LOCALE', defaultValue: "en");

  // LocaleType.device - Use device's language setting
  // LocaleType.asDefined - Use languageCode above
  static final LocaleType localeType =
      getEnv('LOCALE_TYPE', defaultValue: 'asDefined') == 'device'
          ? LocaleType.device
          : LocaleType.asDefined;

  // Directory containing language JSON files
  static const String assetsDirectory = 'lang/';

  // List of supported locales
  static const List<Locale> supportedLocales = [
    Locale('en'),
    Locale('es'),
    // Add more locales as needed
  ];

  // Fallback when a key is not found in the active locale
  static const String fallbackLanguageCode = 'en';

  // RTL language codes
  static const List<String> rtlLanguages = ['ar', 'he', 'fa', 'ur'];

  // Log warnings for missing translation keys
  static final bool debugMissingKeys =
      getEnv('DEBUG_TRANSLATIONS', defaultValue: 'false') == 'true';
}

Aggiungere File Localizzati

Aggiungi i tuoi file JSON di lingua alla directory lang/:

lang/
├── en.json   # English
├── es.json   # Spanish
├── fr.json   # French
└── ...

lang/en.json

{
  "welcome": "Welcome",
  "settings": "Settings",
  "navigation": {
    "home": "Home",
    "profile": "Profile"
  }
}

lang/es.json

{
  "welcome": "Bienvenido",
  "settings": "Configuración",
  "navigation": {
    "home": "Inicio",
    "profile": "Perfil"
  }
}

Registrazione nel pubspec.yaml

Assicurati che i tuoi file di lingua siano inclusi nel tuo pubspec.yaml:

flutter:
  assets:
    - lang/

Localizzare il Testo

Usa l'estensione .tr() o l'helper trans() per tradurre le stringhe:

// Using the .tr() extension
"welcome".tr()

// Using the trans() helper
trans("welcome")

Chiavi Annidate

Accedi alle chiavi JSON annidate utilizzando la notazione a punto:

lang/en.json

{
  "navigation": {
    "home": "Home",
    "profile": "Profile"
  }
}

"navigation.home".tr()       // "Home"
trans("navigation.profile")  // "Profile"

Argomenti

Passa valori dinamici nelle tue traduzioni utilizzando la sintassi {{key}}:

lang/en.json

{
  "greeting": "Hello {{name}}",
  "items_count": "You have {{count}} items"
}

"greeting".tr(arguments: {"name": "Anthony"})
// "Hello Anthony"

trans("items_count", arguments: {"count": "5"})
// "You have 5 items"

Aggiornare la Lingua

Cambia la lingua dell'app in fase di esecuzione:

// Using NyLocalization directly
await NyLocalization.instance.setLanguage(
  context,
  language: 'es'  // Must match your JSON filename (es.json)
);

Se il tuo widget estende NyPage, usa l'helper changeLanguage:

class _SettingsPageState extends NyPage<SettingsPage> {

  @override
  Widget view(BuildContext context) {
    return ListView(
      children: [
        ListTile(
          title: Text("English"),
          onTap: () => changeLanguage('en'),
        ),
        ListTile(
          title: Text("Español"),
          onTap: () => changeLanguage('es'),
        ),
      ],
    );
  }
}

Impostare una Lingua Predefinita

Imposta la lingua predefinita nel tuo file .env:

DEFAULT_LOCALE="en"

Oppure usa la lingua del dispositivo impostando:

LOCALE_TYPE="device"

Dopo aver modificato .env, rigenera la configurazione dell'ambiente:

metro make:env --force

Lingue Supportate

Definisci quali lingue supporta la tua app in LocalizationConfig:

static const List<Locale> supportedLocales = [
  Locale('en'),
  Locale('es'),
  Locale('fr'),
  Locale('de'),
  Locale('ar'),
];

Questa lista viene utilizzata da MaterialApp.supportedLocales di Flutter.

Lingua di Fallback

Quando una chiave di traduzione non viene trovata nella lingua attiva, Nylo Website ricorre alla lingua specificata:

static const String fallbackLanguageCode = 'en';

Questo assicura che la tua app non mostri mai chiavi grezze se una traduzione manca.

Supporto RTL

Nylo Website v7 include il supporto integrato per le lingue da destra a sinistra (RTL):

static const List<String> rtlLanguages = ['ar', 'he', 'fa', 'ur'];

// Check if current language is RTL
if (LocalizationConfig.isRtl(currentLanguageCode)) {
  // Handle RTL layout
}

Debug Chiavi Mancanti

Abilita gli avvisi per le chiavi di traduzione mancanti durante lo sviluppo:

Nel tuo file .env:

DEBUG_TRANSLATIONS="true"

Questo registra avvisi quando .tr() non riesce a trovare una chiave, aiutandoti a individuare stringhe non tradotte.

API NyLocalization

NyLocalization è un singleton che gestisce tutta la localizzazione. Oltre al metodo base translate(), fornisce diversi metodi aggiuntivi:

Verificare se una Traduzione Esiste

bool exists = NyLocalization.instance.hasTranslation('welcome');
// true if the key exists in the current language file

// Also works with nested keys
bool nestedExists = NyLocalization.instance.hasTranslation('navigation.home');

Ottenere Tutte le Chiavi di Traduzione

Utile per il debug per vedere quali chiavi sono caricate:

List<String> keys = NyLocalization.instance.getAllKeys();
// ['welcome', 'settings', 'navigation', ...]

Cambiare Lingua Senza Riavvio

Se vuoi cambiare la lingua silenziosamente (senza riavviare l'app):

await NyLocalization.instance.setLocale(locale: Locale('fr'));

Questo carica il nuovo file di lingua ma non riavvia l'app. Utile quando vuoi gestire gli aggiornamenti dell'interfaccia manualmente.

Verificare la Direzione RTL

bool isRtl = NyLocalization.instance.isDirectionRTL(context);

Accedere alla Lingua Corrente

// Get the current language code
String code = NyLocalization.instance.languageCode;  // e.g., 'en'

// Get the current Locale object
Locale currentLocale = NyLocalization.instance.locale;

// Get Flutter localization delegates (used in MaterialApp)
var delegates = NyLocalization.instance.delegates;

Riferimento Completo dell'API

NyLocaleHelper

NyLocaleHelper è una classe utility statica per le operazioni sulle lingue. Fornisce metodi per rilevare la lingua corrente, verificare il supporto RTL e creare oggetti Locale.

// Get the current system locale
Locale locale = NyLocaleHelper.getCurrentLocale(context: context);

// Get language and country codes
String langCode = NyLocaleHelper.getLanguageCode(context: context);  // 'en'
String? countryCode = NyLocaleHelper.getCountryCode(context: context);  // 'US' or null

// Check if current locale matches
bool isEnglish = NyLocaleHelper.matchesLocale(context, 'en');
bool isUsEnglish = NyLocaleHelper.matchesLocale(context, 'en', 'US');

// RTL detection
bool isRtl = NyLocaleHelper.isRtlLanguage('ar');  // true
bool currentIsRtl = NyLocaleHelper.isCurrentLocaleRtl(context: context);

// Get text direction
TextDirection direction = NyLocaleHelper.getTextDirection('ar');  // TextDirection.rtl
TextDirection currentDir = NyLocaleHelper.getCurrentTextDirection(context: context);

// Create a Locale from strings
Locale newLocale = NyLocaleHelper.toLocale('en', 'US');

Riferimento Completo dell'API

La costante rtlLanguages contiene: ar, he, fa, ur, yi, ps, ku, sd, dv.

Cambiare Lingua da un Controller

Se utilizzi controller con le tue pagine, puoi cambiare la lingua da NyController:

class SettingsController extends NyController {

  void switchToSpanish() {
    changeLanguage('es');
  }

  void switchToEnglishNoRestart() {
    changeLanguage('en', restartState: false);
  }
}

Il parametro restartState controlla se l'app si riavvia dopo aver cambiato la lingua. Impostalo su false se vuoi gestire l'aggiornamento dell'interfaccia da solo.