--- title: "ICU MessageFormat & Placeholder Kılavuzu (Doğru Kullanım)" description: 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. url: "https://cevirihizmetleri.com.tr/belgeler/icu-messageformat-placeholder-kilavuzu/" updated: "2026-11-07" category: Yerelleştirme --- # 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](https://cevirihizmetleri.com.tr/yerellestirme/). ## 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ırnak**la 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](https://cevirihizmetleri.com.tr/belgeler/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](https://cevirihizmetleri.com.tr/belgeler/yazilim-uygulama-yerellestirme-rehberi/) - [L10n QA Kontrol Listesi](https://cevirihizmetleri.com.tr/belgeler/l10n-qa-kontrol-listesi/) - [Çok Dilli SEO: hreflang, x-default ve Kanonik](https://cevirihizmetleri.com.tr/belgeler/hreflang-x-default-rehberi/) - [Sürekli Yerelleştirme (CI/CD) — Blog](/surekli-yerellestirme-ci-cd-nedir-nasil-kurulur/) Projeniz için teknik dil kuralları ve ICU uygulamasını birlikte tasarlayalım: [Teklif Al](https://cevirihizmetleri.com.tr/yerellestirme/) ya da [İletişim](https://cevirihizmetleri.com.tr/iletisim/).