Yerelleştirme

Giriş

Yerelleştirme, uygulamanızı birden fazla dilde sunmanıza olanak tanır. Nylo Website v7, JSON dil dosyaları kullanarak metni yerelleştirmeyi kolaylaştırır.

İşte hızlı bir örnek:

lang/en.json

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

Widget'ınızda:

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

Yapılandırma

Yerelleştirme lib/config/localization.dart dosyasında yapılandırılır:

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

Yerelleştirilmiş Dosyalar Ekleme

Dil JSON dosyalarınızı lang/ dizinine ekleyin:

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"
  }
}

pubspec.yaml'da Kaydetme

Dil dosyalarınızın pubspec.yaml dosyanızda dahil edildiğinden emin olun:

flutter:
  assets:
    - lang/

Metni Yerelleştirme

Dizeleri çevirmek için .tr() uzantısını veya trans() yardımcısını kullanın:

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

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

İç İçe Anahtarlar

Nokta gösterimi kullanarak iç içe JSON anahtarlarına erişin:

lang/en.json

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

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

Argümanlar

{{key}} sözdizimini kullanarak çevirilerinize dinamik değerler geçirin:

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"

Yerel Ayarı Güncelleme

Uygulamanın dilini çalışma zamanında değiştirin:

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

Widget'ınız NyPage sınıfını genişletiyorsa, changeLanguage yardımcısını kullanın:

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'),
        ),
      ],
    );
  }
}

Varsayılan Yerel Ayar Belirleme

.env dosyanızda varsayılan dili ayarlayın:

DEFAULT_LOCALE="en"

Veya cihazın yerel ayarını kullanmak için şunu ayarlayın:

LOCALE_TYPE="device"

.env dosyasını değiştirdikten sonra ortam yapılandırmanızı yeniden oluşturun:

metro make:env --force

Desteklenen Yerel Ayarlar

Uygulamanızın hangi yerel ayarları desteklediğini LocalizationConfig içinde tanımlayın:

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

Bu liste, Flutter'ın MaterialApp.supportedLocales tarafından kullanılır.

Yedek Dil

Aktif yerel ayarda bir çeviri anahtarı bulunamadığında, Nylo Website belirtilen dile geri döner:

static const String fallbackLanguageCode = 'en';

Bu, bir çeviri eksik olduğunda uygulamanızın asla ham anahtarları göstermemesini sağlar.

RTL Desteği

Nylo Website v7, sağdan sola (RTL) diller için yerleşik destek içerir:

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

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

Eksik Anahtarları Hata Ayıklama

Geliştirme sırasında eksik çeviri anahtarları için uyarıları etkinleştirin:

.env dosyanızda:

DEBUG_TRANSLATIONS="true"

Bu, .tr() bir anahtar bulamadığında uyarıları günlüğe kaydeder ve çevrilmemiş dizeleri yakalamanıza yardımcı olur.

NyLocalization API

NyLocalization, tüm yerelleştirmeyi yöneten bir singleton'dır. Temel translate() metodunun ötesinde, birkaç ek metot sağlar:

Bir Çevirinin Var Olup Olmadığını Kontrol Etme

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

Tüm Çeviri Anahtarlarını Alma

Hangi anahtarların yüklendiğini görmek için hata ayıklamada kullanışlıdır:

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

Yeniden Başlatmadan Yerel Ayar Değiştirme

Yerel ayarı sessizce değiştirmek istiyorsanız (uygulamayı yeniden başlatmadan):

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

Bu, yeni dil dosyasını yükler ancak uygulamayı yeniden başlatmaz. Arayüz güncellemelerini manuel olarak yönetmek istediğinizde kullanışlıdır.

RTL Yönünü Kontrol Etme

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

Mevcut Yerel Ayara Erişim

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

Tam API Referansı

NyLocaleHelper

NyLocaleHelper, yerel ayar işlemleri için statik bir yardımcı sınıftır. Mevcut yerel ayarı algılama, RTL desteğini kontrol etme ve Locale nesneleri oluşturma metotları sağlar.

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

Tam API Referansı

rtlLanguages sabiti şunları içerir: ar, he, fa, ur, yi, ps, ku, sd, dv.

Controller'dan Dil Değiştirme

Sayfalarınızla controller kullanıyorsanız, NyController'dan dili değiştirebilirsiniz:

class SettingsController extends NyController {

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

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

restartState parametresi, dil değiştirildikten sonra uygulamanın yeniden başlayıp başlamayacağını kontrol eder. Arayüz güncellemesini kendiniz yönetmek istiyorsanız false olarak ayarlayın.