Aşağıdaki i18n bölümü AGENTS.md dosyasına yapıştıracağın bölüm: bir kodlama agent'ına kullanıcıya görünen her metni çeviri fonksiyonundan geçirmesini, özelliğe göre anahtarlamasını, parçaları asla birleştirmemesini, çoğulu asla üçlü operatörle taklit etmemesini ve üretilmiş bir dil dosyasına asla dokunmamasını söyleyen on kısa kural. globalize.now yapay zekâ destekli yerelleştirme altyapısı olduğu için agent'ların yazdığı çok sayıda i18n kodu okuyoruz ve hataların neredeyse tamamı aynı birkaç hatadan çıkıyor. Her kural bunlardan birine karşılık geliyor.

Yazının ikinci yarısı dosyanın nerede işe yaramadığıyla ilgili. Geliştiricilerin en çok kullandığı iki kod yüzeyi dosyayı hiç okumuyor ve hiçbir ifade bunu düzeltmiyor.

AGENTS.md'nin i18n bölümü ne söylemeli?

Şunu. Üç dosya yolunu ve lint komutunu projene göre uyarla, gerisine dokunma.

## 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.

On kural bilinçli bir seçim. Cursor'ın kendi kurallar belgesi, kuralları sık kullandığın kalıplara odaklı tutmanı ve stil kılavuzunu yapıştırmak yerine linter kullanmanı söylüyor. Claude Code'un yönergesi de aynı: talimatları doğrulanabilecek kadar somut yaz ve dosya büyüdükçe uyum düştüğü için kısa tut. Kırk maddeye uzayan bir i18n bölümü göz gezdirilip geçilir.

Neden sadece “i18n kullan” değil de bu on kural?

Çünkü “i18n kullan”, agent <Button>Save changes</Button> yazarken zaten yaptığını sandığı şeydir. Belirsiz talimatlar agent'ın kendi uyum anlayışıyla karşılanır. Aşağıdaki her kural belirli bir çıktıyı adıyla anar ve yasaklar.

Attribute'lardaki sabit metinler. Agent'lar JSX çocuklarının çevrilmesi gerektiğini öğrenir, sonra aria-label="Close" ve alt="Company logo" değerlerini düz string olarak yazar; çünkü attribute'lar metin değil yapılandırma gibi görünür. Attribute'ları adıyla saymak bu boşluğu kapatır; genel bir “her şeyi çevir” kapatmaz.

Birleştirme. t('greeting') + ' ' + name + '!' İngilizce'de sorunsuz görünür ama adı başa alan veya çekimleyen hiçbir dile çevrilemez. Interpolation, çevirmene tek değişkeni taşıyacağı tek bir metin verir.

Üçlü operatörle çoğul. count === 1 ? 'item' : 'items', i18n kurulduktan sonra bir agent'ın en sık yazdığını gördüğümüz kalıp ve ikiden fazla çoğul biçimi olan her dilde yanlış. Kural bu kalıbı adıyla anar, böylece agent onunla eşleştirme yapabilir. Kataloğunuz ICU kullanıyorsa sözdizimini ICU MessageFormat'ın ne olduğu ve yapay zekâyla üretilen uygulamalarda nerede bozulduğu yazısı anlatıyor.

Üretilmiş dil dosyaları. Bu kural var, çünkü agent'lar yardımsever. Bir Almanca yazım hatasını düzeltmesi istenen agent locales/de.json dosyasını açıp düzenler; bu, bir sonraki çeviri işi dosyayı kaynaktan yeniden üretene kadar işe yarar. Kaynak olmayan dosyaların üretilmiş olduğunu ve asıl düzeltmenin nereye yapılacağını söylemek, bir sessiz regresyon sınıfını engeller.

Aynı değişiklikte en düzenlemek. Bu olmazsa agent t('checkout.summary.total') ekleyip devam eder ve biri fark edene kadar anahtar kendi adıyla görünür. Katalog girdisi ile ilk kullanımı aynı diff'te olmalı.

Hangi araç dosyayı gerçekte nereden okuyor?

Aynı içerik agent'a göre farklı yerlere konur ve yerleşim, kuralın her zaman bağlamda mı olacağını yoksa yalnızca gerektiğinde mi yükleneceğini belirler.

