Cara Menerjemahkan File Markdown Tanpa Merusak Kode, Tautan, atau Front Matter

Untuk menerjemahkan file Markdown, terjemahkan prosa dan biarkan bagian teknisnya: kunci front matter, kode, URL, label tautan, tag komponen, dan label catatan kaki harus kembali persis sama. Lalu periksa tiga hal yang masih bisa rusak meski terjemahannya cermat: tautan ke judul, komentar kode, dan, dalam bahasa Tionghoa, Jepang, atau Korea, spasi di sekitar teks tebal dan rentang angka.

Kami menerjemahkan halaman MDX 73 baris ke bahasa Tionghoa Sederhana sembilan kali dengan model lokal, menggunakan tiga prompt berbeda, dan memeriksa setiap hasil dengan skrip. Bagian yang biasanya dikhawatirkan tetap utuh di kesembilan percobaan: kode, kode inline, URL, tabel, komponen JSX, dan daftar tugas. Tiga hal lain bermasalah. Tautan ke judul rusak di kesembilan percobaan. Komentar kode diterjemahkan di keenam percobaan yang mengirim seluruh file, termasuk tiga percobaan yang prompt-nya melarang menyentuh kode. Dan prompt yang menyembunyikan sintaks di balik placeholder, yang terdengar seperti opsi paling aman, merusak front matter di ketiga percobaannya.

Jawaban Singkat: Apa yang Diterjemahkan dan Apa yang Dibiarkan

Segala hal lainnya adalah prosa biasa: paragraf, item daftar, sel tabel, dan kutipan blok.

Apa yang Kami Uji

Kami menulis sample-source.mdx, sebuah halaman dokumentasi untuk aplikasi membaca fiktif bernama Shelfmark. Halaman ini ditulis dalam gaya MDX yang digunakan oleh Docusaurus dan situs dokumentasi serupa, dengan satu contoh dari setiap konstruksi dalam tabel di atas, ditambah jeda baris keras dua spasi, tautan tebal, frasa tebal yang diakhiri dengan tanda kurung, dua rentang angka yang ditulis dengan tanda pisah en, dan tautan dalam halaman ke judul "Pertahankan satu glosarium untuk seluruh buku."

Kemudian kami meminta model lokal untuk menerjemahkannya ke bahasa Mandarin Sederhana dengan tiga cara:

1. Seluruh file. Tempel seluruh file dan minta file terjemahan kembali.
2. Dengan instruksi. Sama, ditambah enam aturan: pertahankan kunci front matter, jangan ubah apa pun di dalam kode, pertahankan URL dan definisi referensi, pertahankan impor, tag, dan komentar, pertahankan label catatan kaki dan penanda admonisi, serta terjemahkan judul, teks tautan, teks alt, dan atribut title.
3. Dengan perlindungan. Ganti kode, kode inline, URL, tag, komentar, label catatan kaki, penanda admonisi, dan baris front matter dengan placeholder bernomor seperti ⟦12⟧, terjemahkan sisanya, lalu kembalikan yang asli. Nilai title dan description dibiarkan terbuka untuk diterjemahkan, dan ternyata begitu juga baris --- front matter serta tanda kutip penutup.

Model yang digunakan adalah Qwen 3.6 27B (Q4_K_M) di LM Studio, dengan mode berpikir dimatikan dan temperature 0,3, pada Apple M4 Max dengan memori 64 GB. Kami menjalankan setiap kondisi tiga kali, total sembilan kali, pada 25 Oktober 2026. Skripnya adalah run_llm_markdown_test.py, dan kesembilan output dipublikasikan tanpa diedit; README mencantumkan setiap file. Jika Anda belum pernah menyiapkan model lokal, panduan terjemahan LLM lokal kami mencakup pengaturannya.

Ini adalah uji kecil dengan satu model, satu pasangan bahasa, dan satu halaman. Ini menunjukkan masalah apa yang terjadi dan bagaimana menangkapnya. Ini tidak memeringkat model atau prompt.

Hasil: Sintaksis Bertahan; Tautan dan Keputusan Tidak

