Etiketleri, Nitelikleri veya Bağlantıları Bozmadan Bir HTML Dosyası Nasıl Çevrilir

Bir HTML dosyasını çevirmek için, insanların okuduğu metinleri ve okuyucuya yönelik kelimeler içeren nitelikleri (örneğin alt, title, placeholder, aria-label ve sayfanın meta açıklaması) çevirin. İşaretlemeyi olduğu gibi bırakın: etiket adları, href, src, id, class, betikler, stiller ve translate="no" ile işaretlenmiş her şey. Ardından, unutulması kolay bir değeri, <html> öğesindeki lang niteliğini değiştirin; böylece tarayıcılar, ekran okuyucular ve arama motorları sayfanın artık hangi dilde olduğunu bilsin.

Etiketleri sağlam tutmak işin kolay kısmıymış. 59 satırlık bir HTML yardım sayfasını yerel bir modelle dokuz kez Basitleştirilmiş Çinceye çevirdik, üç yöntem kullandık ve her çıktıyı bir betikle kontrol ettik. Her çalıştırma tüm etiketleri, bağlantıları ve kimlikleri korudu. Asıl sorun daha sessizdi: model, tüm dosyayı gönderen altı çalıştırmanın hepsinde bir <pre> kod bloğunun içindeki bir satırı çevirdi, altı çalıştırmanın hepsinde gezinme menüsünün aria-label değerini İngilizce bıraktı ve tasarımı gereği işaretlemeyi en güvenli şekilde koruyan yöntem (metin parçalarını tek tek çevirme) üç çalıştırmasının hepsinde okuyucuya yanlış şeyi yapmasını söyleyen bir cümle üretti.

Kısa Yanıt: Neyi Çevirmeli, Neyi Olduğu Gibi Bırakmalı

Bu liste bizim icadımız değil. HTML Standardının translate özniteliği bölümü "çevrilebilir öznitelikleri" tanımlar: her öğedeki title, görsellerdeki alt, girişlerdeki placeholder, adı çevrilebilir olduğu bilinen meta öğelerindeki content ve yeni dile uyacak şekilde değiştirilmesi gerektiğini söylediği lang. Ayrıca ARIA'nın aria-label özniteliğini, diğer belirtimlerin ekleyebileceği bir öznitelik örneği olarak adlandırır ve translate="no" içeren bir öğede metin ve öznitelik değerlerinin "sayfa yerelleştirildiğinde olduğu gibi bırakılacağını" belirtir.

Neyi Test Ettik

Markdown çeviri testimizde kullandığımız aynı kurgusal okuma uygulaması Shelfmark için bir yardım merkezi sayfası olan sample-source.html dosyasını yazdık. Yukarıdaki tablodaki her satırdan bir örnek ve birkaç tuzak içeriyor:

• satır içi etiketlerle bölünmüş bir cümle: "Dışa aktarmadan önce, notlarınızı yedekleyin. Dışa aktarma kitaplarınızı kopyalar, ancak Shelfmark'tan hiçbir şeyi silmez," ve ürün adı translate="no" içinde;
• sırası önemli olan iki satır içi <code> öğesi içeren bir cümle: "--out sonrasına <library> klasörünün yolunu yazın";
• bir komut ve bir satır örnek çıktı içeren bir <pre><code> bloğu, # Export finished: 128 books;
• bir paragrafın önüne "Not:" kelimesini ekleyen bir CSS kuralı;
• #choose-format adresine sayfa içi bir bağlantı, bir mailto: bağlantısı, bir arama formu ve bir JSON-LD bloğu.

Ardından yerel bir modelden bunu Basitleştirilmiş Çinceye üç şekilde çevirmesini istedik:

1. Tüm dosya. Tüm dosyayı yapıştırın ve çevrilmiş dosyayı geri isteyin.
2. Yönlendirilmiş. Aynısı, artı sekiz kural: her etiketi ve öznitelik adını koru, href, src, id, class ve benzeri değerleri değiştirme, listelenen metin özniteliklerini ve meta etiketlerini çevir, JSON-LD name ve description dışında <code>, <pre>, <script> ve <style> öğelerine dokunma, translate="no"ya saygı göster, karakter referanslarını ve yorumları koru ve lang değerini zh-Hans olarak ayarla.
3. Segmentler. HTML'den metin çıkaran araçların yaklaşımı: bir betik dosyayı etiketlere ve metne böler, <code>, <pre>, <script>, <style> ve translate="no" öğelerini atlar, kalan metin parçalarını ve metin özniteliklerini numaralı bir JSON listesi olarak modele gönderir ve çevirileri dokunulmamış işaretlemeye geri yazar. Ayrıca lang="zh-Hans" değerini kendisi ayarlar.

