Internasionalisasi (i18n)

Halaman ini mendokumentasikan cara situs dokumentasi Apothem menangani banyak bahasa: kohor lokal yang dideklarasikannya, mekanisme hreflang yang dipancarkannya, render kanan-ke-kirinya, dan cara halaman setiap bahasa dihubungkan ke perutean.

Ringkasan keputusanCopy Anchor Link

• Platform: Next.js App Router + Fumadocs. Situs dibangun dari site/. Kohor lokal dideklarasikan di site/lib/i18n.ts, dan mekanisme tautan bahasa alternatif berada di site/lib/hreflang.ts.
• Kohor lokal: dua belas bahasa. Modern Dev Cohort yang terdiri atas dua belas lokal adalah sumber kebenaran kanonik, dengan bahasa Inggris sebagai lokal sumber dan masing-masing dari sebelas target disemai secara mesin dari kumpulan halaman bahasa Inggris; tinjauan manusia per lokal sedang berlangsung, dan fallbackLanguage: 'en' mencakup halaman mana pun yang belum ditulis oleh sebuah lokal.
• Perutean per lokal: diaktifkan di seluruh kohor. Setiap lokal dihubungkan ke perutean dan dapat dijangkau pada awalan URL-nya sendiri (/es/, /zh-cn/, …); bahasa Inggris dilayani di akar situs.
• Mekanisme hreflang: aktif. Setiap halaman memancarkan himpunan <link rel="alternate"> yang mencakup setiap lokal ditambah fallback x-default, sehingga mesin pencari melihat klaster bahasa alternatif yang lengkap. Tautan-tautan itu di-resolve per berkas dari sistem berkas, sehingga sebuah halaman diiklankan dalam suatu lokal hanya ketika lokal tersebut memilikinya.
• Render kanan-ke-kiri: aktif. Lembar gaya bersama menggunakan properti CSS logis di seluruhnya, sehingga halaman bahasa Arab dirender dengan benar di bawah dir="rtl".
• Tinjauan terjemahan: dilacak per halaman. Halaman lokal hasil mesin disajikan dan membawa machineTranslated: true di frontmatter-nya sampai seorang manusia meninjaunya; flag itu adalah metadata pelacakan tinjauan dan halaman tidak menampilkannya. Bahasa Inggris menjadi cadangan untuk halaman apa pun yang tidak dimiliki suatu lokal. Tertinjaunya 80% halaman suatu lokal adalah target tinjauan, bukan gerbang untuk penerbitan.
• Kesegaran terjemahan: dilacak per halaman. Setiap halaman lokal mencatat teks bahasa Inggris yang menjadi sumber terjemahannya. Ketika halaman bahasa Inggris kemudian berubah, halaman terjemahan menampilkan catatan satu baris yang menautkan ke halaman bahasa Inggris, yang tetap otoritatif.

Kohor lokalCopy Anchor Link

Modern Dev Cohort mendeklarasikan dua belas lokal. Bahasa Inggris dilayani di akar situs; masing-masing dari sebelas target disemai secara mesin dari kumpulan halaman bahasa Inggris pada awalan URL-nya sendiri, dengan fallbackLanguage: 'en' yang mencakup halaman mana pun yang belum ditulis.

Kohor ini adalah satu-satunya sumber kebenaran; perubahan terhadapnya melalui keputusan yang disengaja, tidak pernah melalui suntingan diam-diam.

Cara kerja hreflangCopy Anchor Link

site/lib/hreflang.ts membangun peta alternates.languages yang dirender Next.js ke dalam <head> setiap halaman. Konstruksinya mematuhi satu aturan: tautan bahasa alternatif sebuah lokal dipancarkan hanya ketika lokal tersebut telah menulis halaman itu, yang di-resolve per berkas dari sistem berkas (site/lib/translated-pages.ts). Karena itu, halaman yang sepenuhnya diterjemahkan memancarkan klaster lengkap:

<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="es" href="https://apothem.ahmedgad.com/es/..." />
<link rel="alternate" hreflang="ar" href="https://apothem.ahmedgad.com/ar/..." dir="rtl" />
<!-- … one per cohort locale … -->
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />

Tautan canonical halaman selalu merupakan URL-nya sendiri — tautan itu tidak pernah mengarah lintas lokal.

Render kanan-ke-kiriCopy Anchor Link

Bahasa Arab adalah lokal kanan-ke-kiri dalam kohor ini, dan situs merendernya dengan benar:

• Hanya properti CSS logis. Lembar gaya dan komponen bersama menggunakan properti logis (margin-inline-start, padding-inline-end, text-align: start, inset-inline-start) alih-alih properti fisik (margin-left, text-align: left). Properti logis berbalik secara otomatis di bawah dir="rtl", sehingga lembar gaya yang sama melayani kedua arah dengan benar.
• Atribut arah. Halaman bahasa Arab menetapkan dir="rtl" pada elemen <html> bersama lang="ar".
• Konten dwiarah. String dengan arah campuran — misalnya sebuah command bahasa Inggris di dalam paragraf bahasa Arab — dibungkus dalam <bdi> agar rangkaian kiri-ke-kanan yang tersemat dirender dengan benar di dalam alur kanan-ke-kiri.

Menambah atau memperbarui lokalCopy Anchor Link

Kohor dan perutean digerakkan oleh site/lib/i18n.ts:

1. Tulis halaman di bawah content/docs/<locale>/ dengan mencerminkan sumber bahasa Inggris.
2. Catat teks bahasa Inggris yang diterjemahkannya: dari site/, jalankan node scripts/translation-sources.mjs --stamp <locale>/<path>.mdx, yang menulis hash halaman bahasa Inggris ke dalam frontmatter sourceHash halaman lokal.
3. Pastikan lokal tersebut tercantum dalam ROUTED_LOCALES (kedua belas lokal kohor dirutekan saat ini).
4. Tautan hreflang dan rute-rutenya di-resolve secara otomatis dari sistem berkas.

Terjemahan usangCopy Anchor Link

sourceHash sebuah halaman lokal adalah hash dari halaman bahasa Inggris yang menjadi sumber terjemahannya, yang mencakup frontmatter dan prosa bahasa Inggris tetapi tidak mencakup tabel hasil generator yang ditulis ulang oleh generator referensi dalam setiap bahasa sekaligus. Saat build, situs menghitung hash halaman bahasa Inggris saat ini; ketika keduanya berbeda, halaman terjemahan menampilkan catatan bahwa halaman bahasa Inggris telah berubah sejak terjemahan dibuat, beserta tautan ke halaman tersebut. Jalankan node scripts/translation-sources.mjs dari site/ untuk mencantumkan halaman usang per lokal, lalu perbarui setiap terjemahan dan beri cap seperti pada langkah 2 di atas. Halaman yang sama sekali belum diterjemahkan oleh sebuah lokal dilayani dari sumber bahasa Inggris, dengan tanda sebagai teks bahasa Inggris.

Bahasa Inggris tetap menjadi sumber kebenaran; setiap halaman lokal mencerminkan struktur, tautan, dan contoh kode padanannya dalam bahasa Inggris secara verbatim.