Claude Code'dan giriş formuna yükleniyor durumu eklemesini istedin. Yükleniyor durumu çalışıyor. Ama butonda artık “Sign in” yerine “Log in” yazıyor, hata mesajı daha samimi olmuş ve bir başlık birden cümle düzenine geçmiş. Bunların hiçbirini kimse istemedi, tüm testler geçiyor ve diff'i kelime kelime okuyan biri çıkmazsa hepsi yayına gidiyor.
Bu yazı tam olarak şu hatayla ilgili: mevcut, onaylanmış metnin bir yapay zekâ kodlama agent'ı tarafından sessizce yeniden ifade edilmesi ve bunu önleyen iş akışı. Agent'ların koda gömülü ve anahtarsız olarak oluşturduğu metinler ayrı bir sorun; onu yapay zekâ kodlama araçları neden koda gömülü metin eklemeye devam eder yazısında ele aldık. Ürün metninin genel olarak nerede durması gerektiği ise mimari bir soru: kod odaklı ürün metni yazısında. Bu yazı yalnızca olaya odaklanıyor: ifadenin değiştiği ve kimsenin değişmesine karar vermediği o Pazartesi sabahı. globalize.now, yerleşik yerelleştirmeye sahip, kod odaklı bir metin yönetim sistemi; bu olay da var olma nedenlerinden biri.
AI kodlama agent'ları arayüz metinlerini neden yeniden yazar?
AI kodlama agent'ları, bileşenlerin içinde duran düz yazıyı gördükleri için arayüz metinlerini yeniden yazar. Metin kaynak dil dosyasında anahtarların arkasına taşındığında, değiştirmek başka bir işin yan etkisi olmaktan çıkar; açık ve gözden geçirilebilir bir düzenlemeye dönüşür.
Bir bileşenin içinde “Sign in”in özel bir statüsü yoktur. JSX niteliğindeki bir string literal'dir; bir className'den ya da test id'sinden ayırt edilemez. Agent, yakındaki kodu iyileştirmenin iyi davranış sayıldığı milyonlarca diff üzerinde eğitildi ve bir model için bir etiketi “daha net” yapmak, bir değişkeni yeniden adlandırmakla aynı hamledir. Bekleyen bir tip hatası, kırılan bir test, kelimelerin üzerinde bir sahip notu yok. Metni değiştirmek agent'a hiçbir şeye mal olmaz.
Değişiklik, aynı nedenle incelemeden de sağ çıkar. İnceleyenler mantığı okur. İfade değişikliği, meşru biçimde bir yükleme durumuyla ilgili olan bir diff'in ortasında durur, derlenir, render olur; bir snapshot testi şikayet ederse alışılmış tepki snapshot'ı güncellemektir, bu da yeni ifadeyi sanki onaylanmış gibi kayda geçirir.
AGENTS.md gibi kural dosyaları bunu gerçekten durdurur mu?
Agent kural dosyaları sıklığı azaltır; arayüz metnini yazılamaz hâle getirmez. Düzenlemeyi görünür kılan şey mimaridir.
Yine de kurallar dosyasını ekle: en ucuz katman ve yeterince sık işe yaradığı için otuz saniyeye değer. Bu blok AGENTS.md, CLAUDE.md ve Cursor kurallarında (.cursorrules ya da .cursor/rules/) çalışır:
## UI copy policy: do not modify user-facing text
- Never change user-visible strings (button labels, headings, empty states,
error messages, tooltips, placeholder text) unless the task explicitly
asks for a copy change.
- User-visible text lives in the source locale file (e.g. locales/en.json).
Reference it by key. Never inline a new user-facing string in a component.
- If a task needs new user-facing text, add a key to the source locale file,
reference it, and list the new key in your summary for copy review.
- Any diff to the source locale file is a copy change. Call it out
separately: it needs its own approval, apart from code review.
Şimdi dürüst kısım. Kural bir bağlamdır ve bağlamlar birbiriyle yarışır. Uzun bir görevde talimat, binlerce token'lık kodun içinde tek satırdır ve bazen kaybeder: compaction'a, onu hiç görmemiş bir alt agent'a ya da çevredeki dosyadaki güçlü bir kalıba. Daha kötüsü, kuralı çiğneyen agent bunu duyurmaz. İfadenin değiştiğine dair bir bildirim almazsın; yalnızca ifadenin değişmiş olduğu bir diff görürsün. Bir alışkanlık, kontrol sayılmaz.
Yani kural dosyası ilk katmandır ve tek başına güvenmemen gereken katmandır.
Bir metin düzenlemesini sessiz olmaktan çıkarıp görünür kılmak nasıl olur?
Kullanıcıya görünen her metni bileşenlerden çıkarıp kaynak dil dosyasında anahtarların arkasına taşı. Bundan sonra metnini değiştirmek isteyen agent, tek işi ifade olan bir dosyayı düzenlemek zorunda kalır.
Kurallar dosyasının yapamadığı adım bu ve mekanizma basit. Bileşenler “Sign in” yazısını tekrar etmek yerine t('auth.signIn') anahtarına başvurduğunda iki şey aynı anda değişir. Bileşen diff'lerinde metin kalmaz, yani yükleme durumunu düzenleyen agent'ın çalıştığı yerde yeniden ifade edecek bir şeyi olmaz. Ve agent'tan da insandan da gelen her metin değişikliği tek bir dosyaya düşer; orada değişen satır, çevresindeki gürültü değil, tam olarak ilgilendiğin olaydır. Dil dosyası diff'ini taramak saniyeler sürer. Kötü bir yeniden ifadeyi geri almak tek satırdır.
Bunun neyi sağladığını net söyleyelim: agent yine dil dosyasını düzenleyebilir. Mesele kelimelerin dokunulmaz olması değil; onlara dokunmanın bir yan etki olmaktan çıkıp okunabilir, incelenebilir bir eyleme dönüşmesi. Yani bir şeyi diff'ten öğrenmekle müşteriden öğrenmek arasındaki ayrım budur.
Doğruluk kaynağını kod tabanında tutmanın (ona senkronlanan bir tasarım aracında değil) tam gerekçesi ana yazıda: kod odaklı ürün metni. Bu yazının ihtiyaç duyduğu tek sonuç şu: anahtarlanmış metin, kurallar dosyanı bir rica olmaktan çıkarıp kontrol edilebilir bir şeye dönüştürür.
Gözden geçirme kapısı neye benzer?
Kaynak dil dosyasındaki her diff'i bir metin değişikliği say ve kelimelerin sahibine yönlendir.
Somut olarak: dil dosyalarının dizinini CODEOWNERS içine koy, böylece orada her değişiklikte metinden sorumlu bir kişiden inceleme istenir. PR şablonuna bir satır ekle: “Bu PR kullanıcıya görünen ifadeleri değiştiriyor mu ve görev buydu mu?” Ayrıca agent'ın özetinde değişen anahtarları listelemesi şartını kurallar dosyasında tut; uyarsa inceleme anında biter, uymazsa CODEOWNERS kancası yine de yakalar.
Küçük bir ekipte bu, kulağa geldiğinden hafiftir. Dil dosyası diff'i kısadır, düz bir dille okunur ve “bu buton artık Log in mi demeli?” beş saniyede verilebilecek bir karardır; yeter ki soru gerçekten birinin önüne konsun, bu kontrol noktasının asıl işi de bu.
Agent metni zaten yeniden yazdıysa ne yaparsın?
Önce onaylanmış metni geri yükle, sonra metinleri anahtarla; bir sonraki değişiklik diff olarak görünsün.
Hasarı bulmak bir git işidir: etkilenen bileşenleri güvendiğin son commit'le karşılaştır ve yalnızca string literal'leri oku. Değişeni geri yükle. Hangi ifadenin onaylanmış olduğunu emin olarak söyleyemiyorsan (buton “Log in” diyor, tanıtım sayfası “Sign in” diyor ve hangisinin doğru olduğunu kaydeden bir kayıt yok), bu olayın da beslediği daha derin sorunla karşı karşıyasın. Metin kayması (copy drift), kullanıcıya görünen metnin yüzeyler arasında ve zaman içinde onaylı kaynağından ayrışması; üstelik ayrışılacak tek bir doğruluk kaynağı da yok. Bu terim, nedenleri ve sonraki etkileri ayrı bir yazının konusu: metin kayması nedir.
Ardından geri yüklediğini anahtarla; agent'ın dokunduğu metinlerden başla. Hedefte olanların onlar olduğu zaten ortada.
Yerelleştirme bunun neresinde?
Sessiz bir metin değişikliği tek dilde can sıkıcıdır, on dilde ise bir yüktür: eski ifadeden türetilmiş her çeviri artık bayattır ve yeniden çevirmen gerektiğini sana söyleyen hiçbir şey yoktur.
Agent olayının birikerek büyüdüğü yer burası. Yeniden ifade edilmiş İngilizceyi yayına alırsan Almanca, Japonca ve İspanyolca metinler hâlâ eskisini söyler: yüzeyler artık yalnızca ekranlar arasında değil, diller arasında da birbiriyle çelişir. Katalogların birbirinden kopması ayrı bir hata modudur ve kendi çözümleri vardır; onu senkrondan çıkan çeviri dosyaları yazısında ele aldık.
Anahtarlanmış metin bu döngüyü de kapatır, çünkü değişen bir kaynak metin, çevirilerin bağlı olduğu görünür bir olaydır; sessizce kayan bir literal değil. globalize.now'ın tasarımı bu: metin kod tabanında, anahtarların arkasında tek kaynaktan yaşar ve yerelleştirme sonradan eklenen bir parça değil, aynı işin parçasıdır: bir depo bağla, her dil o tek kaynaktan türer. Yapay zekâ kodlama araçlarıyla geliştiren ekipler bunu en erken yaşar; bu yüzden geliştiriciler ve yapay zekâ araçlarıyla geliştirenler için yazıyoruz.
Bir sonraki sefer agent bileşenlerinin içinde dolaşırken sorun şu olacak: değişen bir etiket bir karar olarak mı görünecek, yoksa bir sürpriz olarak mı? globalize.now, bağladığın depodaki kullanıcıya görünen metinleri tek kaynakta toplar ve her dili o tek metinden türetir.
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