Model, LM Studio'da Qwen 3.6 27B (Q4_K_M) idi; düşünme kapalı ve sıcaklık 0,3 olarak ayarlanmıştı, 64 GB belleğe sahip bir Apple M4 Max üzerinde çalıştırıldı. Her yöntemi üç kez, toplamda dokuz kez, 27 Ekim 2026'da çalıştırdık. Betik run_llm_html_test.py ve dokuz çıktının tamamı düzenlenmeden yayınlandı; README her dosyayı listeler. Daha önce yerel bir model kurmadıysanız, yerel LLM çeviri kılavuzumuz ayarları kapsar.

Bu, tek bir model, tek bir dil çifti ve tek bir sayfa üzerinde küçük bir testti. Hangi sorunların oluştuğunu ve bunları nasıl yakalayacağınızı gösterir. Modelleri veya araçları sıralamaz.

Sonuç: İşaretleme Hayatta Kaldı; Üç Karar Kalmadı

Her çıktıyı, yalnızca Python'un standart kütüphanesini kullanan bir denetleyici olan check_html_translation.py ile kontrol ettik. Tam çıktı check-results.txt dosyasında ve results.csv her çalıştırma için bir satır içeriyor.

Dokuz çalıştırmanın her biri aynı 58 etiketi aynı sırayla, her href, src, id ve class değerini, sayfa içi bağlantı hedefini, yorumu, kaçışlı <library> ifadesini ve translate="no" içindeki ürün adını korudu. Basit bir sayfanın işaretlemesini bir modelin bozacağından endişe ediyorsanız, bozmadı. Sorunların hepsi neyin çevrileceğiyle ilgiliydi.

1. <pre> içindeki örnek çıktı çevrildi

Örneğimizdeki kod bloğu bir satır program çıktısıyla bitiyor:

<pre><code>shelfmark export --format epub --covers --out ~/Books/export
# Export finished: 128 books</code></pre>

Altı tam dosya ve talimatlı çalıştırmanın hepsinde model o satırda # 导出完成：128 本书 döndürdü; buna <pre> içindeki hiçbir şeyi değiştirmemesinin söylendiği üç çalıştırma da dahil. Komutun kendisine hiç dokunulmadı. Model satırı bir yorum olarak değerlendirdi ve bir eğitimde yorumları çevirmek makul bir seçimdir. Ancak bu satır programın yazdırdığı şeydir ve terminaliyle karşılaştıran bir okuyucu İngilizce görecektir. Çeviri yapmadan önce örnek çıktının ve kod yorumlarının çevrilip çevrilmeyeceğine karar verin ve araca söyleyin ya da <pre> bloklarını tamamen koruyun.

Tam dosya çalıştırmaları ayrıca <style> bloğundaki CSS content: "Note: " ifadesini çevirdi; <style> öğesine dokunulmaması söylenen talimatlı çalıştırmalar ise onu İngilizce bıraktı. İkisi de tek başına yanlış değil. Stil sayfasını çevirmek, CSS'in satır içi olduğu bir sayfa için doğru, tek bir paylaşılan stil sayfasının her dile hizmet ettiği bir site için yanlıştır. Her iki durumda da bu, birinin vermesi gereken bir karardır, modelin tahmin etmesi gereken bir ayrıntı değil.

2. Erişilebilirlik etiketleri atlandı

İçerik haritası gezinmesi <nav aria-label="Breadcrumb">. Bir ekran okuyucu bu etiketi duyurur; gören okuyucular onu asla görmez. Altı tam dosya ve talimatlı çalıştırmanın hepsinde İngilizce kaldı, üstelik talimatlı istemde aria-label çevrilecek öznitelikler arasında listelenmişti. Bir talimatlı çalıştırmada arama düğmesinin aria-label="Search" değeri de İngilizce kaldı.

Segment yöntemi onu her seferinde çevirdi, çünkü betiği her aria-label, alt, title ve placeholder değerini topladı ve her birini açıkça istedi. Bu, modelin onları fark etmesini ummak yerine metin özniteliklerini bilerek çıkarmak için en güçlü argümandır.

3. Parçaları çevirmek etiketleri korudu ama cümleyi bozdu

Segment yöntemi, yapısı gereği işaretleme için güvenlidir: model hiçbir etiket görmez, bu yüzden bir etikete zarar veremez. Üç çalıştırmanın hepsinde tüm yapısal kontrolleri geçti. Ayrıca testte okuyucuya yanlış talimat veren tek çeviriyi üretti.

