Kod, Bağlantı veya Ön Bilgiyi Bozmadan Markdown Dosyaları Nasıl Çevrilir

Bir Markdown dosyasını çevirmek için düz metni çevirin ve teknik yapıyı olduğu gibi bırakın: ön bilgi anahtarları, kod, URL'ler, bağlantı etiketleri, bileşen etiketleri ve dipnot etiketleri bayt bayt aynı şekilde geri gelmelidir. Ardından, dikkatli bir çevirinin bile bozabileceği üç şeyi kontrol edin: başlıklara verilen bağlantılar, kod yorumları ve Çince, Japonca veya Korece'de kalın metin ile sayı aralıklarının etrafındaki boşluklar.

73 satırlık bir MDX sayfasını yerel bir modelle dokuz kez Basitleştirilmiş Çince'ye çevirdik, üç farklı istem kullandık ve her sonucu bir betikle kontrol ettik. İnsanların genellikle endişelendiği kısımlar dokuz çalıştırmanın tamamında korundu: kod, satır içi kod, URL'ler, tablo, JSX bileşeni ve görev listesi. Ancak üç başka şey ters gitti. Bir başlığa verilen bağlantı dokuz çalıştırmanın tamamında bozuldu. Kod yorumları, tüm dosyayı gönderen altı çalıştırmanın tamamında çevrildi; buna kodla oynamayın denilen üç çalıştırma da dahildi. Sözdizimini yer tutucuların arkasına saklayan ve en güvenli seçenek gibi görünen istem ise üç çalıştırmasının tamamında ön bilgiyi bozdu.

Hızlı Yanıt: Neyi Çevirmeli, Neyi Olduğu Gibi Bırakmalı

Geri kalan her şey sıradan metindir: paragraflar, liste öğeleri, tablo hücreleri ve alıntı blokları.

Neyi Test Ettik

Shelfmark adında kurgusal bir okuma uygulaması için bir dokümantasyon sayfası olan sample-source.mdx dosyasını yazdık. Docusaurus ve benzer dokümantasyon sitelerinin kullandığı MDX stilinde yazılmış olup yukarıdaki tablodaki her yapıdan bir örnek, ayrıca iki boşluklu sert satır sonu, kalın bir bağlantı, parantezle biten kalın bir ifade, kısa çizgiyle yazılmış iki sayı aralığı ve "Keep one glossary for the whole book." başlığına sayfa içi bir bağlantı içerir.

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

1. Tüm dosya. Dosyanın tamamını yapıştırın ve çevrilmiş dosyayı geri isteyin.
2. Talimatlı. Aynısı, artı altı kural: ön bilgi anahtarlarını koru, kod içinde hiçbir şeyi değiştirme, URL'leri ve referans tanımlarını koru, içe aktarımları, etiketleri ve yorumları koru, dipnot etiketlerini ve uyarı işaretlerini koru ve başlıkları, bağlantı metnini, alternatif metni ve title özniteliğini çevir.
3. Korumalı. Kodu, satır içi kodu, URL'leri, etiketleri, yorumları, dipnot etiketlerini, uyarı işaretlerini ve ön bilgi satırlarını ⟦12⟧ gibi numaralı yer tutucularla değiştirin, geri kalanını çevirin, sonra orijinalleri geri koyun. title ve description değerleri çeviri için açıkta bırakıldı ve ortaya çıktığı üzere ön bilginin --- satırları ile kapanış tırnak işaretleri de açıkta kaldı.

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 koşulu üç kez, toplamda dokuz kez, 25 Ekim 2026'da çalıştırdık. Betik run_llm_markdown_test.py ve dokuz çıktının tamamı düzenlenmeden yayımlandı; README her dosyayı listeler. Daha önce hiç yerel 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ın nasıl yakalanacağını gösterir. Modelleri veya istemleri sıralamaz.

Sonuç: Sözdizimi Hayatta Kaldı; Bağlantılar ve Kararlar Kalmadı

Her çıktıyı check_markdown_translation.py ile kontrol ettik ve her birini remark ve MDX derleyicisiyle işledik. Denetleyicinin tam çıktısı check-results.txt dosyasında ve results.csv her çalıştırma için bir satır içerir.

İlk satırlar iyi haber. Bu model tüm dosyayı yapıştırdığımızda Markdown sözdizimini bozulmadan geri döndürdü; kod, URL'ler veya tablolarda düzeltilecek bir şey bulamadık. Son dört satır asıl işin olduğu yer ve hiçbiri siteyi oluşturduğunuzda hata olarak görünmüyor.