Depo kökündeki AGENTS.md ortak konumdur. Biçim, zorunlu alanı olmayan düz Markdown'dır; Linux Foundation çatısı altında Agentic AI Foundation tarafından yürütülür ve Cursor, Codex, Copilot coding agent ve uzun bir liste başka araç tarafından okunur. Spesifikasyon iç içe dosyaları destekler; düzenlenen dosyaya en yakın olan geçerli olur.

Cursor AGENTS.md dosyasını iç içe olanlar dahil doğrudan okur, ayrıca kendi kapsamlı biçimi de vardır. Arayüz dosyalarına kapsamlanmış bir kural, eşleşen bir dosya açılana kadar bağlamın dışında kalır:

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

Dosyanın uzantısı .mdc olmalı ve .cursor/rules/ içinde durmalı; o klasördeki düz .md frontmatter taşımadığı için yok sayılır.

VS Code'daki GitHub Copilot'ta üç seçenek var. .github/copilot-instructions.md her sohbet isteğine uygulanır. Frontmatter'ında applyTo: "**/*.tsx,**/*.jsx" bulunan bir .github/instructions/i18n.instructions.md dosyası yalnızca bu dosyalar oluşturulduğunda veya değiştirildiğinde uygulanır. Depo kökündeki AGENTS.md ise chat.useAgentsMdFile ayarı açıkken Local agent tarafından okunur; alt klasörlerdeki iç içe AGENTS.md dosyaları, varsayılan olarak kapalı olan ayrı bir deneysel ayarın, chat.useNestedAgentsMdFiles, arkasındadır. Copilot'a özgü davranış GitHub Copilot ile yapılmış bir uygulamaya i18n nasıl eklenir yazısında anlatılıyor.

Claude Code CLAUDE.md dosyasını okur; v2.1.277'den beri çalışma dizininin üstünde CLAUDE.md yoksa kökteki AGENTS.md dosyasını da kendiliğinden okur. İkisini de tutuyorsan belgelenen kalıp, dosyanın bir kez yüklenmesi için CLAUDE.md başına bir @AGENTS.md importu koymaktır. Kapsamlandırma için frontmatter'ında paths: listesi olan .claude/rules/i18n.md, yalnızca Claude eşleşen bir dosyayı okuduğunda yüklenir. Claude Code'un tüm iş akışı Claude Code'un ürettiği uygulama nasıl yerelleştirilir yazısında.

Birkaç agent'ın dokunduğu bir depo için pratik düzen şu: ekibinin en çok kullandığı agent için on kural kapsamlı bir dosyada, AGENTS.md içinde ise iki satırlık bir yönlendirme (“Arayüz metinleri: .cursor/rules/i18n.mdc içindeki i18n kurallarına bak ve uy”). Böylece kapsam desteği olmayan agent de talimatı alır.

Hangi kod yüzeyleri AGENTS.md'yi hiç okumaz?

Satır içi tamamlamalar. Bunu iki sağlayıcı da belgeliyor ve kurallar dosyasının tek başına çözüm olamamasının nedeni bu.

Cursor'ın kurallar SSS'si “Kurallar Cursor Tab'i veya diğer yapay zekâ özelliklerini etkiler mi?” sorusuna düz bir hayırla cevap veriyor. Kurallar Agent'ı besler; Tab, yazdığın satırı tamamlayan otomatik tamamlama, onları görmez. VS Code'un özel talimatlar sayfası Copilot için aynı notu taşıyor: editörde yazarken çıkan satır içi önerilerde talimatlar hesaba katılmaz.

Yani bir geliştiricinin <p>No results found</p> yazıp hayalet metni kabul ettiği yüzey, kuralların hiç ulaşmadığı yüzeydir. Chat ve agent modu metni anahtarlar; sen başka bir şey düşünürken satırı bitiren tamamlama anahtarlamaz. Normal bir hafta boyunca kod tabanı, talimat dosyasının kapsamadığı tek yoldan sabit metin biriktirir; özenli bir kurallar dosyası yazmış olan geliştirici de agent'ın onu yok saydığını sanır.

