Türkçe Karakter Sorunu: Adres Aramasında Normalizasyon
Türkçe karakter sorunu ve yazım hataları adres aramasını nasıl bozar? İ/ı tuzakları, kısaltmalar ve hataya toleranslı arama için kod örnekleri.
Bir kullanıcı arama kutusuna "sisli", bir başkası "ŞİŞLİ", üçüncüsü "Şişli" yazar. Üçü de aynı ilçeyi arıyordur. Arama katmanınız bunları farklı metinler olarak görürse kullanıcı "sonuç bulunamadı" mesajıyla karşılaşır ve formu yarıda bırakabilir. Türkçe karakter sorunu, adres aramasında sık görülen ama kolay gözden kaçan bir hatadır. Bu yazıda büyük/küçük harf tuzakları, klavye ve kodlama kaynaklı yazımlar, kısaltmalar ve hataya toleranslı aramanın arayüze yansıtılması çalışan örneklerle ele alınıyor.
Türkçe karakter sorunu neden aramayı bozar?
Bilgisayar için "ş" ile "s" iki ayrı karakterdir. Düz eşitlik karşılaştırması ya da basit bir LIKE '%sisli%' sorgusu, "Şişli" kaydını bulamaz. Kullanıcıların aynı yeri yazma biçimleri ise oldukça çeşitlidir:
| Kaynak | Kullanıcının yazdığı | Kastedilen |
|---|---|---|
| İngilizce klavye düzeni | Uskudar | Üsküdar |
| Büyük harf / Caps Lock | KADIKÖY | Kadıköy |
| Yanlış kod sayfasıyla aktarılmış veri | Ýstanbul, Þiþli | İstanbul, Şişli |
| UTF-8'in yanlış çözülmesi | ÅžiÅŸli | Şişli |
| Hızlı yazım | Bağdat Cadessi | Bağdat Caddesi |
| Kısaltma | Moda Cad. | Moda Caddesi |
Bu satırlar iki gruba ayrılır. Harf büyüklüğü, aksanlı harfler ve kısaltmalar kurala bağlı dönüşümlerdir; bunları normalizasyon ile çözebilirsiniz. "Cadessi" gibi gerçek bir yazım hatası ise kuralla çözülemez; bunun için bulanık (fuzzy) eşleştirme gerekir. İki sorunu ayrı ele almak hem kodu sadeleştirir hem de hangi katmanın neden sorumlu olduğunu netleştirir.
Büyük/küçük harf tuzakları: İ/i ve I/ı
Türkçede dört ayrı "i" vardır: İ, i, I, ı. Unicode'un dilden bağımsız varsayılan dönüşümü ise I ile i harflerini eşler. Bu yüzden dil ayarı verilmeden yapılan dönüşümler Türkçe metinde yanlış sonuç üretir:
"I".toLowerCase(); // "i" (Türkçede "ı" olmalı)
"i".toUpperCase(); // "I" (Türkçede "İ" olmalı)
"İ".toLowerCase().length; // 2 ("i" + birleşik nokta U+0307)
"I".toLocaleLowerCase("tr-TR"); // "ı"
"i".toLocaleUpperCase("tr-TR"); // "İ"
"İ".toLocaleLowerCase("tr-TR"); // "i"
Üçüncü satır en sinsi olanıdır. Ekranda "i" gibi görünen metin aslında iki karakterdir ve hiçbir "i" ile eşleşmez. Python'da da durum aynıdır, ancak standart kütüphanede dile duyarlı bir lower() yoktur. Görüntüleme amacıyla dönüşüm yapacaksanız İ ve I harflerini önce elle eşleyin:
def tr_lower(s: str) -> str:
return s.replace("I", "ı").replace("İ", "i").lower()
def tr_upper(s: str) -> str:
return s.replace("i", "İ").replace("ı", "I").upper()
Burada önemli bir ayrım vardır. Görüntüleme için Türkçe kurallara uygun dönüşüm kullanın. Arama karşılaştırması içinse ı ile i harflerini aynı anahtara indirgemek daha işlevlidir; çünkü İngilizce klavye kullanan biri "Kadıköy" yazamaz. Veritabanı tarafında da LOWER, ILIKE gibi karşılaştırmaların sonucu collation ayarına bağlıdır. Bu nedenle davranışı varsayım yapmadan test edin.
Arama anahtarı üretmek: normalizasyon fonksiyonu
Temel ilke şudur: Özgün metni görüntüleme için saklayın, karşılaştırma için ondan türetilmiş bir arama anahtarı üretin. Aşağıdaki fonksiyon metni Unicode NFD biçimine ayırır, birleşik işaretleri (ş'nin çengeli, ğ'nin şapkası, İ'nin noktası) siler, küçük harfe çevirir ve ı harfini i yapar:
export function foldChar(ch) {
const base = ch.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
const folded = base === "ı" ? "i" : base;
return folded.length === 1 ? folded : ch;
}
export function searchKey(text) {
return Array.from(text.normalize("NFC"))
.map(foldChar)
.join("")
.replace(/[^\p{L}\p{N}]+/gu, " ")
.trim();
}
searchKey("ŞİŞLİ"); // "sisli"
searchKey("Kadıköy"); // "kadikoy"
Python karşılığı:
import re
import unicodedata
def search_key(text: str) -> str:
decomposed = unicodedata.normalize("NFD", text)
no_marks = "".join(c for c in decomposed if not unicodedata.combining(c))
key = no_marks.lower().replace("ı", "i")
return re.sub(r"[\W_]+", " ", key).strip()
Bu anahtar özellikle yerel filtrelemede işe yarar. Örneğin il listesi gibi küçük ve sabit bir listeyi seçim kutusunda filtrelerken searchKey(il.name).includes(searchKey(girdi)) yeterlidir.
Katlama işlemi bilgi kaybettirir: Farklı iki ad aynı anahtara düşebilir. Anahtarı aday bulmak için kullanın, kimlik olarak kullanmayın. Kullanıcının seçtiği kaydı API'nin döndürdüğü stableId ile saklayın. Bu yaklaşımın gerekçeleri adres veritabanı tasarımı yazısında ayrıntılı olarak anlatılıyor.
Klavye düzeni ve kodlama kaynaklı yazımlar
İngilizce klavye, telefonun otomatik düzeltmesi veya kullanıcının alışkanlığıyla yazılan "Uskudar", "Sisli" gibi girdiler yukarıdaki normalizasyon ile çözülür. Kodlama hataları ise başka bir sorundur. "Ýstanbul" ya da "Þiþli", Türkçe kod sayfasıyla kaydedilmiş bir metnin farklı bir kod sayfasıyla okunmasından doğar. "ÅžiÅŸli" ise UTF-8 baytlarının yanlış çözülmesinin izidir.
Bu tür bozulmaları arama anında düzeltmeye çalışmayın; kaynağında çözün:
- Form, sunucu, veritabanı bağlantısı ve dışa aktarma dosyaları baştan sona UTF-8 olsun. API yanıtları zaten
application/json; charset=utf-8olarak gelir. - Eski sistemlerden veri aktarıyorsanız şüpheli kayıtları işaretleyip gözden geçirin:
const MOJIBAKE = /[ÝÞÐýþð]|Ã.|Å./;
const supheli = kayitlar.filter((k) => MOJIBAKE.test(k.adres));
Otomatik "onarım" haritaları başka dillerdeki meşru karakterleri de bozabilir. Bu yüzden işaretleme ve kontrollü düzeltme daha güvenli bir yoldur.
Kısaltmalar: mah., cad., sok.
Kullanıcılar "Caferağa Mah. Moda Cad." gibi kısaltmalı yazmayı sever. Autocomplete ucu Türkçe yazım farklılıklarına ve küçük yazım hatalarına toleranslıdır. Kısaltmaları sorguyu göndermeden önce açmak ise sorgunun kataloğun kullandığı tam adlara yaklaşmasını sağlar:
const ABBR = {
mah: "Mahallesi", mh: "Mahallesi",
cad: "Caddesi", cd: "Caddesi",
sok: "Sokak", sk: "Sokak",
bulv: "Bulvarı", blv: "Bulvarı",
};
const ABBR_RE = new RegExp(`(?<!\\p{L})(${Object.keys(ABBR).join("|")})\\.?(?!\\p{L})`, "giu");
export function expandAbbreviations(text) {
return text.replace(ABBR_RE, (_, k) => ABBR[k.toLowerCase()]).replace(/\s+/g, " ").trim();
}
expandAbbreviations("Moda Cad."); // "Moda Caddesi"
Harf sınırları \p{L} ile kontrol edildiği için "Sokullu" gibi adların içindeki "sok" değişmez.
Hataya toleranslı adres arama: autocomplete'i doğru çağırmak
"Cadessi" yazan kullanıcıya "Caddesi" önermek için ad listesinin tamamına ve benzerlik algoritmalarına ihtiyacınız olur. Bunu kendiniz kurmak yerine /v1/autocomplete ucunu kullanabilirsiniz. Bu uç il, ilçe, mahalle ve cadde/sokak önerilerini yazım farklılıklarına toleranslı biçimde döner:
curl --get "https://api.apiturkiye.com/v1/autocomplete" \
--data-urlencode "q=Bağdat Cadessi" \
--data-urlencode "provinceCode=34" \
--data-urlencode "types=street" \
--data-urlencode "limit=5" \
-H "X-API-Key: apt_live_..."
API anahtarı tarayıcıya konmaz. Arama kutusu kendi sunucunuza istek atar, sunucunuz API'yi çağırır:
export async function suggest(raw, { provinceCode, districtCode, types = "all" } = {}) {
const q = expandAbbreviations(raw).slice(0, 100);
if (searchKey(q).replace(/ /g, "").length < 3) {
return { data: [], hint: "En az 3 harf yazın." };
}
const url = new URL("https://api.apiturkiye.com/v1/autocomplete");
url.searchParams.set("q", q);
url.searchParams.set("types", types);
url.searchParams.set("limit", "8");
if (provinceCode) url.searchParams.set("provinceCode", String(provinceCode));
if (districtCode) url.searchParams.set("districtCode", String(districtCode));
const res = await fetch(url, { headers: { "X-API-Key": process.env.APITURKIYE_KEY } });
if (res.status === 400) {
const { error } = await res.json();
if (error?.code === "invalid_query") return { data: [], hint: "Aramanızı biraz daha ayrıntılandırın." };
}
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
return { data: body.data, interpretedAs: body.meta.query };
}
Yanıtta dikkat etmeniz gereken alanlar:
meta.query: Sorgunun API tarafından nasıl yorumlandığını gösterir; hata ayıklamada çok işe yarar.matchType:exact,prefix,word_prefixveyafuzzy.fuzzy, kullanıcının yazdığıyla önerinin birebir aynı olmadığını söyler.score: Yalnız sıralama içindir. Adresin geçerli olduğunu ya da teslimat yapılabileceğini kanıtlamaz.
Arama kutusunda kullanıcıya yardımcı olmak
Normalizasyon ve bulanık eşleştirme arka planda çalışır. Kullanıcının bunu hissetmesi ise arayüze bağlıdır. Aşağıdaki kontrol listesi iyi bir başlangıç noktasıdır:
- Eşik ve gecikme: Normalize edilmiş sorgu 3 harfe ulaşmadan istek atmayın ve tuş vuruşlarını kısa bir gecikmeyle (debounce) birleştirin.
- Kapsamı daraltın: Kullanıcı ili veya ilçeyi seçtiyse
provinceCodevedistrictCodegönderin. Aynı adlı yerler arasındaki karışıklık azalır. - Tam etiketi gösterin: "Bağdat Caddesi, Caddebostan, Kadıköy, İstanbul" gibi
labeldeğeri, kullanıcının doğru kaydı seçmesini kolaylaştırır. - Bulanık eşleşmeyi öneri olarak sunun:
matchTypedeğerifuzzyolan sonucu kendiliğinden seçmeyin; kullanıcıya seçtirin. - Eşleşen kısmı vurgulayın: Kullanıcı "kadikoy" yazdığında "Kadıköy" içindeki eşleşmeyi göstermek, toleransı görünür kılar.
- Seçimden sonra kimliği saklayın: Metni değil
stableIddeğerini kaydedin. Kapı numarasını ise seçilen sokak için/v1/streets/{code}/buildings?q=...ucunda arayın.
Vurgulama için foldChar her karakteri tek karaktere indirdiğinden, katlanmış metindeki konumlar özgün metinle hizalı kalır:
export function highlight(label, query) {
const chars = Array.from(label);
const hay = chars.map(foldChar).join("");
const needle = Array.from(query.trim()).map(foldChar).join("");
const i = needle ? hay.indexOf(needle) : -1;
if (i < 0) return [{ text: label, match: false }];
const j = i + needle.length;
return [
{ text: chars.slice(0, i).join(""), match: false },
{ text: chars.slice(i, j).join(""), match: true },
{ text: chars.slice(j).join(""), match: false },
].filter((s) => s.text);
}
Parçaları ekrana basarken innerHTML yerine textContent veya çerçevenizin güvenli metin bağlama yöntemini kullanın. Klavye ile gezinme, boş sonuç durumu ve mobil davranış gibi ayrıntılar için adres otomatik tamamlama yazısına göz atabilirsiniz.
Sonraki adım
Kendi katmanınızda yapmanız gerekenler sınırlıdır: Doğru büyük/küçük harf dönüşümü, karşılaştırma için bir arama anahtarı, kısaltmaların açılması ve baştan sona UTF-8. Yazım hatalarına toleranslı öneri üretme işini ise autocomplete ucuna bırakabilirsiniz. Parametrelerin ve yanıt alanlarının tamamı için API dokümantasyonuna bakabilir, akıllı aramayı içeren ücretsiz Core paketiyle denemek için ücretsiz kayıt olup API anahtarınızı oluşturabilirsiniz.