1. Çevrilen başlıklar onlara giden bağlantıları bozar

Örnek, sözlük bölümüne [glossary section](#keep-one-glossary-for-the-whole-book) ile bağlantı veriyor. Her çalıştırma başlığı olması gerektiği gibi çevirdi ve her çalıştırma bağlantı hedefini olması gerektiği gibi korudu. Sonuç, artık var olmayan bir ID'ye giden bir bağlantı.

Çoğu Markdown aracı başlık kimliklerini başlık metninden oluşturur. Pandoc'un belgeleri tanımlayıcıyı "başlık metnine dayalı" olarak açıklar ve Docusaurus uyarır ki "bağlantıları bozmamak için mevcut ID'yi güncellemeden" bir başlığı değiştirmek veya çevirmek isteyebilirsiniz. Başlık 为整本书保留一个术语表 olarak okunduğunda, oluşturulan ID'si Çince olur ve #keep-one-glossary-for-the-whole-book hiçbir yere kaydırmaz. Sayfa hâlâ oluşturulur, bu yüzden size hiçbir şey söylemez.

Bunu çeviriden sonra bağlantıyı düzenleyerek de düzeltemezsiniz. Dokuz çalıştırma boyunca model aynı başlığı dört farklı şekilde yazdı, bu yüzden oluşturulan ID her yeniden çeviride tekrar değişirdi. Düzeltme çeviriden önce yapılmalıdır: bağlantı verilen her başlığa sabit bir ID verin.

• Docusaurus MDX'te ## Keep one glossary for the whole book {/* #keep-one-glossary */} kullanın. Docusaurus, eski {#id} biçiminin "artık geçerli MDX sözdizimi olmadığını" belirtir ve write-heading-ids komutu sizin için her belgeye ID ekler.
• Pandoc'ta ve PHP Markdown Extra'yı takip eden Markdown işlemcilerinde, başlığın sonunda {#keep-one-glossary} kullanın.

Böylece ID her dilde aynı kalır ve denetleyici onu bağlantı hedefi olarak kabul eder.

2. Kod yorumları çevrilir ve görünen dize çevrilmez

Örnekte bir shell yorumu ve bir YAML yorumu var:

library:
  name: "My books"   # shown in the sidebar
  sort: title

Tüm dosyayı gönderen altı çalıştırmanın hepsi her iki yorumu da çevirdi; istemin "Kapalı kod bloklarının içindeki hiçbir şeyi değiştirmeyin" dediği üç çalıştırma dahil. Kodun kendisi dokuz çalıştırmanın hepsinde dokunulmadan kaldı. Bu arada, yorumun kenar çubuğunda gösterildiğini söylediği "My books" dokuz çalıştırmanın hepsinde İngilizce kaldı. Model, yerelleştirilmiş bir sayfanın ihtiyaç duyduğunun tam tersini yaptı: geliştiriciler için notu çevirdi ve okuyucuların göreceği etiketi bıraktı.

Her iki seçim de her durumda yanlış değildir. Okuyucuların kodu kendi projelerine kopyalayacağı bir eğitim için çevrilmiş yorumlar yardımcı olur. Kodun bir depoyla eşleşmesi gereken referans belgeleri için sayfayı kaynakla uyumsuz hale getirirler. Kararı proje için bir kez verin ve yapılandırma örneklerindeki dize değerlerine elle bakın, çünkü hiçbir araç bir görüntü etiketini tanımlayıcıdan ayırt edemez. Denetleyici bu nedenle yalnızca yorum değişikliklerini uyarı olarak bildirir.

3. Güvenli görünen yöntem ön bilgiyi bozdu

Korumalı koşul sözünü tuttu: 32 yer tutucunun tamamı üç çalıştırmanın hepsinde geri geldi, böylece kod, URL'ler ve etiketler mükemmel şekilde geri yüklendi. Ancak betiğimiz yer tutucuların dışında iki küçük şey bıraktı: ön bilgiyi açan --- satırı ve çevrilmiş başlık ile açıklamadan sonraki kapanış tırnak işareti. Model bunların hepsini üç çalıştırmanın hepsinde düşürdü. Dosya şöyle başlıyordu:

title: "导出您的书库
description: "在更换设备之前，请备份您的笔记和书籍。
slug: export-library

Açılış --- olmadan, bir Markdown ayrıştırıcısı artık ön bilgiyi görmez. Altı YAML satırını ve kapanış --- satırını bir başlık olarak okur, böylece sayfa YAML içeren büyük bir başlıkla açılır. Yine de MDX olarak derlendi. --- satırını geri koymak da yeterli değildir: YAML ayrıştırıcısı kapatılmamış iki tırnağı reddeder.

Ders, yer tutuculardan kaçınmak değildir. Açıkta bıraktığınız her şey değişmiş olarak geri gelebilir ve ön bilgi sayfanın bir parçası olarak modele hiç gönderilmemelidir. Bunu ayrıştırın, yalnızca okuyucuya yönelik değerleri (title, description) ayrı dizeler olarak gönderin ve çevirileri orijinal yapıya geri yazın. Bu birkaç satır koddur ve tüm sorun sınıfını ortadan kaldırır.

Çince, Japonca ve Korecede Kalın Metin ve Aralıklar

Dokuz çalıştırmamızda iki sorun daha hiç görünmedi, ancak sayfaları sessizce bozdukları için kontrol etmeye değer ve her ikisi de BookTranslator'ın kendi blogunu vurdu. Blog MDX ile yazılmış ve 27 dile makineyle çevrilmiş ve planlanmış bir çeviri çalıştırmasında iki Korece makale yapı denetimimizde üst üste üç yeniden denemede başarısız oldu. Nedenler aşağıdaki iki kalıptı.

Noktalama işaretiyle biten kalın yazı. CommonMark, ** işaretinin kalın yazıyı açıp kapatamayacağına, işaretin her iki yanındaki karakterlere bakarak karar verir. Noktalama işaretinden hemen sonra gelen bir kapanış ** işaretini bir boşluk, noktalama işareti veya satır sonu takip etmelidir; bu, sağa yaslanma kuralı olarak bilinir. İngilizcede burada her zaman bir boşluk vardır. Çince, Japonca ve Korecede ise genellikle yoktur. Bu nedenle 打开**设置 → 导出（测试版）**并选择 ifadesi, kalın yazı tam genişlikte bir parantezle bitip hemen ardından 并 geldiği için düz yıldız işaretleri olarak görünür. Parantez olmadan aynı satır kalın olarak işlenir ve ** işaretinden sonra boşluk olan satır da öyle. Kalın bir bağlantı da aynı sorunu yaşar, çünkü bağlantı ) ile biter: 点击**[导出](./export-options.md)**打开 başarısız olur ve Korece **[API](./api.md)**는 de öyle.

Modelimiz her kalın ifadenin her iki yanına birer boşluk koydu, bu yüzden çıktısı doğru şekilde işlendi. Daha sonra Çince dizgi kurallarına uymak için bu boşlukları kaldıran bir editör hatayı geri getirir. Yedi varyantın tümünü render-cases.md dosyasında deneyebilirsiniz.

Tilde ile sayı aralıkları. Çince ve Japonca metinlerde aralıklar sıklıkla 3~5 şeklinde yazılır. remark üzerine kurulu GitHub Flavored Markdown siteleri, varsayılan olarak tek tildeleri üstü çizili metne dönüştürür: remark-gfm seçeneği singleTilde, siz değiştirmediğiniz sürece true değerindedir. Bir paragrafta iki aralık, örneğin 需要 3~5 分钟，生成 10~20 MB 的文件夹, aralarındaki metin üstü çizili olarak işlenir. Örneğimizde en dash kullanıldı ve sekiz çalıştırma bunları korurken dokuzuncusu 3 到 5 yazdı. Aralıklarda en dash veya kelime kullanılmasını isteyin ya da remark yapılandırmanızda singleTilde: false ayarlayın.

Yapısal denetleyici her iki deseni de işaretler. Gerçekte neyin işlendiğini doğrulamak için render_check.mjs, kaynakta ve çeviride kalın, italik, üstü çizili ve kalan yıldız işaretlerini sayar ve bir MDX derlemesi dener:

npm install @mdx-js/mdx@3 unified@11 remark-parse@11 remark-gfm@4
node render_check.mjs source.mdx translated.mdx

Çeviride daha az kalın düğüm veya daha fazla düz yıldız işareti, bazı vurguların kapanmayı bıraktığı anlamına gelir.

Sağlam Bir İş Akışı

1. Önce başlık kimliklerini düzeltin. Bir şeyin bağlantı verdiği her başlığa, site oluşturucunuzun desteklediği sözdizimiyle açık kimlikler ekleyin. Bunu kaynak dilde bir kez yapın ve herhangi bir çeviri yapılmadan önce işleyin.

2. Ön bilgiyi sayfadan çıkarın. Yalnızca title ve description gibi okuyucuya yönelik değerleri ayrı dizeler olarak çevirin ve bunları orijinal YAML'a geri yazın.

3. Kod politikasını belirleyin. Yorumlar çevrilsin mi, çevrilmesin mi; yapılandırma örneklerindeki görünen dizeler çevrilsin mi, çevrilmesin mi. Bunu, örneğimizdeki Shelfmark gibi değişmemesi gereken ürün adlarının yanına çeviri sözlüğünüze yazın.

4. Gövdeyi çevirin. Markdown'u ayrıştıran bir araç kullanın veya tüm sayfayı açık kurallarla gönderin. Testimizde, tüm sayfayı göndermek sözdizimini bozulmadan korudu; yer tutucular kullanıyorsanız, tam yapıları koruyun ve yarım açıkta hiçbir şey bırakmayın.

5. Yapısal denetimi çalıştırın.

   python3 check_markdown_translation.py source.mdx translated.mdx --keep Shelfmark
   

   Ön bilgi anahtarlarını ve değerlerini, içe aktarımları, kod bloklarını, satır içi kodu, bağlantı hedeflerini, referans tanımlarını, başlık düzeylerini, sayfa içi bağlantı hedeflerini, JSX etiketlerini ve özniteliklerini, MDX yorumlarını, uyarı işaretlerini, dipnot etiketlerini, tablo şeklini, görev listesi kutularını, sabit satır sonlarını, kapanamayan vurguları, tilde aralıklarını ve korunmasını istediğiniz terimleri karşılaştırır. Çeviri kalitesini yargılamaz.

6. CJK hedefleri için işlemeyi render_check.mjs ile kontrol edin ve noktalama işaretinden sonra gelen her kapanış ** işaretinden sonra bir boşluk ekleyin.

7. Siteyi oluşturun ve bağlantılara tıklayın. Sayfayı her dilde açın, sayfa içi her bağlantıya tıklayın ve yapılandırma örneklerini okuyun. Başarılı bir derleme yalnızca dosyanın derlendiğini kanıtlar.

Doğruluğun önemli olduğu belgeler için teknik çeviri iş akışımızdaki terminoloji ve inceleme adımları bunun üzerine uygulanır.

BookTranslator Nerede Devreye Girer

BookTranslator'ın TXT çevirmeni .txt, .md ve .mdx dosyalarını kabul eder. Ürün sayfasına göre, paragrafları, satır sonlarını, özel karakterleri ve metin yapısını koruyarak çevirir ve büyük dosyaları bağlam duyarlı çeviri için parçalara ayırır; böylece parça parça yapıştırmak yerine Markdown ile yazılmış bir kılavuzun veya kitabın tamamını yükleyebilirsiniz.

Ürün sayfası, ön bilgi, kod blokları veya MDX bileşenleri için özel bir işleme açıklamaz ve bu makale için bu örneği BookTranslator üzerinden çalıştırmadık. Hangi aracı kullanırsanız kullanın, çeviriden önce 1. ila 3. adımları, sonrasında ise 5. ila 7. adımları uygulayın. Sabit kimliği olmayan bir başlık yine bağlantılarını kaybeder ve tilde ile yazılan bir aralık yine üstü çizili metne dönüşür. Bir kitabı birkaç dilde yayımlıyorsanız, birden çok dilde kendi kendine yayımlama rehberimiz bu işin geri kalanını kapsar.

Test Dosyalarını Edinin

Bu testteki her şey ücretsiz olarak yeniden kullanılabilir:

• sample-source.mdx: 73 satırlık İngilizce örnek;
• check_markdown_translation.py: yapısal denetleyici (yalnızca Python standart kütüphanesi);
• render_check.mjs ve render-cases.md: işleme denetimi ve yedi CJK test durumu;
• run_llm_markdown_test.py: OpenAI uyumlu herhangi bir yerel sunucu için üç istem koşulu;
• outputs klasöründeki dokuz çıktı, check-results.txt ve results.csv ile birlikte.