Bagian i18n di bawah ini siap ditempel ke AGENTS.md: sepuluh aturan singkat yang memerintahkan agen coding untuk mengalirkan setiap teks yang terlihat pengguna lewat fungsi terjemahan, memberi kunci berdasarkan fitur, tidak pernah menyambung fragmen, tidak pernah memalsukan plural dengan ternary, dan tidak pernah menyentuh file bahasa hasil generate. globalize.now adalah infrastruktur lokalisasi berbasis AI, jadi kami banyak membaca i18n buatan agen, dan beberapa kesalahan yang sama menyumbang hampir semuanya. Setiap aturan menjawab salah satunya.

Paruh kedua artikel ini membahas titik di mana file tersebut berhenti bekerja. Dua area kode yang paling sering dipakai developer tidak pernah membacanya, dan tidak ada susunan kata yang bisa memperbaikinya.

Apa isi bagian i18n di AGENTS.md?

Blok ini. Sesuaikan tiga path file dan perintah lint dengan proyekmu, sisanya biarkan.

## Internationalization

- Every user-visible string goes through the translation function. That
  includes JSX text, input hint text, `title`, `aria-label`, `alt`, toast and
  error messages, empty states and the document `<title>`.
- The source locale is `en`. The catalog is `locales/en.json`. Add the key in
  the same change that uses it.
- Keys are namespaced by feature: `checkout.summary.total`, not `total3`.
  Search the catalog for an existing key before creating one.
- Never concatenate translated fragments. Use interpolation:
  `t('cart.items', { count })`, not `t('cart.you_have') + count`.
- Plurals use the library's plural forms (`_one` / `_other` keys, or ICU
  `{count, plural, ...}`). Never `count === 1 ? 'item' : 'items'`.
- Dates, numbers and currency go through `Intl.DateTimeFormat` and
  `Intl.NumberFormat` with the active locale. Never a bare
  `toLocaleString()`, never a currency symbol glued to a number.
- Do not hardcode the locale list, language names or text direction in
  components. Read them from `i18n/config.ts`.
- Do not translate brand names, code identifiers, URLs or environment values.
- Do not edit locale files other than `en`. They are generated. If a
  translation looks wrong, fix the source key or the glossary, not the file.
- Before finishing, run `npm run lint`. The `i18next/no-literal-string`
  rule must pass.

Sepuluh aturan adalah pilihan yang disengaja. Dokumentasi rules Cursor sendiri menyarankan agar aturan difokuskan pada pola yang sering kamu pakai dan agar kamu menggunakan linter, bukan menempelkan panduan gaya. Panduan Claude Code pun serupa: tulis instruksi yang cukup konkret untuk diverifikasi, dan jaga file tetap pendek karena kepatuhan menurun seiring file membesar. Bagian i18n yang berisi empat puluh poin hanya akan dibaca sekilas.

Mengapa sepuluh aturan ini, bukan sekadar “gunakan i18n”?

Karena “gunakan i18n” adalah apa yang sudah diyakini agen sedang dilakukannya saat menulis <Button>Save changes</Button>. Instruksi yang samar akan dianggap terpenuhi menurut pemahaman agen sendiri tentang kepatuhan. Setiap aturan di bawah ini menyebut satu hasil tertentu dan melarangnya.

Literal di atribut. Agen belajar bahwa children JSX perlu diterjemahkan, lalu menulis aria-label="Close" dan alt="Company logo" sebagai string biasa, karena atribut tampak seperti konfigurasi, bukan teks. Menyebut nama atributnya satu per satu menutup celah itu; “terjemahkan semuanya” tidak.

Concatenation. t('greeting') + ' ' + name + '!' tampil baik dalam bahasa Inggris, tetapi tidak bisa diterjemahkan ke bahasa yang menaruh nama di depan atau mengubah bentuknya. Interpolasi memberi penerjemah satu string dengan satu variabel yang bisa dipindahkan.

Plural dengan ternary. count === 1 ? 'item' : 'items' adalah hal yang paling sering kami lihat ditulis agen setelah i18n disiapkan, dan salah untuk setiap bahasa yang punya lebih dari dua bentuk plural. Aturan ini menyebut polanya agar agen bisa mengenalinya. Jika katalogmu memakai ICU, apa itu ICU MessageFormat dan di mana ia bermasalah pada aplikasi buatan AI membahas sintaksnya.

