Lokalisasi

Pengantar

Lokalisasi memungkinkan Anda menyediakan aplikasi dalam beberapa bahasa. Nylo Website v7 memudahkan pelokalan teks menggunakan file bahasa JSON.

Berikut contoh singkatnya:

lang/en.json

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

Di widget Anda:

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

Konfigurasi

Lokalisasi dikonfigurasi di lib/config/localization.dart:

final class LocalizationConfig {
  // Kode bahasa default (sesuai dengan file JSON Anda, contoh: 'en' untuk lang/en.json)
  static final String languageCode =
      getEnv('DEFAULT_LOCALE', defaultValue: "en");

  // LocaleType.device - Gunakan pengaturan bahasa perangkat
  // LocaleType.asDefined - Gunakan languageCode di atas
  static final LocaleType localeType =
      getEnv('LOCALE_TYPE', defaultValue: 'asDefined') == 'device'
          ? LocaleType.device
          : LocaleType.asDefined;

  // Direktori yang berisi file JSON bahasa
  static const String assetsDirectory = 'lang/';

  // Daftar locale yang didukung
  static const List<Locale> supportedLocales = [
    Locale('en'),
    Locale('es'),
    // Tambahkan lebih banyak locale sesuai kebutuhan
  ];

  // Fallback ketika key tidak ditemukan di locale aktif
  static const String fallbackLanguageCode = 'en';

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

  // Log peringatan untuk key terjemahan yang hilang
  static final bool debugMissingKeys =
      getEnv('DEBUG_TRANSLATIONS', defaultValue: 'false') == 'true';
}

Menambahkan File Lokal

Tambahkan file JSON bahasa Anda ke direktori lang/:

lang/
├── en.json   # Inggris
├── es.json   # Spanyol
├── fr.json   # Prancis
└── ...

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

Daftarkan di pubspec.yaml

Pastikan file bahasa Anda disertakan di pubspec.yaml Anda:

flutter:
  assets:
    - lang/

Melokalkan Teks

Gunakan extension .tr() atau helper trans() untuk menerjemahkan string:

// Menggunakan extension .tr()
"welcome".tr()

// Menggunakan helper trans()
trans("welcome")

Key Bersarang

Akses key JSON bersarang menggunakan notasi titik:

lang/en.json

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

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

Argumen

Sisipkan nilai dinamis ke dalam terjemahan Anda menggunakan sintaks {{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"

Memperbarui Locale

Ubah bahasa aplikasi saat runtime:

// Menggunakan NyLocalization secara langsung
await NyLocalization.instance.setLanguage(
  context,
  language: 'es'  // Harus sesuai dengan nama file JSON Anda (es.json)
);

Jika widget Anda meng-extend NyPage, gunakan 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'),
        ),
      ],
    );
  }
}

Mengatur Locale Default

Atur bahasa default di file .env Anda:

DEFAULT_LOCALE="en"

Atau gunakan locale perangkat dengan mengatur:

LOCALE_TYPE="device"

Setelah mengubah .env, regenerate konfigurasi environment Anda:

metro make:env --force

Locale yang Didukung

Tentukan locale mana yang didukung aplikasi Anda di LocalizationConfig:

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

Daftar ini digunakan oleh MaterialApp.supportedLocales Flutter.

Bahasa Fallback

Ketika key terjemahan tidak ditemukan di locale aktif, Nylo Website akan kembali ke bahasa yang ditentukan:

static const String fallbackLanguageCode = 'en';

Ini memastikan aplikasi Anda tidak pernah menampilkan key mentah jika terjemahan hilang.

Dukungan RTL

Nylo Website v7 menyertakan dukungan bawaan untuk bahasa kanan-ke-kiri (RTL):

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

// Periksa apakah bahasa saat ini adalah RTL
if (LocalizationConfig.isRtl(currentLanguageCode)) {
  // Tangani tata letak RTL
}

Debug Key yang Hilang

Aktifkan peringatan untuk key terjemahan yang hilang selama pengembangan:

Di file .env Anda:

DEBUG_TRANSLATIONS="true"

Ini mencatat peringatan saat .tr() tidak dapat menemukan key, membantu Anda menemukan string yang belum diterjemahkan.

API NyLocalization

NyLocalization adalah singleton yang mengelola semua lokalisasi. Selain method dasar translate(), ia menyediakan beberapa method tambahan:

Memeriksa Apakah Terjemahan Ada

bool exists = NyLocalization.instance.hasTranslation('welcome');
// true jika key ada di file bahasa saat ini

// Juga bekerja dengan key bersarang
bool nestedExists = NyLocalization.instance.hasTranslation('navigation.home');

Mendapatkan Semua Key Terjemahan

Berguna untuk debugging untuk melihat key mana yang dimuat:

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

Mengubah Locale Tanpa Restart

Jika Anda ingin mengubah locale secara diam-diam (tanpa me-restart aplikasi):

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

Ini memuat file bahasa baru tetapi tidak me-restart aplikasi. Berguna saat Anda ingin menangani pembaruan UI secara manual.

Memeriksa Arah RTL

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

Mengakses Locale Saat Ini

// Mendapatkan kode bahasa saat ini
String code = NyLocalization.instance.languageCode;  // contoh: 'en'

// Mendapatkan objek Locale saat ini
Locale currentLocale = NyLocalization.instance.locale;

// Mendapatkan delegate lokalisasi Flutter (digunakan di MaterialApp)
var delegates = NyLocalization.instance.delegates;

Referensi API Lengkap

NyLocaleHelper

NyLocaleHelper adalah kelas utilitas statis untuk operasi locale. Ia menyediakan method untuk mendeteksi locale saat ini, memeriksa dukungan RTL, dan membuat objek Locale.

// Mendapatkan locale sistem saat ini
Locale locale = NyLocaleHelper.getCurrentLocale(context: context);

// Mendapatkan kode bahasa dan negara
String langCode = NyLocaleHelper.getLanguageCode(context: context);  // 'en'
String? countryCode = NyLocaleHelper.getCountryCode(context: context);  // 'US' atau null

// Memeriksa apakah locale saat ini cocok
bool isEnglish = NyLocaleHelper.matchesLocale(context, 'en');
bool isUsEnglish = NyLocaleHelper.matchesLocale(context, 'en', 'US');

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

// Mendapatkan arah teks
TextDirection direction = NyLocaleHelper.getTextDirection('ar');  // TextDirection.rtl
TextDirection currentDir = NyLocaleHelper.getCurrentTextDirection(context: context);

// Membuat Locale dari string
Locale newLocale = NyLocaleHelper.toLocale('en', 'US');

Referensi API Lengkap

Konstanta rtlLanguages berisi: ar, he, fa, ur, yi, ps, ku, sd, dv.

Mengubah Bahasa dari Controller

Jika Anda menggunakan controller dengan halaman Anda, Anda dapat mengubah bahasa dari NyController:

class SettingsController extends NyController {

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

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

Parameter restartState mengontrol apakah aplikasi akan restart setelah mengubah bahasa. Atur ke false jika Anda ingin menangani pembaruan UI sendiri.