Cara Menterjemah Fail Markdown Tanpa Merosakkan Kod, Pautan atau Front Matter

Untuk menterjemah fail Markdown, terjemah prosa dan biarkan bahagian mekanikal: kunci front matter, kod, URL, label pautan, tag komponen dan label nota kaki mesti kekal bait demi bait. Kemudian semak tiga perkara yang masih boleh rosak walaupun terjemahan dilakukan dengan teliti: pautan ke tajuk, komen kod, dan, dalam bahasa Cina, Jepun atau Korea, jarak di sekeliling teks tebal dan julat nombor.

Kami menterjemah halaman MDX 73 baris ke bahasa Cina Ringkas sembilan kali menggunakan model tempatan, dengan tiga gesaan berbeza, dan menyemak setiap hasil dengan skrip. Bahagian yang biasanya dibimbangkan kekal dalam kesemua sembilan jalan: kod, kod sebaris, URL, jadual, komponen JSX dan senarai tugasan. Tiga perkara lain berlaku masalah. Pautan ke tajuk rosak dalam kesemua sembilan jalan. Komen kod diterjemah dalam kesemua enam jalan yang menghantar keseluruhan fail, termasuk tiga jalan yang gesaannya menyatakan supaya tidak menyentuh kod. Dan gesaan yang menyembunyikan sintaks di sebalik pemegang tempat, yang kedengaran seperti pilihan paling selamat, merosakkan front matter dalam kesemua tiga jalannya.

Jawapan Pantas: Apa yang Perlu Diterjemah dan Apa yang Perlu Dibiarkan

Segala-galanya ialah prosa biasa: perenggan, item senarai, sel jadual, dan blok petikan.

Apa yang Kami Uji

Kami menulis sample-source.mdx, halaman dokumentasi untuk aplikasi bacaan fiksyen bernama Shelfmark. Ia ditulis dalam gaya MDX yang digunakan oleh Docusaurus dan tapak dokumentasi serupa, dengan satu contoh setiap konstruk dalam jadual di atas, serta pemisah baris keras dua ruang, pautan tebal, frasa tebal yang berakhir dengan kurungan, dua julat nombor yang ditulis dengan sengkang en, dan pautan dalam halaman ke pengepala "Kekalkan satu glosari untuk keseluruhan buku."

Kemudian kami meminta model tempatan menterjemahkannya ke bahasa Cina Ringkas dalam tiga cara:

1. Fail penuh. Tampal keseluruhan fail dan minta fail terjemahan dikembalikan.
2. Berarahan. Sama, tetapi dengan enam peraturan: kekalkan kunci front matter, jangan ubah apa-apa dalam kod, kekalkan URL dan definisi rujukan, kekalkan import, tag, dan komen, kekalkan label nota kaki dan penanda admonisi, dan terjemahkan pengepala, teks pautan, teks alt, dan atribut title.
3. Dilindungi. Gantikan kod, kod sebaris, URL, tag, komen, label nota kaki, penanda admonisi, dan baris front matter dengan pemegang tempat bernombor seperti ⟦12⟧, terjemahkan selebihnya, kemudian letakkan semula yang asal. Nilai title dan description dibiarkan terdedah untuk diterjemah, dan begitu juga, ternyata, baris --- front matter dan tanda petikan penutup.

Model tersebut ialah Qwen 3.6 27B (Q4_K_M) dalam LM Studio, dengan pemikiran dimatikan dan suhu 0.3, pada Apple M4 Max dengan memori 64 GB. Kami menjalankan setiap keadaan tiga kali, sembilan larian kesemuanya, pada 25 Oktober 2026. Skripnya ialah run_llm_markdown_test.py, dan kesemua sembilan output diterbitkan tanpa suntingan; README menyenaraikan setiap fail. Jika anda belum pernah menyediakan model tempatan, panduan terjemahan LLM tempatan kami merangkumi tetapan tersebut.

Ini ialah ujian kecil bagi satu model, satu pasangan bahasa, dan satu halaman. Ia menunjukkan masalah yang berlaku dan cara mengesannya. Ia tidak menyusun kedudukan model atau gesaan.

Keputusan: Sintaks Bertahan; Pautan dan Keputusan Tidak