File bahasa hasil generate. Aturan ini ada karena agen cenderung ingin membantu. Diminta memperbaiki typo bahasa Jerman, agen akan membuka locales/de.json dan mengeditnya; perubahan itu bertahan sampai proses terjemahan berikutnya membuat ulang file tersebut dari sumber. Memberi tahu agen bahwa file non-sumber adalah hasil generate, dan ke mana perbaikan yang sebenarnya harus dilakukan, mencegah satu jenis regresi diam-diam.

Mengedit en dalam perubahan yang sama. Tanpa aturan ini, agen menambahkan t('checkout.summary.total') lalu lanjut, dan kunci itu tampil sebagai namanya sendiri sampai ada yang menyadarinya. Entri katalog dan pemakaian pertamanya harus berada dalam satu diff.

Di mana setiap tool benar-benar membaca file ini?

Isi yang sama ditaruh di tempat berbeda tergantung agennya, dan penempatan menentukan apakah aturan selalu ada di konteks atau baru dimuat saat relevan.

AGENTS.md di root repositori adalah lokasi bersama. Formatnya Markdown biasa tanpa field wajib, dikelola oleh Agentic AI Foundation di bawah Linux Foundation, dan dibaca oleh Cursor, Codex, agen coding Copilot, dan banyak lainnya. Spesifikasinya mendukung file bersarang, dengan file yang paling dekat ke file yang diedit lebih diutamakan.

Cursor membaca AGENTS.md secara langsung, termasuk yang bersarang, dan juga punya format bercakupan sendiri. Aturan yang dibatasi ke file UI tidak masuk konteks sampai ada file yang cocok dibuka:

---
description: i18n rules for user-visible strings
globs: src/**/*.tsx, src/**/*.jsx
alwaysApply: false
---
(paste the Internationalization section here)

File harus berakhiran .mdc dan berada di .cursor/rules/; .md biasa di folder itu diabaikan karena tidak punya frontmatter.

GitHub Copilot di VS Code punya tiga opsi. .github/copilot-instructions.md berlaku untuk setiap permintaan chat. File .github/instructions/i18n.instructions.md dengan applyTo: "**/*.tsx,**/*.jsx" di frontmatter hanya berlaku saat file tersebut dibuat atau diubah. Sementara AGENTS.md di root repositori dibaca oleh Local agent saat pengaturan chat.useAgentsMdFile aktif; file AGENTS.md bersarang di subfolder diatur lewat pengaturan eksperimental terpisah, chat.useNestedAgentsMdFiles, yang nonaktif secara default. Perilaku khusus Copilot dibahas di cara menambahkan i18n ke aplikasi yang dibuat dengan GitHub Copilot.

Claude Code membaca CLAUDE.md, dan sejak v2.1.277 juga membaca AGENTS.md di root secara mandiri saat proyek tidak punya CLAUDE.md di atas direktori kerja. Jika kamu menyimpan keduanya, pola yang didokumentasikan adalah impor @AGENTS.md di bagian atas CLAUDE.md agar file hanya dimuat sekali. Untuk membatasi cakupan, .claude/rules/i18n.md dengan daftar paths: di frontmatter hanya dimuat saat Claude membaca file yang cocok. Alur kerja lengkap Claude Code ada di cara melokalisasi aplikasi yang dibuat Claude Code.

Susunan praktis untuk repo yang disentuh beberapa agen: sepuluh aturan di file dengan cakupan khusus untuk agen yang paling sering dipakai timmu, dan penunjuk dua baris di AGENTS.md (“Teks UI: lihat aturan i18n di .cursor/rules/i18n.mdc, dan patuhi”) agar agen tanpa dukungan cakupan tetap menerima instruksinya.

Area kode mana yang tidak pernah membaca AGENTS.md?

Penyelesaian kode inline (inline completion). Hal ini didokumentasikan oleh kedua vendor, dan itulah alasan file aturan tidak bisa menjadi satu-satunya solusi.

FAQ rules Cursor menjawab pertanyaan “Apakah rules memengaruhi Cursor Tab atau fitur AI lainnya?” dengan singkat: tidak. Rules menjadi masukan bagi Agent; Tab, autocomplete yang melengkapi baris yang sedang kamu ketik, tidak melihatnya. Halaman custom instructions VS Code memuat catatan serupa untuk Copilot: instruksi tidak diperhitungkan untuk saran inline saat kamu mengetik di editor.