Kami memeriksa setiap output dengan check_markdown_translation.py dan merender masing-masing dengan remark dan kompiler MDX. Output pemeriksa lengkap ada di check-results.txt, dan results.csv memiliki satu baris per eksekusi.

Baris-baris pertama adalah kabar baik. Model ini mengembalikan sintaks Markdown dengan utuh saat kami menempelkan seluruh file; kami tidak menemukan apa pun untuk diperbaiki pada kode, URL, atau tabel. Empat baris terakhir adalah bagian yang perlu dikerjakan, dan tidak satu pun dari itu muncul sebagai error saat Anda membangun situs.

1. Judul yang diterjemahkan merusak tautan ke judul tersebut

Sampel menautkan ke bagian glosariumnya dengan [glossary section](#keep-one-glossary-for-the-whole-book). Setiap percobaan menerjemahkan judul, sebagaimana mestinya, dan setiap percobaan mempertahankan target tautan, sebagaimana mestinya. Hasilnya adalah tautan ke ID yang sudah tidak ada.

Sebagian besar alat Markdown membangun ID judul dari teks judul. Dokumentasi Pandoc menjelaskan bahwa pengenal tersebut "berdasarkan teks judul," dan Docusaurus memperingatkan bahwa Anda mungkin ingin mengubah atau menerjemahkan judul "tanpa memperbarui ID yang ada agar tidak merusak tautan." Begitu judulnya berbunyi 为整本书保留一个术语表, ID yang dihasilkan menjadi bahasa Mandarin, dan #keep-one-glossary-for-the-whole-book tidak menggulir ke mana pun. Halaman tetap terbangun, jadi tidak ada yang memberi tahu Anda.

Anda juga tidak dapat memperbaiki ini dengan mengedit tautan setelah terjemahan. Dalam sembilan percobaan, model menulis judul yang sama dengan empat cara berbeda, sehingga ID yang dihasilkan akan berubah lagi pada setiap penerjemahan ulang. Perbaikannya harus dilakukan sebelum penerjemahan: berikan ID tetap pada setiap judul yang ditautkan.

• Dalam MDX Docusaurus, gunakan ## Keep one glossary for the whole book {/* #keep-one-glossary */}. Docusaurus mencatat bahwa bentuk {#id} yang lebih lama "bukan lagi sintaks MDX yang valid," dan perintah write-heading-ids miliknya menambahkan ID ke setiap dokumen untuk Anda.
• Dalam Pandoc dan pemroses Markdown yang mengikuti PHP Markdown Extra, gunakan {#keep-one-glossary} di akhir judul.

ID tersebut kemudian tetap sama dalam setiap bahasa, dan pemeriksa memperlakukannya sebagai target tautan.

2. Komentar kode diterjemahkan, dan string yang terlihat tidak

Sampel memiliki komentar shell dan komentar YAML:

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

Keenam percobaan yang mengirim seluruh file menerjemahkan kedua komentar, termasuk tiga percobaan di mana prompt mengatakan "Jangan ubah apa pun di dalam blok kode berpagar." Kode itu sendiri tidak tersentuh di kesembilan percobaan. Sementara itu "My books", yang menurut komentar ditampilkan di sidebar, tetap dalam bahasa Inggris di kesembilan percobaan. Model melakukan kebalikan dari yang dibutuhkan halaman terlokalisasi: ia menerjemahkan catatan untuk pengembang dan membiarkan label yang akan dilihat pembaca.

Tidak ada pilihan yang salah dalam setiap kasus. Untuk tutorial yang pembacanya akan menyalin kode ke proyek mereka sendiri, komentar yang diterjemahkan membantu. Untuk dokumentasi referensi yang kodenya harus cocok dengan repositori, komentar tersebut membuat halaman tidak sesuai dengan sumbernya. Buat keputusan sekali untuk proyek, dan periksa nilai string dalam contoh konfigurasi secara manual, karena tidak ada alat yang dapat membedakan label tampilan dari pengenal. Pemeriksa melaporkan perubahan hanya-komentar sebagai peringatan karena alasan ini.

3. Metode yang tampak aman merusak front matter

Kondisi terlindungi melakukan apa yang dijanjikannya: semua 32 placeholder kembali dalam ketiga percobaan, sehingga kode, URL, dan tag dipulihkan dengan sempurna. Tetapi skrip kami meninggalkan dua hal kecil di luar placeholder: baris --- yang membuka front matter, dan tanda kutip penutup setelah judul dan deskripsi yang diterjemahkan. Model menghilangkan semuanya dalam ketiga percobaan. File dimulai seperti ini:

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

Tanpa --- pembuka, parser Markdown tidak lagi melihat front matter. Ia membaca enam baris YAML plus --- penutup sebagai judul, sehingga halaman akan dibuka dengan judul besar yang berisi YAML. File itu tetap dikompilasi sebagai MDX. Mengembalikan --- juga tidak cukup: parser YAML menolak dua tanda kutip yang tidak ditutup.

Pelajaran yang diambil bukanlah menghindari placeholder. Melainkan bahwa apa pun yang Anda biarkan terbuka mungkin kembali dalam keadaan berubah, dan front matter seharusnya tidak dikirim ke model sebagai bagian dari halaman sama sekali. Parsing-lah, kirim hanya nilai yang menghadap pembaca (title, description) sebagai string terpisah, dan tulis terjemahannya kembali ke struktur asli. Itu hanya beberapa baris kode dan menghilangkan seluruh kelas masalah.

Teks Tebal dan Rentang dalam Bahasa Mandarin, Jepang, dan Korea

Dua masalah lagi tidak pernah muncul dalam sembilan percobaan kami, tetapi patut diperiksa karena keduanya merusak halaman secara diam-diam, dan keduanya pernah menimpa blog BookTranslator sendiri. Blog tersebut ditulis dalam MDX dan diterjemahkan secara mesin ke 27 bahasa, dan dalam satu proses penerjemahan terjadwal dua artikel Korea gagal dalam pemeriksaan struktur kami tiga kali percobaan ulang berturut-turut. Penyebabnya adalah dua pola di bawah ini.

Tebal yang diakhiri tanda baca. CommonMark menentukan apakah ** dapat membuka atau menutup tebal dengan melihat karakter di kedua sisinya. ** penutup yang tepat berada setelah tanda baca harus diikuti oleh spasi, tanda baca, atau akhir baris; ini adalah aturan sayap kanan. Bahasa Inggris selalu memiliki spasi di sana. Bahasa Mandarin, Jepang, dan Korea sering tidak. Jadi 打开**设置 → 导出（测试版）**并选择 menampilkan tanda bintang literal, karena tebal diakhiri dengan tanda kurung lebar penuh dan langsung diikuti oleh 并. Baris yang sama tanpa tanda kurung akan dirender tebal, begitu juga baris dengan spasi setelah **. Tautan tebal memiliki masalah yang sama, karena tautan diakhiri dengan ): 点击**[导出](./export-options.md)**打开 gagal, begitu juga dengan bahasa Korea **[API](./api.md)**는.

Model kami kebetulan menempatkan spasi di kedua sisi setiap frasa tebal, sehingga outputnya dirender dengan benar. Editor yang kemudian menghapus spasi tersebut untuk mengikuti konvensi tata letak bahasa Mandarin akan memunculkan kembali bug tersebut. Anda dapat mencoba ketujuh varian di render-cases.md.

Rentang angka dengan tilde. Teks bahasa Mandarin dan Jepang sering menulis rentang sebagai 3~5. Situs GitHub Flavored Markdown yang dibangun di atas remark mengubah tilde tunggal menjadi coretan secara default: opsi remark-gfm singleTilde bernilai true kecuali Anda mengubahnya. Dua rentang dalam satu paragraf, seperti 需要 3~5 分钟，生成 10~20 MB 的文件夹, akan dirender dengan teks di antaranya tercoret. Sampel kami menggunakan en dash, dan delapan proses menjaganya sementara proses kesembilan menulis 3 到 5. Mintalah en dash atau kata-kata dalam rentang, atau atur singleTilde: false dalam konfigurasi remark Anda.

Pemeriksa struktural menandai kedua pola tersebut. Untuk memastikan apa yang sebenarnya dirender, render_check.mjs menghitung tebal, miring, coretan, dan sisa tanda bintang dalam sumber dan terjemahan, serta mencoba kompilasi MDX:

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

Node tebal yang lebih sedikit atau tanda bintang literal yang lebih banyak dalam terjemahan berarti beberapa penekanan berhenti menutup.

Alur Kerja yang Teruji

1. Perbaiki ID judul terlebih dahulu. Tambahkan ID eksplisit ke setiap judul yang ditautkan oleh sesuatu, dalam sintaks yang didukung oleh generator situs Anda. Lakukan dalam bahasa sumber, sekali, dan commit sebelum apa pun diterjemahkan.

2. Keluarkan front matter dari halaman. Terjemahkan hanya nilai yang menghadap pembaca seperti title dan description, sebagai string terpisah, dan tulis kembali ke YAML asli.

3. Tentukan kebijakan kode. Komentar diterjemahkan atau tidak; string tampilan dalam contoh konfigurasi diterjemahkan atau tidak. Tuliskan dalam glosarium terjemahan Anda di samping nama produk yang tidak boleh berubah, seperti Shelfmark dalam sampel kami.

4. Terjemahkan isi. Gunakan alat yang mem-parsing Markdown, atau kirim seluruh halaman dengan aturan eksplisit. Dalam pengujian kami, mengirim seluruh halaman menjaga sintaks tetap utuh; jika Anda menggunakan placeholder, lindungi konstruksi lengkap dan jangan biarkan apa pun setengah terbuka.

5. Jalankan pemeriksaan struktural.

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

   Ini membandingkan kunci dan nilai front matter, impor, blok kode, kode inline, target tautan, definisi referensi, tingkat judul, target tautan dalam halaman, tag dan atribut JSX, komentar MDX, penanda admonisi, label catatan kaki, bentuk tabel, kotak daftar tugas, jeda baris keras, penekanan yang tidak dapat menutup, rentang tilde, dan istilah yang Anda minta untuk dipertahankan. Ini tidak menilai kualitas terjemahan.

6. Periksa rendering untuk target CJK dengan render_check.mjs, dan tambahkan spasi setelah setiap ** penutup yang mengikuti tanda baca.

7. Bangun situs dan klik tautannya. Buka halaman dalam setiap bahasa, klik setiap tautan dalam halaman, dan baca contoh konfigurasi. Build yang berhasil hanya membuktikan bahwa file tersebut dapat dikompilasi.

Untuk dokumentasi yang mengutamakan akurasi, langkah terminologi dan tinjauan dalam alur kerja terjemahan teknis kami berlaku di atas ini.

Posisi BookTranslator

Penerjemah TXT BookTranslator menerima file .txt, .md, dan .mdx. Menurut halaman produk, ia menerjemahkannya sambil mempertahankan paragraf, jeda baris, karakter khusus, dan struktur teks, dan memecah file besar menjadi segmen untuk terjemahan yang sadar konteks, sehingga Anda dapat mengunggah seluruh manual atau buku yang ditulis dalam Markdown alih-alih menempelkannya sepotong-sepotong.

Halaman produk tidak menjelaskan penanganan khusus untuk front matter, blok kode, atau komponen MDX, dan kami tidak menjalankan sampel ini melalui BookTranslator untuk artikel ini. Apa pun alat yang Anda gunakan, lakukan langkah 1 hingga 3 sebelum menerjemahkan dan langkah 5 hingga 7 setelahnya. Judul tanpa ID tetap kehilangan tautannya, dan rentang yang ditulis dengan tilde tetap berubah menjadi coretan. Jika Anda menerbitkan buku dalam beberapa bahasa, panduan penerbitan mandiri dalam berbagai bahasa kami mencakup sisa pekerjaan tersebut.

Dapatkan File Uji

Semua dari pengujian ini bebas untuk digunakan kembali:

• sample-source.mdx: sampel bahasa Inggris 73 baris;
• check_markdown_translation.py: pemeriksa struktural (hanya pustaka standar Python);
• render_check.mjs dan render-cases.md: pemeriksaan rendering dan tujuh kasus uji CJK;
• run_llm_markdown_test.py: tiga kondisi prompt untuk server lokal apa pun yang kompatibel dengan OpenAI;
• sembilan keluaran di folder keluaran, beserta check-results.txt dan results.csv.