Pendahuluan

Ambil bahasa yang dikonfigurasi dalam proyek Anda untuk mendukung konten multi-bahasa dan deteksi lokal.

Informasi lebih lanjut tentang antarmuka pengguna modul ini https://doc.oneentry.cloud/docs/category/languages

---

🎯 Apa yang dilakukan modul ini?

Modul Locales memungkinkan Anda untuk mengambil bahasa aktif yang dikonfigurasi dalam proyek OneEntry Anda - sehingga Anda dapat membangun aplikasi internasional yang menyajikan konten dalam berbagai bahasa.

Alih-alih mengkodekan bahasa secara statis dalam aplikasi Anda, Anda mengambil daftar bahasa aktif dari OneEntry secara dinamis, memungkinkan konten Anda beradaptasi dengan lokal yang telah Anda aktifkan (Inggris, Rusia, Arab, Spanyol, dll.). Bahasa dikonfigurasi di panel admin OneEntry; SDK bersifat hanya-baca dan hanya mengambil mereka.

🚀 Memulai dengan Cepat

Inisialisasi modul dari defineOneEntry:

const { Locales } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Ambil lokal aktif dan baca bidangnya:

// Returns only active locales (isActive: true).
const locales = await Locales.getLocales();

console.log(`${locales.length} active languages`);

locales.forEach((locale) => {
  console.log(locale.code, locale.name, locale.shortCode);
});

✨ Konsep Kunci

Apa itu Locale?

Locale adalah kombinasi bahasa dan wilayah yang menentukan bagaimana konten ditampilkan:

• Kode Bahasa - kode bahasa ISO 639-1 (misalnya, en, ru, ar)
• Kode Wilayah - kode negara ISO 3166-1 (misalnya, US, GB, RU)
• Pengenal Locale - format gabungan: language_REGION (misalnya, en_US, ru_RU, ar_SA)

Contoh:

Kode Locale	Bahasa	Wilayah	Deskripsi
en_US	Inggris	Amerika Serikat	Bahasa Inggris Amerika
en_GB	Inggris	Britania Raya	Bahasa Inggris Britania
ru_RU	Rusia	Rusia	Bahasa Rusia
es_ES	Spanyol	Spanyol	Bahasa Spanyol Eropa
es_MX	Spanyol	Meksiko	Bahasa Spanyol Meksiko
ar_SA	Arab	Arab Saudi	Arab (Arab Saudi)
fr_FR	Prancis	Prancis	Prancis
de_DE	Jerman	Jerman	Jerman

Struktur Locale

Setiap locale yang dikembalikan oleh getLocales() (ILocalEntity) memiliki:

{
  id: 146,                      // unique ID
  shortCode: 'en',              // short code
  code: 'en_US',                // full code
  name: 'English (USA)',        // name
  nativeName: 'English (USA)',  // native name
  isActive: true,               // is active (always true here)
  image: null,                  // image
  position: 1,                  // position
}

Kode Locale vs. Kode Pendek

Setiap locale memiliki dua format kode:

Bidang	Format	Contoh	Digunakan Untuk
code	language_REGION	en_US, ru_RU	Identifikasi locale lengkap
shortCode	language	en, ru	Identifikasi hanya bahasa

---

📋 Apa yang Perlu Anda Ketahui

Locales dikonfigurasi di panel admin (hanya-baca)

Anda tidak dapat membuat, memperbarui, atau menghapus locales melalui SDK - mereka dikonfigurasi di panel admin OneEntry:

OneEntry Admin Panel → Settings → Languages → Add Language → Select Locale

SDK hanya untuk mengambil informasi locale.

SDK hanya mengembalikan locales aktif

getLocales() hanya mengembalikan objek lokal bahasa aktif (isActive: true). Locales yang tidak aktif yang dikonfigurasi di panel admin tidak dikembalikan, jadi tidak perlu menyaringnya di klien. Setiap locale yang dikembalikan tetap membawa flag isActive (selalu true di sini), bersama dengan code, shortCode, name, nativeName, image, dan position.

Tidak ada bidang default-locale dalam respons — pilih dan simpan bahasa cadangan di aplikasi Anda sendiri.

---

📊 Tabel Referensi Cepat

Metode	Deskripsi	Kasus Penggunaan
getLocales()	Ambil semua locales aktif	Ambil bahasa yang tersedia

---

❓ Pertanyaan Umum (FAQ)

Bagaimana cara menambahkan bahasa baru ke proyek saya?

Anda tidak dapat menambahkan locales melalui SDK. Locales dikonfigurasi di panel admin OneEntry.

---

Apakah getLocales() mengembalikan bahasa yang tidak aktif?

Tidak. SDK hanya mengembalikan locales aktif (isActive: true). Bahasa yang dinonaktifkan di panel admin tidak termasuk dalam respons.

---

Bisakah saya menyimpan cache locales?

Ya. Locales jarang berubah, jadi menyimpan hasilnya dalam cache disarankan untuk kinerja.

---

Bagaimana cara menangani terjemahan yang hilang?

Pilih bahasa cadangan di aplikasi Anda dan gunakan sebagai cadangan ketika konten hilang untuk locale yang diminta — getLocales() tidak menyertakan bidang default-locale.

---

🎓 Praktik Terbaik

• Bergantung pada daftar aktif - SDK sudah mengembalikan hanya locales yang diaktifkan, jadi tidak perlu penyaringan di sisi klien.
• Simpan cache locales - Mereka jarang berubah; simpan hasilnya dalam cache untuk kinerja.
• Pilih bahasa cadangan Anda sendiri - Tidak ada bidang default-locale; tangani terjemahan yang hilang di aplikasi Anda.
• Cocokkan code vs shortCode - Gunakan code (en_US) untuk identifikasi lengkap dan shortCode (en) untuk logika hanya bahasa.

---

🔗 Dokumentasi Terkait

• Modul Halaman - Ambil konten halaman yang dilokalisasi
• Modul Produk - Kelola produk multi-bahasa
• Modul GeneralTypes - Klasifikasi jenis entitas
• Modul Admins - Pengguna admin yang mengelola locales

---