Kullanıcıya görünen her metin depodaki tek bir katalogda durduğunda, anahtarla çağrıldığında ve yalnızca gözden geçirilen bir diff üzerinden değiştiğinde arayüz metinleri tutarlı kalır. Mantığa zaten uyguladığın disiplinin aynısı, bu kez ifadelere uygulanıyor. Bu sayfanın geri kalanı, bu düzeni sürdürülebilir kılan pratiklerden oluşuyor.
Bu sayfa uygulama rehberi. Arkasındaki mimariyi ve ürün metinleri için neden kod tabanının tek doğru kaynak olması gerektiğini kod odaklı ürün metni yazısında anlattık. Nedenini merak ediyorsan oradan başla. Nasılını merak ediyorsan okumaya devam et.
Arayüz metinleri nerede durmalı?
Her kaynak dil için depo içinde, onu render eden kodun yanında tek bir katalog dosyasında. Elektronik tabloda, tasarım dosyasında ya da Mart'ta doğru olan bir wiki sayfasında değil. Katalog; geliştiricinin, gözden geçirenin, çevirmenin ve kod yazan agent'ın bir ekranın ne yazdığını öğrenmek istediğinde baktığı tek yer olmalı.
Bundan çıkan pratik kurallar şunlar:
- Tek katalog, tek kaynak dil. Tek bir
en.json(ya da.po,.ftl,.strings, i18n kütüphanen hangisini okuyorsa) metnin resmi kaynağıdır. Monorepo'da birkaç uygulaman varsa her uygulamanın kendi kataloğu olur, ortak metinler için de ikisinin de import ettiği ortak bir katalog açılır. Kaçınman gereken, aynı mesajı barındırabilen iki dosyanın olması. - Anahtarları bileşene göre değil, ekrana ya da özelliğe göre grupla.
checkout.summary.totalgibi anahtarlarSummaryCard.totalLabelgibilerden daha uzun ömürlü olur, çünkü bileşenler yeniden adlandırılır ve bölünür, ekran ile mesaj ise yerinde kalır. - Anahtara ifadeyi değil, mesajı adlandır.
checkout.submit“Place order” metni “Buy now” olarak değişse de geçerliliğini korur.checkout.placeOrderButtonise korumaz; anahtar ile metin arasındaki bu uyumsuzluk yüzünden gözden geçiren kişi ileride bunları iki ayrı metin sanabilir. - Katalogu, onu kullanan kodla aynı pull request'te tut. Bir metni bir PR'da, bileşenini başka bir PR'da eklemek; o metnin gözden kaçmasına, unutulmasına ya da kopyalanmasına yol açar.
Metinlerin hâlâ bileşenlerin içinde sabit değer olarak duruyorsa, oluşturman gereken ilk şey katalogdur. Bunu elle yapmak başlı başına bir proje; aşağıda ele aldığımız depoyu bağlayıp dönüşümü otomatiğe bırakmanın gerekçesi de tam olarak bu.
Anahtarla çağırmak, sabit metni aramaktan neden daha iyi?
Çünkü bir anahtar yalnızca tek bir metne çözülür, sabit bir metin ise geliştirici sayısı kadar farklı yazılabilir. “Sign in”, “Sign In”, “Log in” ve “Login” arama aracı için dört ayrı metin, kullanıcı için tek bir niyet. Her bileşen t("auth.signIn") çağırdığında hangi ifadenin doğru olduğu tek bir yerde, bir kez cevaplanır ve cevap anahtarın kullanıldığı her yerde geçerli olur.
İki alışkanlık bu düzeni ayakta tutar:
- Eklemeden önce yeniden kullan. Anahtar oluşturmadan önce katalogda mesajı ara.
common.cancelzaten varsa aynı metinle yeni birdialog.cancelButtoneklemek zararsız bir kopya değil, sapmanın başlangıcıdır. İkisinden biri değiştiği anda ikisi birbirinden bağımsız düzenlenmeye başlar. - Birleştirme yapma.
t("cart.items") + " " + counthiçbir katalog satırının karşılığı olmayan bir metin üretir. Cümlenin tamamı gözden geçirilebilen tek bir birim olsun diye kütüphanenin interpolasyon ve çoğul biçimlerini kullan.
İnsanların sığındığı bahane şu: “Bu metin sadece bir yerde geçiyor, sabit değer sorun olmaz.” Bugün bir yerde geçiyor. Yarın bileşen kopyalanır, ekranın bir kardeşi çıkar; sabit metin de onunla birlikte gider ve sonra ikisi birbirinden ayrılır.
Metin değişikliklerini pull request'te nasıl gözden geçirirsin?
Değişen bir katalog satırına, değişen bir fonksiyon imzasına davrandığın gibi davran: gözden geçirenin okuyup sorguladığı ve onayladığı bir şey olsun. Tutarlılığı bir hafıza sorunundan bir review sorununa çeviren pratik bu. Review de birinin gerçekten dikkat verdiği tek an.
Katalog review'unu işe yarar kılan şeyler:
- İfade değişikliği diff'te kendi satırında görünür. Bu yalnızca metin katalogdaysa geçerli. Bileşenin içindeki bir ifade değişikliği de diff satırıdır, ama mantık değişikliklerinin arasında kaybolur ve “sadece metin” diye geçilir.
- Katalog değişikliklerini bir metin sahibine yönlendir. Katalog yolunda tanımlı bir
CODEOWNERSgirdisi sayesinde ifadenin sahibi (ürün sorumlusu, içerik tasarımcısı ya da konuyu en çok önemseyen geliştirici) katalogdaki her değişiklikte otomatik olarak review'a çağrılır. PR'ın geri kalanı normal review'dan geçer. - Değişen her satır için üç soru sor. Bu, söz konusu şey için onaylı terim mi? Çevresindeki metinlerle ton ve büyük/küçük harf kullanımı açısından uyumlu mu? Anahtar adı hâlâ mesajı tarif ediyor mu? Bu üç soruyu soran bir reviewer, stil kılavuzunun önlemek için var olduğu hataların çoğunu yakalar.
- Sessiz yeniden adlandırmaları reddet.
auth.signInmetnini “Sign in” yerine “Log in” yapan ve hiçbir açıklama içermeyen bir PR, o sırada dosyayı kim düzenliyorsa onun verdiği bir metin kararıdır. PR açıklamasında nedenini anlatan bir cümle olmalı, yoksa geri alınmalı.
Bunun önlediği hatanın bir adı var. Metin sapması (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ğru kaynak da yok. Copy drift nedir yazısı nedenlerini anlatıyor; diff'te katalog review'u ise çoğunu durduran pratik.
Koda yeni gömülü metinlerin girmesini nasıl engellersin?
Yeni bir sabit metnin build'i kırmasını sağla. Kurallar ve review'lar, insanların bakmayı akıl ettiği şeyleri yakalar. Geri kalanı lint kuralı yakalar; her pull request'te, kimsenin hatırlamasına gerek kalmadan.
Kurulum küçük:
- no-literal-string kuralını etkinleştir.
eslint-plugin-i18nextJavaScript ve TypeScript projeleri için böyle bir kural sunuyor. Kuralı JSX metinleriyle ve input ipuçları,title,aria-labelvealtgibi kullanıcıya dönük attribute'larla sınırla; test dosyalarını ve Storybook story'lerini kapsam dışı bırak ki kural güvenilir kalsın. - Merge'lerin olduğu yerde çalıştır. pre-commit hook'u kullanışlıdır; asıl önemli olan CI adımıdır, çünkü yazarın editörü yapılandırılmış olsun olmasın pull request üzerinde çalışır.
- Kullanılmayan ve eksik anahtarlar için bir kontrol ekle. Çoğu i18n kütüphanesinin, kodda referans verilip katalogda olmayan anahtarları ve katalogda olup hiçbir yerde kullanılmayan anahtarları listeleyen bir yardımcı aracı vardır. Bunu da CI'da çalıştır. Eskimiş ifadeler kullanılmayan anahtarların içinde saklanır.
- Sıkı başla, istisnaları yorumla tanımla.
components/klasörü için tamamen kapatılmış bir kural, kural değildir. Tek satırda, gerekçesiyle kapatılmış bir kural ise dokümantasyondur.
AI kodlama araçlarıyla çalışan ekipler bunu daha sert yaşıyor, çünkü araçlar bileşenleri yerel bağlamdan yeniden üretiyor ve sabit metinleri de beraberinde geri getiriyor. Cursor AI neden sürekli koda gömülü metin ekler yazısı; kurallar dosyası, linter ve CI'dan oluşan üç katmanlı kurulum dahil, lint kuralını ayrıntılı anlatıyor.
Geliştiriciler için bir metin stil kılavuzunda neler olmalı?
Depoda duran, tek ekrana sığan; tonu belirleyen, terimleri sabitleyen ve metinlerin nereye gideceğini söyleyen kısa bir dosya. Uzun stil kılavuzları wiki'de durur ve bir kez okunur. Kısa olan koda yakın durur, bir metin eklendiğinde hem insanlar hem araçlar tarafından her seferinde okunur.
İşe yarayan bir COPY.md (ya da mevcut katkı rehberinde bir bölüm) şunları kapsar:
- Üç cümlelik ton. Ürün kime benziyor, ne kadar resmi, “sen” mi diyor yoksa “kullanıcı” mı? Çoğu tartışmayı bitirmeye yetecek kadar.
- Asla değişmeyen terimler. Her özelliğin ürün içindeki adı, temel eylemlerin fiilleri (“Save” mi “Update” mi? “Delete” mi “Remove” mu?) ve kullanmamaya karar verdiğin kelimeler.
- Büyük/küçük harf ve noktalama kuralları. Butonlarda ve başlıklarda cümle düzeni mi başlık düzeni mi, tooltip'lerde nokta olacak mı, sayılar ve tarihler nasıl yazılacak.
- Metinlerin nereye gideceği ve anahtarların nasıl adlandırılacağı. Katalog yolu, gruplama kuralı, anahtar adlandırma kuralı ve “eklemeden önce ara”.
- Emin olmadığında ne yapılacağı. Kime sorulacağı ya da o sırada hangi anahtarın yeniden kullanılacağı.
Depoda tut; böylece bir kurallar dosyası ona işaret edebilir, reviewer yorumda ona link verebilir ve kodlama agent'ı bir etiket yazmadan önce onu okuyabilir.
AI kodlama agent'larının tutarlılığı bozmasını nasıl engellersin?
Agent'a okuyacağı bir doğru kaynak ver ve okumadığında onu yakalayan bir kapı kur. Bir form üreten agent, bir ekranda “Submit”, bir sonrakinde “Send” yazar; çünkü her biri o an için en olası kelimedir. Dikkatsiz değil; tutarlı olacağı bir referansı yok.
İki hamle sorunun çoğunu çözer. Birincisi, şunu söyleyen bir kurallar dosyası (AGENTS.md, .cursor/rules, CLAUDE.md, araçların hangisini okuyorsa): kullanıcıya görünen metin katalogda durur, mevcut anahtarları yeniden kullan ve etiket yazmadan önce COPY.md dosyasını oku. İkincisi, yukarıdaki bölümdeki lint kuralı; çünkü kurallar dosyası tahmini azaltır, lint kuralı ise geçen tahminleri yakalar.
Bu sayfanın agent'lar hakkında söyleyeceklerinin tamamı bu kadar. Bir agent'ın zaten var olan metinleri yeniden yazması ve bu düzenlemenin sessiz değil görünür olması ise ayrı bir konu: AI kodlama agent'larının arayüz metinlerini yeniden yazmasını nasıl durdurursun.
Yerelleştirme bunun neresinde?
Tutarlılık da yerelleştirme de aynı şeye, üzerinde anlaşılmış bir kaynağa dayanır; dolayısıyla birini sağlayan katalog ötekini de sağlar. Üç ifadeden hangisinin onaylı olduğunu söyleyemeyen bir ekip, hiçbirini doğru çeviremez. Kaynağı düzelt, çeviri de kendi doğru kopyası olan ayrı bir proje olmaktan çıkıp katalogdan türeyen bir çıktı hâline gelsin.
Pratikte bu, tutarlılık için kurduğun katalogun zaten bir çevirmenin ya da çeviri aracının çalıştığı dosya olması demek. Her anahtarın her hedef dildeki karşılığı olur, aynı anahtar adları geçerli olur ve kaynak katalogdaki bir ifade değişikliği, çevirilerin takip etmesi gereken bir değişiklik olarak görünür. Çeviriler kaynağın gerisinde sapmaya bırakıldığında çeviri dosyaları neden senkronun dışına çıkar yazısında anlatılan sorunlar çıkar. Çözüm yine aynı disiplin: tek katalog, anahtarlar, diff'te değişiklikler.
globalize.now'ın yeri
globalize.now, yerelleştirmesi hazır gelen, kod odaklı bir metin yönetim sistemi; bu sayfadaki her pratik de deponla ilgili varsayımlarının özeti. Uygulamada bir GitHub ya da GitLab deposu bağlarsın. Bir tarama neyin nerede olduğunu çıkarır. Metinler bileşenlerin içinde sabit değer olarak duruyorsa tek seferlik bir dönüşüm bunları anahtarların arkasına, bir katalogun içine taşır; i18n kurulumu yoksa onu da ekler. next-intl, react-i18next, i18next ya da Lingui kullanıyorsan mevcut kurulumunla çalışır. Sonuç kendi branch'inde bir pull request olarak gelir; yani ilk katalog yukarıda anlatılan review'dan aynen geçer. Sonrasında eklediğin yeni kaynak metinler, sonucu pull request olarak açan push job'larıyla çevrilir. Tek doğru kaynak depo olarak kalır.
Hedefimiz, aynı disiplinin pazarlama sitesinde, landing page'de ve üründe tek bir kaynaktan işlemesi; böylece bir özellik, kullanıcının karşılaştığı her yerde aynı şekilde anlatılır. Bu bir yol haritası; bugün satın alınabilecek bir şey değil. Fiyatlar fiyatlandırma sayfasında.
Bu hafta uygulayabileceğin bir kontrol listesi
- Her kaynak dil için depoda bir katalog oluştur ve anahtar adlandırma kuralını belirle.
- En çok kullandığın ekranlardaki metinleri kataloga taşı ve anahtarla çağır.
- Kullanıcıya dönük metinlerle sınırlı bir no-literal-string lint kuralını aç ve CI'da çalıştır.
- Katalog yoluna bir
CODEOWNERSsatırı ekle. COPY.mddosyasını yaz: ton, sabit terimler, büyük/küçük harf kuralları, metinlerin nereye gideceği. Tek ekran.- Agent'ının kural dosyasını kataloga ve
COPY.mddosyasına yönlendir. - PR açıklamasında gerekçesi olmayan her ifade değişikliğini review'da reddet.
İkinci adım bir aylık iş gibi görünüyorsa bir depo bağla, önerdiği planı oku ve açtığı pull request'i gözden geçir.
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