Kami menyemak setiap output dengan check_markdown_translation.py dan memaparkan setiap satu dengan remark dan pengkompil MDX. Output penyemak penuh terdapat dalam check-results.txt, dan results.csv mempunyai satu baris setiap larian.

Baris pertama adalah berita baik. Model ini mengembalikan sintaks Markdown dengan utuh apabila kami menampal keseluruhan fail; kami tidak menemui apa-apa untuk dibetulkan dalam kod, URL, atau jadual. Empat baris terakhir adalah tempat kerja sebenar, dan tiada satu pun daripadanya muncul sebagai ralat apabila anda membina tapak.

1. Tajuk yang diterjemah memutuskan pautan kepadanya

Sampel itu memaut ke bahagian glosarinya dengan [glossary section](#keep-one-glossary-for-the-whole-book). Setiap larian menterjemah tajuk itu, seperti sepatutnya, dan setiap larian mengekalkan sasaran pautan, seperti sepatutnya. Hasilnya ialah pautan ke ID yang tidak lagi wujud.

Kebanyakan alat Markdown membina ID tajuk daripada teks tajuk. Dokumentasi Pandoc menerangkan pengecam sebagai "berdasarkan teks tajuk," dan Docusaurus memberi amaran bahawa anda mungkin mahu menukar atau menterjemah tajuk "tanpa mengemas kini ID sedia ada untuk mengelakkan pautan terputus." Sebaik sahaja tajuk itu berbunyi 为整本书保留一个术语表, ID yang dijana ialah bahasa Cina, dan #keep-one-glossary-for-the-whole-book tidak menatal ke mana-mana. Halaman itu masih dibina, jadi tiada apa yang memberitahu anda.

Anda juga tidak boleh membetulkannya dengan menyunting pautan selepas terjemahan. Merentas sembilan larian, model menulis tajuk yang sama dalam empat cara berbeza, jadi ID yang dijana akan berubah lagi dengan setiap terjemahan semula. Pembetulan itu perlu dilakukan sebelum terjemahan: berikan setiap tajuk yang dipautkan ID tetap.

• Dalam Docusaurus MDX, gunakan ## Keep one glossary for the whole book {/* #keep-one-glossary */}. Docusaurus menyatakan bahawa bentuk {#id} yang lebih lama "bukan lagi sintaks MDX yang sah," dan arahan write-heading-ids menambah ID pada setiap dokumen untuk anda.
• Dalam Pandoc dan dalam pemproses Markdown yang mengikut PHP Markdown Extra, gunakan {#keep-one-glossary} di hujung tajuk.

ID itu kemudiannya kekal sama dalam setiap bahasa, dan penyemak menganggapnya sebagai sasaran pautan.

2. Komen kod diterjemah, dan rentetan yang kelihatan tidak

Sampel itu mempunyai komen shell dan komen YAML:

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

Kesemua enam larian yang menghantar keseluruhan fail menterjemah kedua-dua komen, termasuk tiga larian yang promptnya berkata "Jangan ubah apa-apa di dalam blok kod berpagar." Kod itu sendiri tidak disentuh dalam kesemua sembilan larian. Sementara itu "My books", yang menurut komen itu dipaparkan di bar sisi, kekal dalam bahasa Inggeris dalam kesemua sembilan larian. Model melakukan perkara yang bertentangan dengan keperluan halaman setempat: ia menterjemah nota untuk pembangun dan membiarkan label yang akan dilihat pembaca.

Tiada pilihan yang salah dalam setiap kes. Untuk tutorial yang pembacanya akan menyalin kod ke dalam projek mereka sendiri, komen yang diterjemah membantu. Untuk dokumentasi rujukan yang kodnya mesti sepadan dengan repositori, komen itu membuat halaman tidak selaras dengan sumber. Buat keputusan sekali untuk projek itu, dan periksa nilai rentetan dalam contoh konfigurasi secara manual, kerana tiada alat boleh membezakan label paparan daripada pengecam. Atas sebab ini, penyemak melaporkan perubahan komen sahaja sebagai amaran.

3. Kaedah yang kelihatan selamat merosakkan front matter

Keadaan terlindung itu melakukan apa yang dijanjikannya: kesemua 32 pemegang tempat kembali dalam ketiga-tiga larian, jadi kod, URL, dan tag dipulihkan dengan sempurna. Tetapi skrip kami meninggalkan dua perkara kecil di luar pemegang tempat: baris --- yang membuka front matter, dan tanda petikan penutup selepas tajuk dan penerangan yang diterjemah. Model menggugurkan kesemuanya dalam ketiga-tiga larian. Fail itu bermula seperti ini:

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

Tanpa --- pembuka, penghurai Markdown tidak lagi melihat front matter. Ia membaca enam baris YAML serta --- penutup sebagai tajuk, jadi halaman itu akan dibuka dengan tajuk besar yang mengandungi YAML. Ia masih dikompil sebagai MDX. Meletakkan semula --- juga tidak mencukupi: penghurai YAML menolak dua petikan yang tidak ditutup.

Pengajarannya bukanlah untuk mengelakkan pemegang tempat. Ia adalah bahawa apa sahaja yang anda biarkan terdedah mungkin kembali berubah, dan front matter tidak sepatutnya dihantar kepada model sebagai sebahagian daripada halaman sama sekali. Huraikannya, hantar hanya nilai yang menghadap pembaca (title, description) sebagai rentetan berasingan, dan tulis terjemahan kembali ke dalam struktur asal. Itu hanya beberapa baris kod dan menghapuskan seluruh kelas masalah.

Teks Tebal dan Julat dalam Bahasa Cina, Jepun, dan Korea

Dua lagi masalah tidak pernah muncul dalam sembilan larian kami, tetapi ia wajar diperiksa kerana ia memecahkan halaman secara senyap, dan kedua-duanya pernah melanda blog BookTranslator sendiri. Blog itu ditulis dalam MDX dan diterjemah secara mesin ke dalam 27 bahasa, dan dalam satu larian terjemahan berjadual dua artikel Korea gagal semakan struktur kami tiga percubaan berturut-turut. Puncanya ialah dua corak di bawah.

Tebal yang berakhir dengan tanda baca. CommonMark menentukan sama ada ** boleh membuka atau menutup tebal dengan melihat aksara di kedua-dua belahnya. ** penutup yang datang terus selepas tanda baca mesti diikuti oleh ruang, tanda baca, atau penghujung baris; ini ialah peraturan sayap kanan. Bahasa Inggeris sentiasa mempunyai ruang di situ. Bahasa Cina, Jepun, dan Korea selalunya tidak. Jadi 打开**设置 → 导出（测试版）**并选择 memaparkan asterisk literal, kerana tebal itu berakhir dengan kurungan penuh dan diikuti terus oleh 并. Baris yang sama tanpa kurungan itu dipaparkan sebagai tebal, begitu juga baris dengan ruang selepas **. Pautan tebal mempunyai masalah yang sama, kerana pautan berakhir dengan ): 点击**[导出](./export-options.md)**打开 gagal, begitu juga dengan bahasa Korea **[API](./api.md)**는.

Model kami kebetulan meletakkan ruang pada kedua-dua belah setiap frasa tebal, jadi outputnya dipaparkan dengan betul. Editor yang kemudiannya membuang ruang tersebut untuk mengikut konvensyen tipografi Cina akan mengembalikan pepijat itu. Anda boleh mencuba ketujuh-tujuh varian dalam render-cases.md.

Julat nombor dengan tilde. Teks Cina dan Jepun sering menulis julat sebagai 3~5. Laman GitHub Flavored Markdown yang dibina atas remark menukar tilde tunggal menjadi coretan secara lalai: pilihan remark-gfm singleTilde ialah true melainkan anda mengubahnya. Dua julat dalam satu perenggan, seperti 需要 3~5 分钟，生成 10~20 MB 的文件夹, dipaparkan dengan teks di antaranya dicoret. Sampel kami menggunakan sengkang en, dan lapan larian mengekalkannya manakala larian kesembilan menulis 3 到 5. Minta sengkang en atau perkataan dalam julat, atau tetapkan singleTilde: false dalam konfigurasi remark anda.

Pemeriksa struktur menandakan kedua-dua corak. Untuk mengesahkan apa yang sebenarnya dipaparkan, render_check.mjs mengira tebal, italik, coretan, dan asterisk yang tertinggal dalam sumber dan terjemahan, dan mencuba kompilasi MDX:

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

Nod tebal yang lebih sedikit atau asterisk literal yang lebih banyak dalam terjemahan bermakna beberapa penekanan berhenti menutup.

Aliran Kerja yang Tahan Lasak

1. Betulkan ID tajuk dahulu. Tambah ID eksplisit pada setiap tajuk yang dipautkan oleh sesuatu, dalam sintaks yang disokong oleh penjana laman anda. Lakukan dalam bahasa sumber, sekali, dan komit sebelum apa-apa diterjemahkan.

2. Keluarkan front matter daripada halaman. Terjemah hanya nilai yang menghadap pembaca seperti title dan description, sebagai rentetan berasingan, dan tulis semula ke dalam YAML asal.

3. Tentukan dasar kod. Komen diterjemah atau tidak; rentetan paparan dalam contoh konfigurasi diterjemah atau tidak. Tuliskan dalam glosari terjemahan anda bersebelahan dengan nama produk yang tidak boleh berubah, seperti Shelfmark dalam sampel kami.

4. Terjemah badan. Gunakan alat yang menghuraikan Markdown, atau hantar keseluruhan halaman dengan peraturan eksplisit. Dalam ujian kami, menghantar keseluruhan halaman mengekalkan sintaks; jika anda menggunakan pemegang tempat, lindungi konstruk lengkap dan jangan biarkan apa-apa terdedah separuh.

5. Jalankan pemeriksaan struktur.

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

   Ia membandingkan kunci dan nilai front matter, import, blok kod, kod sebaris, sasaran pautan, definisi rujukan, tahap tajuk, sasaran pautan dalam halaman, tag dan atribut JSX, komen MDX, penanda admonisi, label nota kaki, bentuk jadual, kotak senarai tugas, pemisah baris keras, penekanan yang tidak boleh menutup, julat tilde, dan istilah yang anda minta untuk dikekalkan. Ia tidak menilai kualiti terjemahan.

6. Periksa paparan untuk sasaran CJK dengan render_check.mjs, dan tambah ruang selepas mana-mana ** penutup yang mengikuti tanda baca.

7. Bina laman dan klik pautan. Buka halaman dalam setiap bahasa, klik setiap pautan dalam halaman, dan baca contoh konfigurasi. Pembinaan yang berjaya hanya membuktikan bahawa fail itu dikompil.

Untuk dokumentasi yang mementingkan ketepatan, langkah terminologi dan semakan dalam aliran kerja terjemahan teknikal kami terpakai di atas ini.

Kedudukan BookTranslator

Penterjemah TXT BookTranslator menerima fail .txt, .md, dan .mdx. Menurut halaman produk, ia menterjemahkannya sambil mengekalkan perenggan, pemisah baris, aksara khas, dan struktur teks, dan ia memecahkan fail besar kepada segmen untuk terjemahan sedar konteks, jadi anda boleh memuat naik keseluruhan manual atau buku yang ditulis dalam Markdown daripada menampalnya sedikit demi sedikit.

Halaman produk tidak menerangkan pengendalian khas untuk front matter, blok kod, atau komponen MDX, dan kami tidak menjalankan sampel ini melalui BookTranslator untuk artikel ini. Walau apa pun alat yang anda gunakan, lakukan langkah 1 hingga 3 sebelum menterjemah dan langkah 5 hingga 7 selepasnya. Tajuk tanpa ID tetap kehilangan pautannya, dan julat yang ditulis dengan tilde tetap bertukar menjadi coretan. Jika anda menerbitkan buku dalam beberapa bahasa, panduan kami untuk menerbitkan sendiri dalam pelbagai bahasa merangkumi selebihnya tugas itu.

Dapatkan Fail Ujian

Semua daripada ujian ini bebas untuk digunakan semula:

• sample-source.mdx: sampel bahasa Inggeris 73 baris;
• check_markdown_translation.py: pemeriksa struktur (hanya pustaka standard Python);
• render_check.mjs dan render-cases.md: pemeriksaan paparan dan tujuh kes ujian CJK;
• run_llm_markdown_test.py: tiga syarat gesaan untuk mana-mana pelayan tempatan serasi OpenAI;
• sembilan output dalam folder output, bersama check-results.txt dan results.csv.