Hreflang etiketini eklemenin üç yolu var: HTML <head> bloğu, XML sitemap ve HTTP başlığı. Üçü de Google tarafından tanınır; ancak uygulamada en yaygın ve en çok hata üreteni <head> yöntemidir. Sözdizimi yalındır, ama karşılıklı referans zorunluluğu, self-referencing ve sayfa sayısı arttıkça oluşan <head> şişmesi göz ardı edildiğinde Google Search Console beklenmedik uyarılarla dolu bir hreflang raporu sunar.
<link> elementinin sözdizimi ve üç zorunlu nitelik
HTML yönteminde hreflang, sayfanın <head> bölümüne eklenen <link> elementleri üzerinden tanımlanır. Her elemanın üç zorunlu niteliği vardır: rel="alternate", hreflang ve href.
<link rel="alternate" hreflang="tr" href="https://www.orneksite.com/sayfa/" />
<link rel="alternate" hreflang="en" href="https://www.orneksite.com/en/sayfa/" />
<link rel="alternate" hreflang="de" href="https://www.orneksite.com/de/sayfa/" />
<link rel="alternate" hreflang="x-default" href="https://www.orneksite.com/sayfa/" />rel="alternate" Google'a bu bağlantının alternatif bir sürüme işaret ettiğini söyler. hreflang niteliği dil veya dil-bölge kodunu alır; href ise canonical URL'yi. Bu üçü birlikte olmak zorunda; birinin eksik olduğu bir <link> etiketi geçersiz sayılır ve Google tarafından sessizce görmezden gelinir.
Dil kodu formatı için ISO 639-1 (örneğin tr, en, de), bölge kodu için ISO 3166-1 Alpha-2 (örneğin TR, US, GB) kullanılır. Birleşik kod yazımı dil-BÖLGE biçimindedir: en-US, en-GB, pt-BR. Büyük/küçük harf teknik olarak hata değildir ama standarda uymak Search Console raporlarını daha temiz tutar. x-default ise herhangi bir dil-bölge kombinasyonuyla eşleşmeyen kullanıcılar için gösterilecek varsayılan sayfayı işaret eder.
Bu <link> etiketleri sayfanın <head> bloğunun herhangi bir yerine eklenebilir; Google, <head> içindeki sıralamayı anlam farkı olarak yorumlamaz. Ancak bakım kolaylığı açısından yaygın pratik, hreflang bloğunu canonical etiketiyle diğer <link rel="..."> etiketlerinin yanına toplamaktır. Bu, şablon incelemesini hızlandırır ve bir hata raporunda hangi satırın hangi dil sürümüne ait olduğunu bulmayı kolaylaştırır.
Hreflang karşılıklı referans zorunluluğu: hangi sayfaya ne eklenmeli
Hreflang'ın <head> uygulamasında en sık yapılan hata tek taraflı tanımlamadır. Google, hreflang grubunun geçerli sayılması için her sayfanın gruptaki diğer tüm sayfaları referans göstermesini zorunlu tutar; buna karşılıklı referans (return tag) denir.
Türkçe sayfanız İngilizce sayfayı <link hreflang="en"> ile gösteriyorsa, İngilizce sayfanın da <link hreflang="tr"> ile Türkçe sayfayı göstermesi gerekir. Bu yalnızca ikili dil yapıları için değil; beş dilli bir sitede her sayfa diğer dört sayfayı referans göstermelidir.
<!-- Türkçe sayfa (https://www.orneksite.com/urun/) -->
<link rel="alternate" hreflang="tr" href="https://www.orneksite.com/urun/" />
<link rel="alternate" hreflang="en" href="https://www.orneksite.com/en/product/" />
<link rel="alternate" hreflang="x-default" href="https://www.orneksite.com/urun/" />
<!-- İngilizce sayfa (https://www.orneksite.com/en/product/) -->
<link rel="alternate" hreflang="tr" href="https://www.orneksite.com/urun/" />
<link rel="alternate" hreflang="en" href="https://www.orneksite.com/en/product/" />
<link rel="alternate" hreflang="x-default" href="https://www.orneksite.com/urun/" />Return tag eksik olduğunda Google Search Console, "Alternatif sayfada dönüş etiketi yok" uyarısı üretir. Google bu durumda hreflang grubunu yok saymaz; sinyal olarak işler ama güvenilirliğini düşürür. Dil hedefleme kararsız hâle gelir, yanlış dil sürümü sıralamaya girebilir. Ayrıca İngilizce sayfayı siz yönetmiyorsanız, karşı tarafın return tag eklemesini sağlamak gerekir.
Return tag yönetimi ölçekte kırılır.
Dil sayısı da bu yükü doğrudan çarpar. Beş dilli bir site için her sayfada 5 <link> etiketi yeterlidir; 10 dilli bir yapıda bu sayı 10'a çıkar. 20+ dil sürümü olan bir e-ticaret sitesinde her URL 20 <link> taşır ve yeni bir dil sürümü eklendiğinde, var olan tüm sayfaların güncellenmesi gerekir. HTML boyutu render-blocking olmadığı için performans üzerinde doğrudan etkisi sınırlıdır; asıl sorun bakım tarafındadır. Şablon katmanında merkezi bir üretim mekanizması yoksa, sonradan eklenen dil için return tag eksikliği kaçınılmaz hale gelir. Büyük ölçekli projelerde hreflang listesini dinamik olarak üretmek bu nedenle bir tercih değil, zorunluluktur.
Self-referencing: kendi URL'inizi neden listeye dahil etmelisiniz
Sayfanın kendi dil kodunu da <link> listesine eklemek zorunlu değildir; ancak Google bunu önerir ve olmadığında bazı durumlarda uyarı üretilebilir. Teknik kural şudur: hreflang grubundaki her sayfa, hem diğer sürümleri hem de kendisini referans göstermelidir.
Bu kural pratikte anlamlıdır. Google, sayfanın hangi dil grubuna ait olduğunu anlamak için referans listesini kullanır. Sayfanın kendisi listede yoksa, hreflang tarama araçlarının büyük çoğunluğu bunu "eksik self-reference" olarak işaretler. Daha önemlisi: bazı CMS şablonları veya hreflang oluşturma araçları self-reference'ı otomatik ekler; tutarsız bir yapı (bazı sayfalarda kendisi var, bazılarında yok) gereksiz karmaşa yaratır. Hreflang etiketlerini otomatik üretmek için kullandığınız araç bu tutarlılığı zaten sağlamalıdır.
Özellikle büyük ölçekli projelerde self-reference'ı şablon katmanında standart hâle getirmek, sonradan çıkacak uyarıları baştan önler.
Self-referencing'in bir diğer pratik değeri URL değişikliği senaryolarında ortaya çıkar. Bir sayfanın URL'si değiştiğinde hem canonical hem hreflang güncellenmesi gerekir; bu güncellemeyi yapan geliştiricinin tüm dil sürümlerini takip etmesi için listenin sayfanın kendi <head> bloğunda tam olması kolaylaştırıcıdır. Kendisini de referans gösteren sayfa, kendi hreflang grubunun tam görüntüsünü taşır; kayıp sürüm tespiti şablon render sırasında yapılabilir.
Hreflang sözdizimi hataları ve yaygın karıştırmalar
Canonical çelişkisi bu dört hata içinde en sessiz olanıdır; Search Console uyarısı gecikir ama hreflang grubunu fiilen çalışmaz hale getirir. Diğer üçü sözdizimi düzeyinde kalır ve çoğu araç tarafından hemen işaretlenir.
Birincisi: <meta> etiketi kullanmak. Hreflang <meta> etiketi olarak tanımlanamaz; yalnızca <link rel="alternate"> biçiminde yazılır. <meta name="hreflang"> Google tarafından tanınmaz.
İkincisi: href niteliğinde relative URL yazmak. href="/en/sayfa/" değil, href="https://www.orneksite.com/en/sayfa/" olmalıdır. Hreflang, tam canonical URL gerektirir; relative path geçersizdir.
Üçüncüsü: Yanlış dil kodu. hreflang="tur" (ISO 639-2) yazmak sık görülen bir hatadır; doğrusu tr (ISO 639-1). Benzer biçimde hreflang="zh" yazmak Çince için belirsizdir: Basitleştirilmiş için zh-Hans veya zh-CN, Geleneksel için zh-Hant veya zh-TW kullanmak gerekir. zh tek başına Search Console'da geçerli görünse de hedefleme belirsizleşir.
Dördüncüsü: Canonical çelişkisi. Bir sayfanın hreflang href değeri ile canonical etiketi uyuşmuyorsa Google sinyal çatışması yaşar. <link rel="canonical"> farklı bir URL'yi gösterirken hreflang başka bir URL yazıyorsa, hreflang görmezden gelinebilir. Canonical ve hreflang aynı URL'yi işaret etmelidir. Bu ilişkiyi canonical ile hreflang etiketinin birlikte kullanımı konusunda ayrıca ele aldık.
Canonical çelişkisi özellikle subdirectory yapısında sık karşılaşılan bir hatadır. Örneğin, İngilizce sayfanın canonical'i https://www.orneksite.com/en/urun/ gösterirken hreflang href değeri https://www.orneksite.com/en/urun (trailing slash yok) yazıyorsa, Google bu ikisini farklı URL olarak değerlendirebilir. Canonical'de trailing slash kullanıyorsanız hreflang href değerlerinde de aynı formatı tutmak bu tür sessiz uyumsuzlukları önler.
Tüm bu hataları elle takip etmek yerine hreflang etiketleri üretmek için bir araç kullanmak, sözdizimini standart tutar.
SPA ve dinamik sitelerde <link> yönteminin sınırı
HTML <head> yöntemi, Googlebot'un sayfayı taradığında <head> bloğunu statik olarak okuyabilmesine dayanır. JavaScript ile render edilen <head> içeriği bu garantiyi ortadan kaldırır.
React, Vue veya Angular tabanlı bir SPA'da hreflang etiketleri JavaScript tarafından DOM'a eklendiyse, Googlebot sayfayı taramak için yeterli render bütçesi ayırmazsa bu etiketleri görmeyebilir. Google, JavaScript render'ı asenkron işler; kaynak kısıtlamaları nedeniyle render ertelenmiş veya tamamlanmamış sayfalar eksik hreflang sinyaliyle indekslenebilir.
Bu senaryoda iki seçenek var: sunucu tarafı render (SSR) ile <head> bloğunu statik üretmek veya sitemap yönetimine geçmek. Next.js'in generateMetadata veya Nuxt'un useHead composable'ı gibi SSR mekanizmaları doğru yapılandırıldığında hreflang'ı statik HTML'e yerleştirir; bu durumda <head> yöntemi güvenilir çalışır. Ancak SSR garantisi yoksa hreflang'ı XML sitemap üzerinden tanımlamak render bağımlılığını tamamen ortadan kaldırır. Sitemap yöntemi Googlebot için JavaScript ihtiyacı doğurmadan tüm dil gruplarını tek bir noktadan yönetir; büyük ölçekli sitelerde bakım kolaylığı da sağlar.
Hangi yöntemin daha uygun olduğu sitenin teknik altyapısına ve dil sürümü sayısına göre değişir; ancak dinamik render söz konusuysa <head> yöntemini seçmeden önce Googlebot'un bu etiketleri gerçekten gördüğünü doğrulamak gerekir. Google Search Console'un URL Denetleme aracında "Gezinilen Sayfa Kaynağı" bölümü, render edilmiş HTML'yi gösterir ve hreflang etiketlerinin orada bulunup bulunmadığını kontrol etmek için doğrudan kullanılabilir.
Doğrulama adımı şu şekilde işler: Search Console'da hedef URL'yi girin, "Sayfayı Test Et" seçeneğini kullanarak güncel render sonucunu alın ve açılan render görünümünde Ctrl+F ile hreflang aratın. Etiket render edilmiş HTML'de görünüyorsa Googlebot'un onu alabildiğinden makul ölçüde emin olunabilir; görünmüyorsa JavaScript render sorununu çözmeden sitemap yöntemine geçmek daha sağlam bir tercih olur. Render bütçesi ve JavaScript yoğunluğu büyük ölçekli sitelerde her sayfa için bu testi yapmayı imkânsız kılar; bu nedenle SPA projelerinde <head> yöntemi yerine sitemap yöntemi baştan tercih edilmelidir.
HTML <link> yöntemi en hızlı kurulum yolu olarak öne çıkar; ancak karşılıklı referansın tutarlı uygulanması ve canonical ile uyumun korunması, sayfa sayısı büyüdükçe şablon katmanında yönetilmezse kolayca bozulur. Return tag hatası sessizdir; Search Console uyarısı görünene kadar yanlış dil hedeflemesi fark edilmeyebilir. Sıralama raporlarında beklenmedik bir dil sürümünün üst sıralarda çıkması, çoğunlukla eksik return tag'in geç fark edilen belirtisidir.