ICU MessageFormat & Placeholder Kılavuzu (Doğru Kullanım)

Özet: ICU MessageFormat, metin içinde çoğul kuralları (plural), seçim ifadeleri (select) ve sayı/tarih/para birimi biçimlendirmesini güvenle ifade etmenizi sağlar. Bu kılavuz; TR bağlamında doğru kullanım, placeholder yönetimi, JSON içinde dikkat edilmesi gerekenler, doğrulama/QA ve sık hatalar için uygulamaya yönelik örnekler sunar.
Bağlam: Yerelleştirme Hizmetleri.

1) ICU MessageFormat nedir?

• Metin içinde değişkenleri türüne göre biçimlendirir: number, date, time, plural, select, selectordinal.
• Çeviride değişken adları ve ICU anahtarları (ör. plural, select) çevirilmez; yalnızca kullanıcı görünen metin çevrilir.
• Hata riskini azaltır: yanlış çoğul, eksik placeholder, bozuk süslü parantez gibi sorunlar erken yakalanabilir.

2) Çoğul kuralları (plural)

Türkçe çoğul kuralları genellikle “özel durumlar (=0, =1) + other” ile güvenle çözülebilir.

• "notifications.count": "{count, plural, =0 {Bildirim yok} =1 {# bildirim} other {# bildirim}}"
• "cart.items": "{n, plural, =0 {Sepetiniz boş} =1 {Sepette # ürün var} other {Sepette # ürün var}}"

• # sembolü, ilgili sayı değerini otomatik yerleştirir ({count} yazmanıza gerek yoktur).
• Özel eşitlik formları (=0, =1) sayıyı tam karşılaştırır; other geri kalan her şeyi kapsar.

3) Seçim ifadeleri (select)

Kullanıcı rolü, cinsiyet, durum gibi kategorik seçimler için select kullanılır.

• "greeting.role": "{role, select, admin {Yönetici {name}} support {Destek {name}} other {Merhaba {name}}}"
• "welcome.gender": "{gender, select, female {Hoş geldin} male {Hoş geldin} other {Hoş geldiniz}}"

Seçeneklerin dışında gelen değerler other ile karşılanmalıdır.

4) Sıra sayıları (selectordinal)

Türkçede yaygın değildir; İngilizce gibi dillere yönelik sıralamada (1st, 2nd) kullanılır. TR arayüzleri için çoğu zaman gerekmez.

• "rank": "{pos, selectordinal, one {#’inci} two {#’nci} few {#’üncü} other {#’inci}}"

5) Placeholder (yer tutucu) yönetimi

• Yer tutucu adlarını anlamlı ve tutarlı kullanın: {userName}, {appName} gibi.
• ICU metni içinde süslü parantez karakterini literal göstermek isterseniz tek tırnakla kaçış yapın.
• Tek tırnağın kendisini göstermek için iki kez yazılır: ''.

• "welcome.named": "Merhaba {userName}, {appName}’e hoş geldiniz!"
• "escape.example": "'{' ve '}' karakterleri için kaçış gerekir."

6) JSON içinde ICU: doğru kullanım

JSON değerleri dizedir; ICU kalıpları değerin içinde yer alır. Anahtarlar sade ve dosya boyunca tutarlı olmalıdır.

• "login.required": "Lütfen {field} alanını doldurun."
• "errors.limit": "{n, plural, =0 {Hata yok} =1 {# hata} other {# hata}}"
• "due.date": "Son tarih: {ts, date, medium} {ts, time, short}"
• "price": "Tutar: {value, number}"

JSON’da kaçışa dikkat edin; çift tırnak içinde süslü parantezler ICU’nun parçasıdır ve çevrilmez.

7) Sayı, tarih, para birimi biçimlendirme

• "price.currency": "Tutar: {value, number, ::currency/TRY}"
• "updated.at": "Güncellendi: {ts, date, long} {ts, time, short}"
• "percent.done": "Tamamlandı: {p, number, percent}"

Kullanılan i18n kütüphanesinin desteklediği style tanımlarına (örn. short, long, currency) uygun hareket edin.

8) Doğrulama (lint) ve test önerileri

• İçe aktarma sırasında JSON/ICU sentaks doğrulaması çalıştırın; eksik süslü, yanlış değişken adı gibi hataları yakalayın.
• Unit test ile beklenen çıktı eşleşmesini doğrulayın: sayısal değerler için 0/1/diğer senaryoları kapsayın.
• Pseudo-localization ile UI taşması, yön ve karakter desteğini erken görün.

9) LQA (dilsel + kozmetik) ve UI notları

• Çoğul senaryoları ekran görüntüsü üzerinde gözden geçirin; # yerleştirmeleri ve boşluk/başlık uyumunu kontrol edin.
• Buton/etiket kısıtlarında kısaltma ve anlam kaybı olmamasına dikkat edin.
• Ayrıntılı denetim adımları için bkz. L10n QA Kontrol Listesi.

10) Anti-pattern’ler (kaçınılması gerekenler)

• ICU anahtarlarını çevirmek: plural, select, other gibi anahtarlar çevrilmez.
• Yanlış değişken adı: Metinde {count} var ama parametre n. Uyum şart.
• Eksik çoğul formu: =0 veya =1 tanımlanmamışsa yanlış cümle çıkabilir.
• Düz metinle çoğul: Ayrı ayrı “1 bildirim / 2 bildirim” yazmak yerine plural kullanın.
• JSON’da satır sonu/kaçış hataları: Tırnak ve süslü parantez dengesi bozulmamalı.

11) Hızlı kontrol listesi

• Değişken adları tutarlı ve belgelendi.
• TR çoğul: =0, =1 ve other senaryoları kapsandı.
• other her select/plural ifadesinde mevcut.
• Sayısal/tarih biçimleri proje standardı ile uyumlu.
• Lint/test çalıştı; pseudo-localization ve LQA yapıldı.

12) Mini SSS

ICU anahtarlarını çevirmeli miyim?

Hayır. plural, select, other gibi anahtarlar ve biçimleyiciler sabit kalır; yalnızca kullanıcı görünen metin çevrilir.

Türkçe için “one” formunu yazmalı mıyım?

Zorunlu değil. Güvenli yaklaşım: =0, =1 ve other kullanın.

ICU kalıplarını çeviri aracında nasıl korurum?

ICU farkındalığı olan TMS/CAT kullanın; otomatik doğrulama ve korumalı yer tutucular hataları azaltır.

13) Örnek set (kısa başvuru)

• "notifications.count": "{count, plural, =0 {Bildirim yok} =1 {# bildirim} other {# bildirim}}"
• "welcome.named": "Merhaba {userName}, {appName}’e hoş geldiniz!"
• "greeting.role": "{role, select, admin {Yönetici {name}} support {Destek {name}} other {Merhaba {name}}}"
• "updated.at": "Güncellendi: {ts, date, long} {ts, time, short}"
• "price.currency": "Tutar: {value, number, ::currency/TRY}"

14) İlgili içerik ve sonraki adım

• Yazılım ve Uygulama Yerelleştirme Rehberi
• L10n QA Kontrol Listesi
• Çok Dilli SEO: hreflang, x-default ve Kanonik
• Sürekli Yerelleştirme (CI/CD) — Blog

Projeniz için teknik dil kuralları ve ICU uygulamasını birlikte tasarlayalım: Teklif Al ya da İletişim.