Jadi area tempat developer mengetik <p>No results found</p> dan menerima ghost text adalah persis area yang tidak pernah dijangkau aturan tersebut. Chat dan mode agen akan menetapkan kunci terjemahan untuk string itu; completion yang menyelesaikan baris saat kamu memikirkan hal lain tidak. Dalam seminggu kerja normal, codebase menumpuk literal dari satu jalur yang tidak dicakup file instruksi, dan developer yang sudah menulis file aturan dengan cermat mengira agen mengabaikannya.

Claude Code tidak punya inline completion, tetapi dokumentasinya menyampaikan hal yang setara dari sisi lain: isi CLAUDE.md adalah konteks, bukan konfigurasi yang ditegakkan, dan untuk memblokir sebuah tindakan terlepas dari apa pun keputusan model, kamu memakai hook. Itulah model mental yang tepat untuk semua tool di sini. File instruksi menggeser probabilitas. Mereka tidak menegakkan.

Apa yang benar-benar menegakkan aturan?

Aturan lint di CI, dan itu hanya tambahan satu baris karena file aturan sudah menyuruh agen menjalankannya. eslint-plugin-i18next menyediakan no-literal-string; aktifkan untuk direktori komponenmu dan literal di JSX akan menggagalkan build, bukan sekadar mendapat pengingat sopan. Cara setup, opsi aturannya, dan alasan instruksi dan penegakan adalah dua lapisan berbeda diuraikan di mengapa Cursor terus menambah teks hardcode setelah i18n disiapkan, jadi post ini tidak mengulangnya.

Ada dua hal yang bisa diberikan lapisan lint tetapi tidak bisa diberikan file aturan. Lint menangkap hasil inline completion, karena berjalan pada file, bukan pada percakapan. Dan lint menjadikan loop agen itu sendiri sebagai jalur perbaikan: aturan terakhir di blok di atas menyuruh agen menjalankan lint sebelum selesai, dan agen yang melihat no-literal-string gagal akan langsung membuatkan kunci untuk teks itu dalam sesi yang sama.

Khusus untuk Claude Code, hook PreToolUse atau post-edit yang menjalankan linter pada file yang baru ditulis adalah mekanisme penegakan yang ditunjuk dokumentasinya. Hook berjalan sebagai perintah shell pada titik-titik tetap dan berlaku terlepas dari apakah model memilih mengikuti aturan.

Bagaimana dengan teks yang masih lolos?

Teks itu perlu diekstrak, diberi kunci sesuai namespace yang ada, dan diterjemahkan, dan bagian inilah yang layak diotomatiskan, bukan diatasi dengan prompt ulang. Build yang gagal hanya memberi tahu bahwa ada literal. Seseorang tetap harus mengubahnya menjadi kunci, menambahkannya ke en, dan memasukkannya ke setiap bahasa lain.

Di lapisan inilah globalize.now berada. Konversi hanya dilakukan sekali dan berlangsung di dalam aplikasi: hubungkan repositori, dan codebase dikonversi satu kali, dengan katalog dikirim sebagai pull request yang kamu review. Sesudah itu, push job menerjemahkan unit katalog baru begitu masuk, sehingga kunci yang ditambahkan di PR hari Selasa sudah punya terjemahannya pada hari Rabu. Library runtime, format katalog, dan file aturan di atas sepenuhnya milikmu; referensi developer membahas bagaimana agen di Cursor, Claude Code, Codex, dan Copilot mengambil peran pascasetup, dan integrasi Cursor adalah panduan tersingkat.

Dua pola kegagalan terkait punya post sendiri. Jika masalahnya agen menulis ulang copy yang sudah diberi kunci, lihat cara menghentikan agen AI menulis ulang copy UI-mu, dan solusinya adalah disiplin bahasa sumber yang sama dengan aturan kesembilan di atas. Jika bahasa-bahasanya sudah ada tetapi terus tidak sinkron, mengapa file terjemahan bisa tidak sinkron menjelaskan kegagalan routing di baliknya.

Mulai dari mana?

Tempel blok tersebut, batasi cakupannya ke direktori UI-mu, dan aktifkan no-literal-string di CI di hari yang sama. Lalu amati apa yang ditangkap aturan lint selama seminggu; itu ukuran seberapa banyak yang bisa dilakukan file aturan sendirian. Jika kamu mengirim aplikasi buatan AI dan ingin ekstraksi serta terjemahan semua yang masih lolos ditangani, bukan dipelihara sendiri, halaman vibe coder adalah ringkasannya dan harga ada di halaman tersendiri.

globalize.now mengubah teks hardcode di aplikasimu menjadi file locale yang siap diterjemahkan, lalu menjaganya tetap diperbarui setiap kali kamu rilis.

Coba globalize.now gratis