İngilizce cümle şudur: "Type the path to the <library> folder after --out." Satır içi <code> onu üç parçaya böler: "Type the path to the", "folder after" ve bir nokta. Çince bu kelimeleri farklı bir sıraya koyar, bu yüzden bir çevirmenin iki kod öğesini taşıması gerekir. Segment yöntemi onları taşıyamaz. Üç çalıştırmanın hepsi talimatı tersine çevirdi. 2. çalıştırma şunu üretti (1. ve 3. çalıştırmalar 之后 yerine aynı anlama gelen 后 der):

在 <code>&lt;library&gt;</code> 之后输入 <code>--out</code>文件夹的路径。

Bu, "--out klasörünün yolunu <library> sonrasında yazın" anlamına gelir, yani talimatın tersi. Altı tam dosya ve talimatlı çalıştırmanın hepsi kod öğelerini taşıdı ve doğru yaptı:

在 <code>--out</code> 后面输入 <code>&lt;library&gt;</code> 文件夹的路径。

Aynı bölme, üç segment çalıştırmasının hepsinde, çalıştırma başına altı yerde, bir etiketin Çince metinle buluştuğu yerlerde 前往 <b>设置</b> ve <b>书库</b> ， gibi başıboş boşluklar bıraktı. Bir tarayıcı bunları, Çince noktalama işaretlerinden öncekiler de dahil olmak üzere görünür boşluklar olarak gösterir. Tam dosya çalıştırmalarında hiç yoktu; talimatlı üç çalıştırmanın ikisinde dört veya beş vardı.

Yapısal bir denetleyici tersine dönmüş cümleyi yakalayamaz, çünkü her etiket tam olarak olması gereken yerdedir. Denetleyicimiz satır içi kodun sırası değiştiğinde uyarır, ki bu birçok dil için normaldir, ancak bu uyarı doğruyu yanlıştan ayırt edemez. Bu testte altı doğru çevirinin hepsinde tetiklendi ve üç yanlış çeviride sessiz kaldı, çünkü yanlış olanlar İngilizce sırayı korumuştu. Bunu ancak cümleyi okuyan bir kişi anlayabilir. Çözüm, satır içi etiketleriyle birlikte tam cümleleri çevirmene göndermektir, ki tam dosya çalıştırmaları bunu yaptı, ve ardından yapıyı kontrol etmektir.

Daha küçük farklar

• lang: tam dosya çalıştırmaları bunu kendiliğinden zh-CN olarak değiştirdi. Talimatlı çalıştırmalar istendiği gibi zh-Hans kullandı. Her ikisi de geçerli dil etiketleridir; zh-Hans betiği (Basitleştirilmiş Çince) adlandırır, zh-CN bir bölgeyi adlandırır. W3C'nin dil bildirimleri konusundaki rehberi, dilin <html> öğesinde bildirilmesini ve bir Content-Language meta etiketiyle bildirilmemesini önerir.
• JSON-LD: tam dosya ve talimatlı çalıştırmalar name ve description değerlerini çevirdi ve JSON'u geçerli tuttu. Segment betiğimiz <script> içeriğini atladı, bu yüzden yapılandırılmış verileri İngilizce kaldı; betikleri yok sayan bir araç da aynı şekilde davranır.
• Karakter referansları: tam dosya ve talimatlı çalıştırmalar ›,  , © ve emoji referansını yazıldığı gibi korudu. Bu altı çalıştırmanın beşi 2–5 aralığını Çince kelimelerle (2 到 5 veya 2 至 5) yeniden yazdı; bir talimatlı çalıştırma, istemi referansları korumasını söylemesine rağmen referans yerine düz bir tire yazdı. Segment betiğimiz hepsini çözüp karakterleri geri yazdı, ki bu aynı şekilde görüntülenir. Önemli olan, <code> içindeki <library>, dokuz çalıştırmanın hepsinde kaçışlı kaldı.

Çevirmeden Önce: Dosyayı Hazırlayın