Claude Code'un satır içi tamamlama yüzeyi yok ama belgeleri aynı noktayı öbür taraftan vurguluyor: CLAUDE.md içeriği bağlamdır, zorlanan yapılandırma değildir; model ne karar verirse versin bir eylemi engellemek için hook kullanırsın. Buradaki her araç için doğru zihinsel model bu. Talimat dosyaları olasılıkları kaydırır. Zorlamaz.

Kuralı gerçekte ne zorlar?

CI'daki bir lint kuralı ve kurallar dosyası agent'a zaten onu çalıştırmasını söylüyorsa tek satırlık bir ektir. eslint-plugin-i18next ile no-literal-string gelir; bileşen dizinlerin için aç, JSX'teki sabit metin nazik bir hatırlatma yerine build'i kırsın. Kurulum, kuralın seçenekleri ve talimat ile zorlamanın neden iki ayrı katman olduğu i18n kurulumundan sonra Cursor neden hâlâ koda gömülü metin ekler yazısında anlatıldığı için burada tekrar etmiyoruz.

Lint katmanının kurallar dosyasının veremediği iki şeyi var. Satır içi tamamlama çıktısını yakalar, çünkü konuşma üzerinde değil dosya üzerinde çalışır. Ve agent'ın kendi döngüsünü düzeltmeye çevirir: yukarıdaki bloktaki son kural agent'a bitirmeden önce lint çalıştırmasını söyler ve no-literal-string başarısız olduğunu gören bir agent metni aynı oturumda kendisi anahtarlar.

Claude Code için özellikle, az önce yazılan dosyada linter çalıştıran bir PreToolUse veya düzenleme sonrası hook, belgelerinin işaret ettiği zorlama mekanizmasıdır. Hook'lar sabit noktalarda kabuk komutu olarak çalışır ve model kurala uymayı seçmiş olsun olmasın uygulanır.

Yine de sızan metinlere ne olur?

Çıkarılmaları, mevcut namespace'lere göre anahtarlanmaları ve çevrilmeleri gerekir; yeniden prompt yazmak yerine otomatikleştirmeye değer kısım bu. Kırmızı bir build sabit metin olduğunu söyler. Onu anahtara çevirmek, en dosyasına eklemek ve diğer tüm dillere ulaştırmak yine birinin işi.

globalize.now tam bu katmanda durur. Dönüştürme tek seferliktir ve uygulama içinde olur: depoyu bağla, kod tabanı bir kez dönüştürülür ve katalog, inceleyeceğin bir pull request olarak gelir. Bundan sonra push işleri yeni katalog birimlerini geldikçe çevirir; Salı'daki PR'a eklenen bir anahtarın çevirileri Çarşamba'daki PR'da hazırdır. Runtime kütüphanesi, katalog biçimi ve yukarıdaki kurallar dosyası tamamen senin; [geliştirici referansı] (/developers/) Cursor, Claude Code, Codex ve Copilot'taki agent'ların kurulum sonrası rolü nasıl üstlendiğini anlatıyor, Cursor entegrasyonu ise en kısa anlatım.

İlgili iki hata türünün kendi yazıları var. Sorun agent'ın zaten anahtarlanmış metni yeniden yazması ise bu yapay zekâ agent'larının arayüz metnini yeniden yazmasını durdurma konusu ve çözüm, yukarıdaki dokuzuncu kuraldaki kaynak dil disiplininin aynısı. Diller var ama birbirinden ayrışmaya devam ediyorsa çeviri dosyaları neden senkrondan çıkar yazısı arkasındaki yönlendirme hatasını açıklıyor.

Nereden başlamalı?

Bloğu yapıştır, arayüz dizinlerine kapsamla ve aynı öğleden sonra CI'da no-literal-string kuralını aç. Sonra bir hafta boyunca lint kuralının neyi yakaladığına bak; kurallar dosyasının tek başına ne kadarını yapabileceğinin ölçüsü bu. Yapay zekâyla yapılmış bir uygulama yayınlıyorsan ve sızan her şeyin çıkarılması ile çevrilmesi bakım yükü olmak yerine halledilsin istiyorsan, vibe coder'lar sayfası genel bakış, fiyatlandırma ise kendi sayfasında.

globalize.now koda gömülü uygulama metinlerini çeviriye hazır dil dosyalarına dönüştürür ve sen yayına aldıkça güncel tutar.

globalize.now'ı ücretsiz dene