Internasionalisasi (i18n)
Starlight menyediakan dukungan bawaan untuk website multibahasa, termasuk pengaturan rute, konten cadangan, dan dukungan bahasa dari kanan ke kiri (RTL) sepenuhnya.
Konfigurasikan i18n
-
Beri tahu Starlight tentang bahasa yang Anda dukung dengan cara menambahkan
locales
dandefaultLocale
ke integrasi Starlight:defaultLocale
Anda akan digunakan untuk konten cadangan dan label UI pengguna, jadi pilih bahasa yang kemungkinan besar akan Anda gunakan untuk menulis konten, atau sudah memiliki konten. -
Buat direktori untuk setiap bahasa di
src/content/docs/
. Sebagai contoh, untuk konfigurasi yang ditunjukkan di atas, buat folder berikut:Directorysrc/
Directorycontent/
Directorydocs/
Directoryar/
- …
Directoryen/
- …
Directoryzh-cn/
- …
-
Sekarang Anda dapat menambahkan file konten dalam direktori bahasa Anda. Gunakan nama file yang sama untuk mengaitkan halaman di seluruh bahasa dan manfaatkan fitur i18n lengkap Starlight, termasuk konten cadangan, pemberitahuan terjemahan, dan lainnya.
Sebagai contoh, buat
ar/index.md
danen/index.md
, masing-masing mewakili beranda untuk bahasa Arab dan Inggris.
Untuk skenario i18n yang lebih canggih, Starlight juga mendukung konfigurasi internasionalisasi menggunakan opsi konfigurasi i18n
Astro.
Gunakan root locale
Anda dapat menggunakan root locale untuk melayani bahasa tanpa awalan i18n dalam path-nya. Sebagai contoh, jika Inggris adalah root locale Anda, path halaman dalam bahasa Inggris akan terlihat sebagai /about
dan bukan /en/about
.
Untuk mengatur root locale, gunakan properi root
dalam konfigurasi locales Anda. Jika root locale juga merupakan bahasa default konten Anda, hapus defaultLocale
atau tetapkan nilainya dengan nilai 'root'
.
Ketika menggunakan locale root
, simpan halaman untuk bahasa tersebut langsung di src/content/docs/
dan tidak di dalam folder khusus untuk bahasa. Sebagai contoh, berikut adalah file halaman beranda untuk bahasa Inggris dan Cina ketika menggunakan konfigurasi di atas:
Directorysrc/
Directorycontent/
Directorydocs/
- index.md
Directoryzh-cn/
- index.md
Website monolingual
Secara default, Starlight adalah website monolingual (Inggris). Untuk membuat website bahasa tunggal dalam bahasa lain, tetapkan bahasa tersebut sebagai root
dalam konfigurasi locales
Anda:
Ini memungkinkan Anda mengganti bahasa default Starlight tanpa mengaktifkan fitur internasionalisasi lainnya untuk website multibahasa, seperti pemilih bahasa.
Konten cadangan
Starlight mengharapkan Anda membuat halaman yang sama untuk semua bahasa yang Anda dukung. Sebagai contoh, jika Anda memiliki file en/about.md
, buatlah about.md
untuk setiap bahasa lain yang Anda dukung. Ini memungkinkan Starlight menyediakan konten cadangan otomatis untuk halaman yang belum diterjemahkan.
Jika terjemahan belum tersedia untuk suatu bahasa, Starlight akan menampilkan konten untuk halaman tersebut dalam bahasa default (di-set melalui defaultLocale
). Sebagai contoh, jika Anda belum membuat versi bahasa Prancis dari halaman Tentang Anda dan bahasa default Anda adalah Inggris, pengunjung ke /fr/about
akan melihat konten berbahasa Inggris dari /en/about
dengan pemberitahuan bahwa halaman ini belum diterjemahkan. Ini membantu Anda menambahkan konten dalam bahasa default Anda dan kemudian secara bertahap menerjemahkannya saat penerjemah Anda memiliki waktu.
Terjemahkan judul website
Secara default, Starlight akan menggunakan judul website yang sama untuk semua bahasa.
Jika Anda perlu menyesuaikan judul untuk setiap bahasa, Anda dapat meneruskan objek ke title
di opsi Starlight:
Terjemahkan UI Starlight
Selain menyimpan file konten yang diterjemahkan, Starlight memungkinkan Anda menerjemahkan string UI default (misalnya, judul “Di halaman ini” dalam daftar isi) sehingga pembaca Anda dapat mengakses website Anda sepenuhnya dalam bahasa yang dipilih.
Arab, Belanda, Bokmål Norwegia, Cheska, Dansk, Galisia, Hindi, Ibrani, Indonesia, Inggris, Italia, Jepang, Jerman, Korea, Persia, Polski, Portugis, Prancis, Rumania, Rusia, Slovak, Spanyol, Swedia, Tionghoa, Tionghoa (Taiwan), Turki, Ukraina, dan Vietnam string UI yang diterjemahkan disediakan secara langsung, dan kami menyambut kontribusi untuk menambahkan lebih banyak bahasa default.
Anda dapat memberikan terjemahan untuk bahasa tambahan yang Anda dukung — atau mengganti label default kami — melalui koleksi data i18n
.
-
Konfigurasikan koleksi data
i18n
disrc/content/config.ts
jika belum dikonfigurasi: -
Buat file JSON di
src/content/i18n/
untuk setiap locale tambahan yang ingin Anda berikan string terjemahan UI-nya. Sebagai contoh, ini akan menambahkan file terjemahan untuk bahasa Arab dan Cina (yang disederhanakan):Directorysrc/
Directorycontent/
Directoryi18n/
- ar.json
- zh-CN.json
-
Tambahkan terjemahan untuk properti yang ingin Anda terjemahkan ke file JSON. Terjemahkan hanya nilai-nilainya, biarkan nama propertinya dalam bahasa Inggris (misalnya,
"search.label": "Buscar"
).Berikut adalah nilai default bahasa Inggris dari string-string yang sudah ada yang diberikan secara bawaan oleh Starlight:
Blok kode Starlight didukung oleh pustaka Expressive Code. Anda dapat mengatur terjemahan untuk string UI-nya dalam file JSON yang sama menggunakan nama properti
expressiveCode
:Modal pencarian Starlight didukung oleh pustaka Pagefind. Anda dapat mengatur terjemahan untuk UI Pagefind di file JSON yang sama menggunakan properti-properti
pagefind
:
Memperluas skema terjemahan
Tambahkan nama properti khusus ke kamus terjemahan website Anda dengan menyetel extend
di opsi i18nSchema()
.
Dalam contoh berikut, nama properti custom.label
opsional yang baru ditambahkan ke nama properti default:
Pelajari selengkapnya tentang skema pengumpulan konten di “Mendefinisikan skema pengumpulan” di dokumen Astro.
Menggunakan terjemahan UI
Anda dapat mengakses string UI bawaan Starlight serta string UI yang ditentukan pengguna, dan yang disediakan plugin melalui API terpadu yang didukung oleh i18next. Ini termasuk dukungan untuk fitur seperti interpolasi dan pluralisasi.
Dalam komponen Astro, API ini tersedia sebagai bagian dari objek Astro
global sebagai Astro.locals.t
:
Anda juga dapat menggunakan API di titik akhir, di mana objek locals
tersedia sebagai bagian dari konteks titik akhir:
Merender string UI
Render string UI menggunakan fungsi locals.t()
.
Ini adalah contoh fungsi t()
i18next, yang mengambil nama properti string UI sebagai argumen pertamanya dan mengembalikan terjemahan yang sesuai untuk bahasa saat ini.
Misalnya, diberikan berkas terjemahan khusus dengan konten berikut:
String UI pertama dapat dirender dengan meneruskan 'link.astro'
ke fungsi t()
:
String UI kedua menggunakan sintaks interpolasi i18next untuk placeholder {{feature}}
.
Nilai untuk feature
harus ditetapkan dalam objek opsi yang diteruskan sebagai argumen kedua ke t()
:
Lihat dokumentasi i18next untuk informasi lebih lanjut tentang cara menggunakan fungsi t()
dengan interpolasi, pemformatan, dan lainnya.
API Tingkat Lanjut
t.all()
Fungsi locals.t.all()
mengembalikan objek berisi semua string UI yang tersedia untuk bahasa saat ini.
t.exists()
Untuk memeriksa apakah nama properti terjemahan tersedia untuk suatu bahasa, gunakan fungsi locals.t.exists()
dengan nama properti terjemahan sebagai argumen pertama.
Berikan argumen kedua opsional jika Anda perlu mengganti bahasa saat ini.
Lihat referensi exists()
dalam dokumentasi i18next untuk informasi lebih lanjut.
t.dir()
Fungsi locals.t.dir()
mengembalikan arah teks bahasa saat ini atau bahasa tertentu.
Lihat referensi dir()
dalam dokumentasi i18next untuk informasi lebih lanjut.
Mengakses bahasa saat ini
Anda dapat menggunakan Astro.currentLocale
untuk membaca bahasa saat ini di komponen .astro
.
Contoh berikut membaca bahasa saat ini dan menggunakannya untuk membuat tautan ke halaman tentang dalam bahasa saat ini: