Localisation

Introduction

La localisation vous permet de fournir votre application en plusieurs langues. Nylo Website v7 facilite la localisation du texte en utilisant des fichiers de langue JSON.

Voici un exemple rapide :

lang/en.json

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

Dans votre widget :

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

Configuration

La localisation est configuree dans 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';
}

Ajouter des fichiers localises

Ajoutez vos fichiers JSON de langue dans le repertoire 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"
  }
}

Enregistrer dans pubspec.yaml

Assurez-vous que vos fichiers de langue sont inclus dans votre pubspec.yaml :

flutter:
  assets:
    - lang/

Localiser du texte

Utilisez l'extension .tr() ou le helper trans() pour traduire des chaines :

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

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

Cles imbriquees

Accedez aux cles JSON imbriquees en utilisant la notation par points :

lang/en.json

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

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

Arguments

Passez des valeurs dynamiques dans vos traductions en utilisant la syntaxe {{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"

Mettre a jour la locale

Changez la langue de l'application au moment de l'execution :

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

Si votre widget etend NyPage, utilisez le 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'),
        ),
      ],
    );
  }
}

Definir une locale par defaut

Definissez la langue par defaut dans votre fichier .env :

DEFAULT_LOCALE="en"

Ou utilisez la locale de l'appareil en definissant :

LOCALE_TYPE="device"

Apres avoir modifie .env, regenerez votre configuration d'environnement :

metro make:env --force

Locales prises en charge

Definissez quelles locales votre application prend en charge dans LocalizationConfig :

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

Cette liste est utilisee par MaterialApp.supportedLocales de Flutter.

Langue de secours

Lorsqu'une cle de traduction n'est pas trouvee dans la locale active, Nylo Website se rabat sur la langue specifiee :

static const String fallbackLanguageCode = 'en';

Cela garantit que votre application n'affiche jamais de cles brutes si une traduction est manquante.

Support RTL

Nylo Website v7 inclut un support integre pour les langues de droite a gauche (RTL) :

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

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

Debugger les cles manquantes

Activez les avertissements pour les cles de traduction manquantes pendant le developpement :

Dans votre fichier .env :

DEBUG_TRANSLATIONS="true"

Cela journalise les avertissements lorsque .tr() ne trouve pas une cle, vous aidant a reperer les chaines non traduites.

API NyLocalization

NyLocalization est un singleton qui gere toute la localisation. Au-dela de la methode de base translate(), il fournit plusieurs methodes supplementaires :

Verifier si une traduction existe

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');

Obtenir toutes les cles de traduction

Utile pour le debogage pour voir quelles cles sont chargees :

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

Changer la locale sans redemarrage

Si vous souhaitez changer la locale silencieusement (sans redemarrer l'application) :

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

Cela charge le nouveau fichier de langue mais ne redemarre pas l'application. Utile lorsque vous souhaitez gerer les mises a jour de l'interface manuellement.

Verifier la direction RTL

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

Acceder a la locale actuelle

// 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;

Reference API complete

NyLocaleHelper

NyLocaleHelper est une classe utilitaire statique pour les operations de locale. Elle fournit des methodes pour detecter la locale actuelle, verifier le support RTL et creer des objets 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');

Reference API complete

La constante rtlLanguages contient : ar, he, fa, ur, yi, ps, ku, sd, dv.

Changer la langue depuis un controleur

Si vous utilisez des controleurs avec vos pages, vous pouvez changer la langue depuis NyController :

class SettingsController extends NyController {

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

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

Le parametre restartState controle si l'application redemarre apres le changement de langue. Definissez-le a false si vous souhaitez gerer la mise a jour de l'interface vous-meme.