@intlayer/docs 9.4.2 → 9.4.3

package/blog/id/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Memformat Tanggal dan Angka Berdasarkan Bahasa dengan Intl"
+description: Anda kemungkinan besar tidak memerlukan pustaka pemformatan pihak ketiga. Cara Intl menangani tanggal, angka, mata uang, dan daftar per locale, biaya caching, dan bug zona waktu di produksi.
+keywords:
+  - format tanggal berdasarkan bahasa
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - format mata uang locale
+  - format waktu relatif
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Memformat Tanggal dan Angka Berdasarkan Bahasa dengan Intl
+
+Menerjemahkan teks hanyalah separuh bagian yang terlihat dari internasionalisasi (i18n). Separuh lainnya yang rutin memicu laporan bug adalah pemformatan: pengguna di Jerman melihat `1,234.56` alih-alih `1.234,56`, pengguna di Jepang melihat `08/02/2026` dan mengiranya bulan Agustus, atau tanggal yang dirender berbeda di server dan browser sehingga menyebabkan kerusakan hidrasi (hydration mismatch) di React.
+
+Semua itu tidak memerlukan pustaka eksternal. API `Intl` bawaan sudah tersedia di setiap runtime modern.
+
+## Daftar Isi
+
+<TOC/>
+
+## Mulailah dengan menghapus fungsi pembantu tanggal buatan sendiri
+
+Hampir setiap basis kode memiliki fungsi `formatDate` yang ditulis sebelum tim memikirkan dukungan multi-bahasa. Fungsi ini biasanya mengunci urutan tertentu, pemisah tertentu, dan nama-nama bulan dalam bahasa Inggris.
+
+```ts
+// Kode yang perlu Anda hapus:
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` menggantikannya sepenuhnya dan bekerja akurat untuk setiap locale:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+Hal yang sama berlaku untuk angka. Memanggil `toFixed(2)` menghasilkan `1234.56` di mana saja, yang salah di sebagian besar negara Eropa.
+
+## Apa Saja yang Dicakup oleh `Intl`
+
+| API                       | Kegunaan                                                  |
+| :------------------------ | :-------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | Tanggal dan waktu dengan preset `dateStyle` / `timeStyle` |
+| `Intl.NumberFormat`       | Desimal, mata uang, persentase, satuan, notasi ringkas    |
+| `Intl.RelativeTimeFormat` | "3 hari yang lalu", "dalam 2 jam"                         |
+| `Intl.ListFormat`         | "a, b, dan c" versus variasi bahasa lainnya               |
+| `Intl.PluralRules`        | Menentukan kategori bentuk jamak untuk nilai numerik      |
+| `Intl.Collator`           | Pengurutan string sesuai kaidah alfabetis bahasa setempat |
+
+`Intl.Collator` adalah alat yang paling sering dilupakan. Menjalankan `array.sort()` standar pada string menggunakan urutan code point Unicode, sehingga karakter beraksen terlempar ke urutan setelah huruf `z` dan huruf khusus seperti `ö` berada di posisi yang keliru. Jika Anda mengurutkan daftar yang dilihat pengguna, selalu gunakan collator.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("id").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Utamakan preset daripada opsi yang dirangkai manual
+
+`dateStyle` dan `timeStyle` membiarkan locale menentukan urutan logis dan pemisah yang tepat secara otomatis. Menentukan `year`, `month`, dan `day` secara individual memberi Anda kontrol yang sebenarnya tidak perlu, karena urutan yang tepat bervariasi menurut wilayah dan Anda berisiko menimpa standar CLDR dengan asumsi pribadi.
+
+```ts
+// Locale menentukan struktur yang benar:
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// Anda memaksakan struktur sendiri, dan salah di wilayah lain:
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Gunakan komponen eksplisit hanya jika desain tampilan mutlak membutuhkan lebar tetap, seperti pada kolom tabel yang sempit.
+
+## Membangun objek pemformat (formatter) itu mahal
+
+Ini adalah detail performa yang krusial. Membangun sebuah `Intl.NumberFormat` memerlukan pemuatan data locale yang cukup besar ke memori, dan langkah ini jauh lebih berat daripada eksekusi `.format()` berikutnya. Menjalankannya di dalam perulangan render pada seribu baris data akan menimbulkan penurunan performa yang nyata.
+
+```ts
+// Membuat ulang formatter pada setiap baris (lambat):
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Buat sekali, gunakan berulang kali (cepat):
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` dan `toLocaleString()` menyembunyikan masalah yang sama: setiap pemanggilan membuat instansiasi formatter baru. Tidak masalah untuk satu nilai tunggal, tetapi sangat buruk untuk daftar data.
+
+Simpan di cache berdasarkan kombinasi locale dan opsi:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## Bug zona waktu yang hanya muncul di produksi
+
+Masalah ini kerap menghabiskan waktu berjam-jam. Server merender tanggal saat SSR, browser melakukan hidrasi di sisi klien, dan React melempar error hydration mismatch karena kedua lingkungan menghasilkan teks yang berbeda.
+
+Penyebabnya: `Intl.DateTimeFormat` menggunakan zona waktu sistem operasi lokal jika Anda tidak menentukannya secara eksplisit. Server produksi berjalan di UTC, sedangkan komputer lokal pengembang menggunakan zona waktu lain. Akibatnya bug tidak terlihat di lokal dan hanya meledak di produksi.
+
+```ts
+// Server di UTC dan browser di UTC+7 menghasilkan teks berbeda. Gagal hidrasi:
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Keduanya cocok sempurna tanpa celah:
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Tiga pendekatan yang dapat diterapkan:
+
+- **Kunci zona waktu** di server dan teruskan secara eksplisit. Stabil dan deterministik, tetapi semua orang melihat waktu UTC.
+- **Render di sisi klien saja**, dengan placeholder netral saat proses di server. Akurat bagi pengguna, meski ada sedikit kedipan visual.
+- **Simpan zona waktu pengguna** dan teruskan ke server maupun klien. Pengalaman terbaik dengan sedikit pekerjaan integrasi tambahan.
+
+Pendekatan mana pun yang Anda pilih, selalu tentukan `timeZone` secara eksplisit untuk tanggal apa pun yang dirender di server dan klien. Tanggal tanpa zona waktu yang jelas adalah tanggal dengan dua nilai yang berbeda.
+
+## Mata uang memerlukan kode mata uang, bukan locale
+
+Locale dan mata uang adalah dua entitas independen. `fr-FR` tidak selalu berarti euro: pengguna di Prancis bisa saja sedang memeriksa faktur berdenominasi dolar AS.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+Locale mengatur pemisah, pengelompokan digit, dan letak simbol. Mata uang berasal dari data transaksi Anda. Mengasumsikan salah satu dari yang lain akan memicu kekeliruan pembukuan.
+
+Perhatikan pula properti `currencyDisplay`. Pada antarmuka di mana beberapa mata uang berbagi simbol dolar ($), opsi `"code"` menghilangkan keraguan antara dolar AS, Kanada, dan Australia.
+
+## Waktu relatif lebih mudah dipahami daripada waktu absolut
+
+Untuk kejadian terkini, "2 jam yang lalu" jauh lebih nyaman dibaca daripada timestamp kaku, dan `Intl.RelativeTimeFormat` menangani lokalisasinya secara otomatis.
+
+```ts
+new Intl.RelativeTimeFormat("id", { numeric: "auto" }).format(-1, "day");
+// "kemarin"
+```
+
+`numeric: "auto"` menghasilkan kata "kemarin" alih-alih bentuk numerik kaku "1 hari yang lalu".
+
+## Apa yang Ditambahkan oleh Intlayer
+
+Intlayer membungkus API ini ke dalam helper siap pakai dengan caching bawaan, membebaskan Anda dari keharusan mengelola Map secara manual, serta menerapkan bahasa yang aktif secara default tanpa harus mengoper argumen di setiap pemanggilan.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1.234,5"
+currency(1234.5, { currency: "EUR" }); // "€1.234,50"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 jam yang lalu"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 kilometer"
+compact(1200); // "1,2 rb"
+list(["apel", "pisang", "jeruk"]); // "apel, pisang, dan jeruk"
+```
+
+Fungsi `date()` juga mendukung preset (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`). Untuk React dan Vue, tersedia hook dan composable yang langsung mengekstrak bahasa aktif dari konteks.
+
+Ini adalah lapisan cache dan penyediaan default bahasa di atas API bawaan platform. Logika pemformatannya sendiri sepenuhnya bersumber dari `Intl`. Rincian lengkap tersedia di [dokumentasi formatters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/formatters.md).
+
+## Kesalahan umum
+
+- **`toLocaleDateString()` tanpa menentukan locale.** Bergantung pada konfigurasi wadah kontainer di server.
+- **Melakukan pemformatan di dalam loop tanpa cache.** Instansiasi formatters memakan mayoritas waktu komputasi.
+- **Menghilangkan `timeZone` pada tanggal isomorfik.** Menghasilkan error hidrasi yang tidak pernah terjadi di mesin pengembang.
+- **Menyimpulkan mata uang dari locale.** `fr-FR` tidak menjamin transaksi dalam euro.
+- **Menggunakan `sort()` biasa pada string yang tampil di layar.** Selalu gunakan `Intl.Collator`.
+- **Menuliskan nama bulan atau hari secara hardcode.** Seluruhnya sudah tersedia di CLDR untuk setiap bahasa.
+- **Mempertahankan `numeric: "always"` pada waktu relatif.** Menghasilkan "1 hari yang lalu" di bahasa yang memiliki kata seperti kemarin.
+
+## Pelajari lebih lanjut
+
+- [Formatters dan utilitas bahasa: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/formatters.md)
+- [Panduan konfigurasi](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/configuration.md)
+- [Laporan benchmark performa framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/benchmark/index.md)
+- [Adapter kompatibilitas react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/compat/react-intl.md)
+- [Format pesan ICU: bentuk jamak, seleksi, dan skeleton angka](https://github.com/aymericzip/intlayer/blob/main/docs/blog/id/icu_message_format.md)
+- [Cara menguji terjemahan, termasuk cakupan formatter dan bentuk jamak](https://github.com/aymericzip/intlayer/blob/main/docs/blog/id/i18n_testing_strategies.md)
+- [Apa saja yang sebenarnya dicakup oleh internasionalisasi](https://github.com/aymericzip/intlayer/blob/main/docs/blog/id/what_is_internationalization.md)

package/blog/id/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Cara Menemukan Terjemahan yang Hilang Sebelum Pengguna Anda Menemukannya"
+description: Terjemahan yang hilang gagal secara diam-diam. Mengapa fallback menyembunyikannya, empat lapisan deteksi yang benar-benar berfungsi, dan cara menggagalkan build pada kunci yang belum diterjemahkan.
+keywords:
+  - temukan terjemahan yang hilang
+  - kunci terjemahan hilang
+  - audit i18n
+  - string yang belum diterjemahkan
+  - cakupan terjemahan
+  - lint i18n
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# Cara Menemukan Terjemahan yang Hilang Sebelum Pengguna Anda Menemukannya
+
+Terjemahan yang hilang hampir tidak pernah memicu error atau exception. Bergantung pada konfigurasi Anda, aplikasi akan menampilkan teks bahasa Inggris kepada pengguna di Jepang, atau mencetak `checkout.summary.total` langsung di halaman produksi. Keduanya lolos ke tahap rilis, lolos peninjauan kode, dan justru ditemukan oleh pelanggan alih-alih oleh Anda sendiri.
+
+## Daftar Isi
+
+<TOC/>
+
+## Ini berlaku untuk pustaka (library) apa pun yang Anda gunakan
+
+Tidak ada yang eksklusif untuk satu stack teknologi tertentu di sini. Lapisan deteksi di bawah ini bekerja persis sama pada i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate, atau Lingui, karena semuanya menyelesaikan kunci dan mengalami kegagalan dengan logika yang serupa.
+
+Alat-alatnya juga portabel. Jika pesan Anda berada di katalog JSON saat ini, [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/plugins/sync-json.md) mengarahkan Intlayer ke file-file tersebut, memberi Anda perintah audit, pengisian (fill), dan pengujian tanpa memindahkan konten atau mengubah satu baris impor pun:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // atau "icu" untuk next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Jika Anda ingin API runtime tetap identik, [adapter kompatibilitas](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/compat/index.md) menyediakan alias untuk `useTranslation`, `$t`, dan sejenisnya pada tingkat bundler. Apa pun pilihannya, perlakukan perintah di bawah ini sebagai salah satu implementasi nyata dari konsep tersebut, bukan sebagai keharusan.
+
+## Mengapa terjemahan yang hilang tidak terlihat?
+
+Setiap library i18n menyelesaikan kunci melalui rantai yang sama: mencari locale aktif, beralih ke locale default (fallback), dan jika gagal, mengembalikan kunci itu sendiri sebagai string. Langkah terakhir inilah yang menjadi sumber masalah. Tidak ada error, tidak ada peringatan di produksi, dan tidak ada tes yang gagal, karena tidak ada bagian dalam alur kerja yang menganggap kunci yang hilang sebagai hal abnormal.
+
+Mekanisme fallback justru memperburuk keadaan alih-alih memperbaikinya. Halaman yang secara diam-diam menampilkan bahasa Inggris terlihat sangat normal bagi developer berbahasa Inggris dan bagi semua pengujian otomatis. Bug tersebut hanya terlihat oleh orang yang tidak memahami bahasa tersebut.
+
+Jadi pertanyaannya bukanlah "bagaimana menangani terjemahan yang hilang di runtime". Melainkan "bagaimana membuat terjemahan yang hilang mustahil untuk di-merge".
+
+## Empat lapisan tempat Anda dapat menangkapnya
+
+Setiap lapisan menangkap apa yang dilewatkan oleh lapisan lainnya. Anda membutuhkan lebih dari satu.
+
+| Lapisan       | Menangkap                                       | Melewatkan                                    |
+| :------------ | :---------------------------------------------- | :-------------------------------------------- |
+| Tipe (Types)  | Kunci yang memang tidak ada sama sekali         | Kunci ada tetapi belum diterjemahkan di `ja`  |
+| Linter        | String hardcode yang tidak pernah diterjemahkan | Kunci yang hilang dari katalog                |
+| Audit         | Cakupan bahasa pada setiap kunci yang dibuat    | Teks yang tidak pernah dijadikan translatable |
+| Tes Rendering | Kunci yang terselesaikan tetapi salah render    | Segala hal yang tidak dicakup oleh tes        |
+
+Celah yang paling sering dihadapi tim adalah baris ketiga: mereka tahu kunci mereka valid secara sintaksis, tetapi tidak ada yang memeriksa apakah semua delapan belas bahasa benar-benar memiliki nilai.
+
+## Lapisan 1: jadikan kunci sebagai tipe, bukan sekadar string
+
+`t("checkout.summry.total")` adalah typo yang tetap lolos kompilasi. Jika kunci Anda berupa string biasa, setiap penggantian nama adalah risiko runtime dan setiap penghapusan meninggalkan kunci yatim piatu.
+
+Kunci bertipe mengubah masalah tersebut menjadi kesalahan build. `react-i18next` mendukungnya melalui declaration merging, `next-intl` menyimpulkannya dari bentuk pesan, Lingui menurunkan ID dari teks sumber, dan Intlayer menghasilkan tipe ketat langsung dari file deklarasi konten. Semuanya bekerja; yang membedakan adalah seberapa banyak konfigurasi yang harus Anda siapkan.
+
+Lapisan ini penting namun tidak cukup. Tipe hanya mendeskripsikan struktur katalog default Anda. Tipe tidak menjamin apakah bahasa Korea memiliki nilai untuk kunci tersebut.
+
+## Lapisan 2: lint string yang tidak pernah menjadi kunci
+
+Terjemahan yang tidak dapat Anda temukan sering kali adalah teks yang tidak pernah dieksternalisasi. Label yang di-hardcode dalam komponen tidak terlihat oleh audit berbasis katalog mana pun, karena dari sudut pandang peralatan tersebut, string itu tidak pernah ada.
+
+Plugin ESLint dari Intlayer mengatasi hal ini dengan `no-raw-text`, ditambah `no-unused-content` untuk kasus sebaliknya: konten dideklarasikan tetapi tidak lagi dibaca oleh apa pun.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` mencegah katalog membengkak selamanya. Kunci mati memang tidak merusak kode, tetapi membuat tagihan vendor penerjemah menjadi lebih besar dari yang seharusnya. Daftar aturan lengkap ada di [dokumentasi plugin ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/eslint.md).
+
+## Lapisan 3: audit cakupan bahasa (locale coverage)
+
+Inilah lapisan yang menjawab pertanyaan inti. Intlayer menyediakannya sebagai perintah CLI:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+Perintah ini membaca locale yang Anda konfigurasikan dan kamus yang dideklarasikan, lalu melaporkan kunci mana yang kehilangan bahasa apa, dan di file mana letaknya.
+
+Satu detail penting sebelum Anda memasukkannya ke pipeline: **CLI mencetak laporan tetapi keluar dengan status nol (sukses).** Jika Anda memasukkannya dengan harapan menggagalkan build, Anda akan mendapatkan build hijau dengan teks laporan panjang yang tidak dibaca siapa pun. Untuk memblokir proses, gunakan API programatik yang dibahas di bawah.
+
+## Lapisan 4: uji dengan assertion di test suite
+
+`listMissingTranslations()` memberikan hasil audit yang sama dalam bentuk data terstruktur, sangat pas untuk kebutuhan build gate.
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("tidak memiliki locale wajib yang hilang", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Tiga field dikembalikan dengan fungsi masing-masing:
+
+- `missingTranslations`: per kunci, bahasa apa yang hilang dan dari file mana. Ini yang Anda cetak jika tes gagal.
+- `missingLocales`: gabungan seluruh bahasa yang hilang di semua kunci.
+- `missingRequiredLocales`: dibatasi pada `requiredLocales` dalam konfigurasi Anda (atau semua bahasa jika tidak disetel).
+
+## `requiredLocales` adalah pengaturan yang membuat gate dapat bertahan
+
+Mendukung delapan belas bahasa tidak berarti semua delapan belas harus 100% lengkap agar Anda dapat melakukan deploy. Sebagian besar tim membagi tingkatan: tingkatan penting yang menahan rilis, dan tingkatan pelengkap yang dikerjakan berkala.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Tanpa `requiredLocales`, setiap bahasa yang terdaftar otomatis menjadi wajib dan build Anda akan terus merah hingga bahasa terakhir selesai. Hal ini biasanya berujung pada tim yang mematikan pemeriksaan tersebut secara total, yang tentu lebih buruk daripada tidak memilikinya sama sekali.
+
+## Menemukan celah yang sudah terlanjur di produksi
+
+Lapisan di atas mencegah masuknya celah baru. Untuk aplikasi yang sudah live, dua langkah ini sangat membantu.
+
+**Pseudolokalisasi.** Jalankan aplikasi dengan locale tiruan di mana setiap string diubah, misalnya `[!!! Ĉĥéçķöũţ !!!]`. Teks apa pun yang masih muncul dalam bahasa Inggris polos dipastikan merupakan teks hardcode. Metode ini menemukan dalam sepuluh menit apa yang secara struktural tidak dapat dilihat oleh audit katalog, karena ia menguji tampilan yang sudah dirender.
+
+**Merayapi (crawl) situs Anda sendiri.** Jika Anda menyajikan URL dengan locale, ambil sampel per bahasa dan lakukan pencarian teks HTML untuk string bahasa default Anda. Halaman di `/ja/` yang memuat frasa "Add to cart" menandakan adanya terjemahan yang hilang atau fallback yang tidak Anda sadari.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Mengisi kekosongan terjemahan
+
+Begitu Anda tahu apa yang kurang, `intlayer fill` mengisi entri kosong tersebut, dan opsi `autoFill` dapat menghasilkan file per-locale saat konten dideklarasikan. Lihat [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/autoFill.md).
+
+Perlu dipahami dengan jelas: terjemahan yang diisi oleh mesin mengubah celah _yang terlihat_ menjadi celah _yang tidak terlihat_. Kunci sekarang memiliki isi, sehingga audit berubah menjadi hijau, tetapi belum ada manusia yang membaca hasilnya. Gunakan cara ini untuk membuka blokir rilis, lalu serahkan teks penting kepada peninjau manusia untuk hal-hal yang memengaruhi keputusan pelanggan. Ini adalah penopang sementara, bukan jawaban mutlak.
+
+## Kesalahan umum
+
+- **Menganggap fallback sebagai fitur perlindungan.** Ini hanyalah strategi rendering darurat, bukan jaring pengaman. Halaman yang diam-diam berbahasa Inggris adalah bug yang tidak diketahui siapa pun.
+- **Mengandalkan laporan CLI untuk membatalkan CI.** `intlayer content test` keluar dengan kode nol. Gunakan assertion dalam unit test.
+- **Mewajibkan semua bahasa.** Pemeriksaan langsung dimatikan begitu menahan jadwal rilis darurat.
+- **Mengaudit katalog tanpa pernah melihat layar render.** String hardcode tidak mungkin terlihat dalam audit katalog.
+- **Hanya menguji bahasa default.** Bahasa default adalah satu-satunya bahasa yang mustahil hilang.
+- **Mengakhiri alur kerja hanya dengan auto-fill mesin.** Audit hijau dengan teks yang belum pernah diperiksa manusia.
+
+## Pelajari lebih lanjut
+
+- [Menguji konten Anda: audit CLI, API programatik, dan assertion UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/testing.md)
+- [Aturan plugin ESLint, termasuk `no-raw-text` dan `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/eslint.md)
+- [autoFill: menghasilkan file deklarasi per-locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/autoFill.md)
+- [Referensi konfigurasi: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/configuration.md)
+- [Laporan benchmark performa antar-framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/benchmark/index.md)
+- [Adapter kompatibilitas i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/compat/i18next.md)
+- [Apa saja yang sebenarnya dicakup oleh internasionalisasi](https://github.com/aymericzip/intlayer/blob/main/docs/blog/id/what_is_internationalization.md)
+- [i18n per komponen vs i18n terpusat](https://github.com/aymericzip/intlayer/blob/main/docs/blog/id/per-component_vs_centralized_i18n.md)

package/blog/id/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Mengotomatiskan Terjemahan di CI/CD Tanpa Mengirim Teks yang Buruk"
+description: Tiga tempat untuk mengotomatiskan i18n, pre-push, pull request, dan runtime. Cara membatasi build berdasarkan cakupan, mengisi otomatis dengan aman, dan menghindari loop commit CI tanpa akhir.
+keywords:
+  - otomatisasi terjemahan ci
+  - i18n ci cd
+  - github actions terjemahan
+  - husky pre-push
+  - lokalisasi berkelanjutan
+  - pipeline terjemahan
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Mengotomatiskan Terjemahan di CI/CD Tanpa Mengirim Teks yang Buruk
+
+Terjemahan manual tidak dapat bertahan dalam ritme rilis modern. Seseorang menambahkan string pada hari Jumat, proses ekspor baru terjadi pada sprint berikutnya, dan pada saat itu tiga bahasa lainnya sudah tertinggal. Mengotomatiskannya sangat mudah. Mengotomatiskannya tanpa secara diam-diam menerbitkan output mesin tanpa tinjauan kepada pelanggan adalah bagian yang perlu dipikirkan secara matang.
+
+## Daftar Isi
+
+<TOC/>
+
+## Anda tidak perlu bermigrasi untuk mengotomatiskan
+
+Bentuk pipeline di bawah ini tidak bergantung pada library tertentu, begitu pula peralatannya. Jika pesan Anda berupa katalog JSON untuk i18next, next-intl, react-intl, vue-i18n, atau next-translate, [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/plugins/sync-json.md) membaca dan menulis file-file tersebut langsung di tempat:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // atau "icu" untuk next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Aplikasi Anda tetap mengimpor file seperti biasa. Tugas CI berikut ini kemudian mengisi dan memverifikasi katalog yang ada, dan perbedaan (diff) yang dilihat oleh reviewer adalah perubahan pada `locales/fr/checkout.json`, bukan migrasi kode besar-besaran. Terdapat juga [plugin Sync PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/plugins/sync-po.md) untuk alur kerja gettext, dan [adapter kompatibilitas](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/compat/index.md) jika Anda ingin API runtime tetap tidak berubah.
+
+## Pisahkan gerbang pemeriksaan (gate) dari pengisian (fill)
+
+Dua tugas yang berbeda ini sering kali tertukar.
+
+Sebuah **gate** adalah pemeriksaan yang dapat gagal. Ini menyatakan bahwa build ini tidak boleh dirilis karena ada locale wajib yang belum lengkap. Gate tidak menulis file apa pun.
+
+Sebuah **fill** adalah proses mutasi data. Ini menghasilkan terjemahan yang hilang dan melakukan commit. Fill tidak pernah menggagalkan build.
+
+Menjalankan fill saja berarti tidak ada yang pernah diblokir, dan terjemahan mesin yang belum ditinjau akan langsung mengalir ke produksi. Menjalankan gate saja berarti build akan sering merah dan manusia harus turun tangan memperbaikinya setiap saat. Sebagian besar tim menginginkan keduanya dengan pemicu berbeda: fill pada pull request, gate saat merge ke branch rilis.
+
+## Tempat otomasi dapat diterapkan
+
+| Tahap         | Pemicu    | Cocok untuk                               | Biaya                                             |
+| :------------ | :-------- | :---------------------------------------- | :------------------------------------------------ |
+| Hook pre-push | Git lokal | Umpan balik cepat, nol menit CI           | Berjalan di komputer developer dan API key mereka |
+| Pull request  | Job CI    | Review sebelum merge, satu tempat rahasia | Menit CI ditambah panggilan model per PR          |
+| Branch rilis  | Job CI    | Gerbang ketat untuk cakupan terjemahan    | Murah, tidak ada panggilan ke model AI            |
+| Runtime       | CMS       | Perubahan konten tanpa build ulang        | Ketergantungan layanan hosting                    |
+
+## Pre-push: putaran tercepat
+
+Husky menjalankan proses pengisian sebelum kode meninggalkan komputer lokal, sehingga terjemahan tiba dalam push yang sama dengan string yang membutuhkannya.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` membatasi pekerjaan pada konten yang belum di-push, mencegah proses memakan waktu lama pada setiap push. `--mode complete` hanya mengisi apa yang hilang tanpa menulis ulang entri yang sudah memiliki nilai, sehingga terjemahan yang sudah ditinjau manusia tidak akan pernah ditimpa secara diam-diam.
+
+Untuk monorepo, tentukan cakupan per aplikasi:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+Kelemahannya nyata: setiap pengembang membutuhkan API key, dan biayanya dibebankan kepada siapa pun yang melakukan push. Itulah sebabnya sebagian besar tim memindahkan proses ini ke CI saat tim berkembang.
+
+## Pull request: isi di tempat review dilakukan
+
+Pekerjaan yang sama di GitHub Actions, dibatasi pada diff:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+Empat detail di dalamnya sangat krusial:
+
+- **`fetch-depth: 0`** wajib ada agar `--git-diff` dapat bekerja. Kloning dangkal (shallow clone) tidak memiliki basis perbandingan untuk diff, sehingga proses pengisian tidak mencakup apa pun secara diam-diam.
+- **`[skip ci]` dalam pesan commit** mencegah workflow memicu dirinya sendiri tanpa akhir. Tanpa ini, commit memicu eksekusi baru yang kemudian commit lagi, menghabiskan kuota CI dalam semalam.
+- **`concurrency` dengan `cancel-in-progress`** mencegah dua push bersamaan berebut menulis ke file yang sama.
+- **`--git-diff`** membatasi pengisian hanya pada apa yang diubah dalam PR. Jika diabaikan, Anda akan menerjemahkan ulang seluruh katalog pada setiap proses.
+
+Terjemahan akan masuk sebagai commit di branch PR, yang berarti reviewer dapat memeriksanya di diff. Itulah inti dari melakukannya di sini daripada setelah merge.
+
+## Branch rilis: gerbang pemeriksaan (gate)
+
+Gate tidak memerlukan akses model dan harus selesai dengan cepat.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+Didukung oleh tes yang menguji cakupan melalui assertion daripada sekadar laporan teks CLI:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("has no missing required locales", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` mencetak laporan tetapi keluar dengan kode nol, sehingga hanya memberi tahu tanpa memblokir build. Gunakan itu secara lokal; gunakan assertion tes di CI. Rincian lebih lanjut di [menemukan terjemahan yang hilang](https://github.com/aymericzip/intlayer/blob/main/docs/blog/id/detecting_missing_translations.md).
+
+## `requiredLocales` membuat gate dapat bertahan di dunia nyata
+
+Sebuah gerbang yang menuntut lengkapnya semua delapan belas bahasa akan memblokir setiap rilis hingga bahasa yang paling lambat selesai, dan biasanya dinonaktifkan dalam waktu satu bulan.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Deklarasikan bahasa yang Anda layani, dan jadikan wajib hanya bahasa yang benar-benar harus memblokir rilis. Sisanya dapat dilengkapi secara asinkron tanpa menahan jadwal deployment.
+
+## Memisahkan terjemahan sepenuhnya dari repositori
+
+Model lainnya adalah mendeklarasikan satu bahasa utama dalam kode dan mengelola sisanya dari jarak jauh melalui CMS dengan Live Sync. Perubahan konten kemudian tidak memerlukan proses build ulang aplikasi, memisahkan ritme pembaruan teks dari ritme deploy kode.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+Ini cocok untuk tim di mana non-developer mengelola konten. Ini adalah kompromi: Anda mendapatkan otonomi editor namun kehilangan jaminan bahwa git checkout secara mandiri mendeskripsikan secara tepat apa yang dirender aplikasi. Detailnya di [dokumentasi CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_CMS.md).
+
+Harap dicatat bahwa `clientSecret` adalah kredensial sisi server. Kunci ini harus berada di rahasia CI dan variabel lingkungan server Anda, tidak boleh masuk ke bundle klien.
+
+## Batasan nyata yang harus disadari
+
+Semua yang dijelaskan di atas mengotomatiskan _cakupan (coverage)_, bukan _kualitas_. Pengisian mesin mengubah celah yang terlihat menjadi tidak terlihat: audit menjadi hijau karena kunci sekarang memiliki nilai, tetapi belum ada manusia yang membacanya.
+
+Itu dapat diterima untuk alat internal, catatan rilis, atau locale dalam versi beta. Ini tidak dapat diterima untuk penetapan harga, dokumen hukum, pesan kesalahan pembayaran, atau apa pun yang dibaca pelanggan sebelum mengambil keputusan. Arahkan teks penting tersebut melalui peninjauan manusia, dan gunakan `--mode complete` di mana saja agar string yang sudah diperiksa tidak pernah ditimpa.
+
+Beri konteks pada model agar keluarannya konsisten:
+
+```ts
+ai: {
+  applicationContext: "Aplikasi faktur B2B. Gaya bahasa formal. Jangan pernah menerjemahkan nama produk.",
+}
+```
+
+## Kesalahan umum
+
+- **Tidak ada `[skip ci]` pada auto-commit.** Alur kerja memicu dirinya sendiri dalam lingkaran tanpa akhir.
+- **Shallow clone dengan `--git-diff`.** Tidak ada basis diff, tidak ada yang diisi dan tidak ada error yang dilaporkan.
+- **Mengisi seluruh katalog pada setiap proses.** Batasi dengan `--git-diff` atau `--unpushed` untuk mengontrol tagihan.
+- **Menggunakan laporan CLI sebagai gate.** Perintah keluar dengan kode 0 sehingga build tetap lolos.
+- **Mewajibkan semua locale.** Gerbang langsung dinonaktifkan saat pertama kali memblokir rilis penting.
+- **Job pengisian tanpa gerbang verifikasi.** Tidak ada yang pernah gagal, sehingga teks mesin tanpa review langsung tayang di produksi.
+- **Menyimpan API key model di dalam repo.** Kunci harus disimpan di rahasia CI, sama seperti `clientSecret`.
+
+## Pelajari lebih lanjut
+
+- [CI/CD: membuat terjemahan otomatis dengan Husky, GitHub Actions, dan CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/CI_CD.md)
+- [Menguji konten Anda dan membatasi build berdasarkan cakupan](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/testing.md)
+- [autoFill: menghasilkan file deklarasi per-locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/autoFill.md)
+- [Referensi konfigurasi: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/configuration.md)
+- [Laporan benchmark performa antar berbagai framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/benchmark/index.md)
+- [Adapter kompatibilitas i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/compat/i18next.md)
+- [Cara mendeteksi terjemahan yang hilang](https://github.com/aymericzip/intlayer/blob/main/docs/blog/id/detecting_missing_translations.md)
+- [Cara menguji terjemahan tanpa tes yang rapuh](https://github.com/aymericzip/intlayer/blob/main/docs/blog/id/i18n_testing_strategies.md)