1. Değişmemesi gerekenleri işaretleyin. Ürün adlarına, model numaralarına, düzyazı içindeki kod benzeri dizelere ve olduğu gibi kalması gereken her şeye translate="no" koyun. Bu HTML'in bir parçasıdır, hiçbir maliyeti yoktur ve model bunu tüm dosyayı gönderen altı çalıştırmanın hepsinde dikkate aldı. Bizim betiğimiz gibi bunu okuyan segment araçları bu öğeleri tamamen atlar. Çevrilmeyecekler rehberimiz bu listeye nelerin gireceğine nasıl karar vereceğinizi anlatır.
2. Kod politikasına karar verin. Kod yorumları çevrilecek mi? Örnek çıktı çevrilecek mi? Stil sayfası diller arasında paylaşılıyor mu? Cevabı, değişmemesi gereken adlarla birlikte bir çeviri sözlüğüne yazın ve çeviren kişiye veya araca verin.
3. Kimlikleri kaynak dilde tutun. Sayfa içi bağlantılar id değerlerine işaret eder. Biri bir id'yi çevirirse ona giden her bağlantı kırılır. Çalıştırmalarımızın hiçbiri bunu yapmadı, ama "yardımcı olmaya çalışan" bir çevirmen çapaları yerelleştirecektir.
4. Gizli metni toplayın. Kelime içeren öznitelikleri listeleyin: alt, title, placeholder, aria-label, düğmelerdeki value, meta etiketleri ve JSON-LD; böylece kontrol edilir ve unutulmazlar.
5. JavaScript dizelerini yerinde çevirmeyin. Bir betik tarafından ayarlanan mesajlar, örneğin bir uyarı veya kodda oluşturulan bir düğme etiketi, kodda ayrı bir yerelleştirme adımı gerektirir. Altı tam dosya veya talimatlı çalıştırmanın hiçbiri betik bloğumuzu değiştirmedi, ki bu doğrudur, ama bu o dizelerin İngilizce kalması anlamına gelir.

Çevirdikten Sonra: Kontrol Edin

1. Yapısal kontrolü çalıştırın.

   python3 check_html_translation.py source.html translated.html --lang zh-Hans --keep Shelfmark
   

   Etiketleri ve sıralarını, okuyucuya yönelik metin olmayan her özniteliği, <pre>, <script> ve <style> içeriklerini, satır içi kodu, JSON-LD anahtarlarını, translate="no" metnini, yorumları ve sayfa içi bağlantıları karşılaştırır. Hâlâ İngilizce olan metin öznitelikleri, beklediğinizden farklı bir lang değeri, çevrilmemiş gibi görünen görünür metin, sırası değişmiş satır içi kod ve bir satır içi etiket boyunca Çince, Japonca veya Korece metin arasındaki boşluklar hakkında uyarır. Çeviri kalitesini yargılamaz.

2. Satır içi etiket içeren her cümleyi okuyun. Testimizde anlamın bozulduğu yer burasıdır. Bu cümleleri bulmak için denetleyicinin "satır içi kod yeniden sıralandı" uyarısına güvenmeyin: testimizde yanlış çeviriler orijinal sırayı koruyanlardı.

3. Sayfayı bir tarayıcıda açın. Sayfa içi bağlantılara tıklayın, mümkünse bir ekran okuyucuyla formda sekmeler arasında gezinin ve kalın ve bağlantılı metinlerin etrafındaki boşlukları arayın.

4. Sağdan sola yazılan diller için ayrıca <html> öğesine dir="rtl" ayarlayın. RTL kitap çevirisi rehberimiz başka nelerin değiştiğini anlatır.

5. XHTML için, örneğin bir EPUB içindeki bölüm dosyaları için, dosyanın hâlâ iyi biçimlendirilmiş XML olduğunu da doğrulayın, örneğin xmllint --noout chapter.xhtml ile. Bir tarayıcı kapatılmamış bir etiketi affeder; bir e-kitap okuyucu affetmeyebilir. EPUB çeviri kalite kontrol listemiz bir e-kitabın geri kalanını kapsar.

BookTranslator Nerede Uygun

BookTranslator'ın yükleme sayfası, kitaplar ve belgelerin yanı sıra .html, .htm ve .xhtml dosyalarını da kabul eder; böylece kaydedilmiş bir sayfayı veya statik bir yardım makalesini tek bir dosya olarak yükleyebilirsiniz. Bu makale için bu örneği BookTranslator üzerinden çalıştırmadık ve satır içi kod sırasını, CSS içeriğini veya JSON-LD'yi nasıl işlediğini test etmedik; bu nedenle çıktısını başka herhangi bir aracın çıktısını kontrol eder gibi kontrol edin. Ödemeyi yapmadan önce fiyatı görürsünüz.

Neyi kullanırsanız kullanın, çeviriden önce hazırlık adımlarını, sonrasında ise kontrolleri yapın. Tüm etiketleri sağlam olan bir sayfa bile okuyucuya yanlış bir şey yazmasını söyleyebilir. HTML'iniz aslında Markdown ile yazılmış belgelerden oluşuyorsa, Markdown çeviri rehberimiz kaynak biçimini ele alır.

Test Dosyalarını Edinin

Bu testteki her şey yeniden kullanım için ücretsizdir:

• sample-source.html: 59 satırlık İngilizce örnek;
• check_html_translation.py: yapısal denetleyici (yalnızca Python standart kütüphanesi);
• run_llm_html_test.py: OpenAI uyumlu herhangi bir yerel sunucu için üç yöntem;
• outputs klasöründeki dokuz çıktı, check-results.txt ve results.csv ile birlikte.