Cara Menerjemahkan File HTML Tanpa Merusak Tag, Atribut, atau Tautan

Untuk menerjemahkan file HTML, terjemahkan teks yang dibaca orang dan atribut yang memuat kata-kata untuk pembaca, seperti alt, title, placeholder, aria-label, dan deskripsi meta halaman. Biarkan markup apa adanya: nama tag, href, src, id, class, skrip, gaya, dan apa pun yang ditandai translate="no". Lalu ubah satu nilai yang mudah terlupakan, atribut lang pada elemen <html>, agar peramban, pembaca layar, dan mesin pencari tahu bahasa halaman saat ini.

Menjaga tag tetap utuh ternyata bagian yang mudah. Kami menerjemahkan halaman bantuan HTML 59 baris ke bahasa Mandarin Sederhana sembilan kali dengan model lokal, menggunakan tiga metode, dan memeriksa setiap keluaran dengan skrip. Setiap proses mempertahankan semua tag, tautan, dan ID. Yang salah lebih senyap: model menerjemahkan satu baris di dalam blok kode <pre> pada keenam proses yang mengirim seluruh file, membiarkan aria-label navigasi dalam bahasa Inggris pada keenamnya, dan metode yang secara desain paling aman menjaga markup, yaitu menerjemahkan potongan teks satu per satu, menghasilkan kalimat yang menyuruh pembaca melakukan hal yang salah pada ketiga prosesnya.

Jawaban Singkat: Apa yang Diterjemahkan dan Apa yang Dibiarkan

Daftar ini bukan buatan kami. Bagian Standar HTML tentang atribut translate mendefinisikan "atribut yang dapat diterjemahkan": title pada setiap elemen, alt pada gambar, placeholder pada input, content pada elemen meta yang namanya diketahui dapat diterjemahkan, dan lang, yang menurut standar tersebut harus diubah agar sesuai dengan bahasa baru. Standar itu juga menyebut aria-label dari ARIA sebagai contoh atribut yang dapat ditambahkan oleh spesifikasi lain, dan menyatakan bahwa dalam elemen translate="no", teks dan nilai atribut "harus dibiarkan apa adanya saat halaman dilokalkan."

Yang Kami Uji

Kami menulis sample-source.html, halaman pusat bantuan untuk aplikasi bacaan fiktif yang sama, Shelfmark, yang kami gunakan dalam uji terjemahan Markdown. File ini memiliki satu contoh dari setiap baris dalam tabel di atas, ditambah beberapa jebakan:

• kalimat yang dipisahkan oleh tag inline: "Sebelum mengekspor, cadangkan catatan Anda. Ekspor menyalin buku Anda, tetapi tidak menghapus apa pun dari Shelfmark," dengan nama produk di dalam translate="no";
• kalimat dengan dua elemen <code> inline yang urutannya penting: "Ketik jalur ke folder <library> setelah --out";
• blok <pre><code> dengan sebuah perintah dan satu baris contoh keluaran, # Export finished: 128 books;
• aturan CSS yang menyisipkan kata "Catatan:" sebelum sebuah paragraf;
• tautan dalam halaman ke #choose-format, tautan mailto:, formulir pencarian, dan blok JSON-LD.

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

1. Seluruh file. Tempel seluruh file dan minta file terjemahan dikembalikan.
2. Dengan instruksi. Sama seperti di atas, ditambah delapan aturan: pertahankan setiap nama tag dan atribut, jangan ubah href, src, id, class dan nilai serupa, terjemahkan atribut teks dan tag meta yang tercantum, biarkan <code>, <pre>, <script>, dan <style> kecuali name dan description JSON-LD, hormati translate="no", pertahankan referensi karakter dan komentar, dan atur lang menjadi zh-Hans.
3. Segmen. Pendekatan alat yang mengekstrak teks dari HTML: skrip memecah file menjadi tag dan teks, melewati <code>, <pre>, <script>, <style>, dan elemen translate="no", mengirim potongan teks dan atribut teks yang tersisa ke model sebagai daftar JSON bernomor, dan menuliskan terjemahan kembali ke markup yang tidak tersentuh. Skrip ini juga mengatur lang="zh-Hans" sendiri.

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

Ini adalah uji kecil dengan satu model, satu pasangan bahasa, dan satu halaman. Uji ini menunjukkan masalah apa yang terjadi dan cara menangkapnya. Uji ini tidak memberi peringkat pada model atau alat.

Hasil: Markup Bertahan; Tiga Keputusan Tidak

Kami memeriksa setiap keluaran dengan check_html_translation.py, sebuah pemeriksa yang hanya menggunakan pustaka standar Python. Keluaran lengkapnya ada di check-results.txt, dan results.csv berisi satu baris per eksekusi.

Kesembilan eksekusi mempertahankan 58 tag yang sama dalam urutan yang sama, setiap href, src, id, dan class, target tautan dalam halaman, komentar, <library> yang di-escape, dan nama produk di dalam translate="no". Jika Anda khawatir model akan merusak markup halaman sederhana, ternyata tidak. Masalahnya semua ada pada apa yang harus diterjemahkan.

1. Contoh output di dalam <pre> ikut diterjemahkan

Blok kode dalam sampel kami diakhiri dengan satu baris output program:

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

Dalam keenam eksekusi whole-file dan instructed, model mengembalikan # 导出完成：128 本书 pada baris itu, termasuk tiga eksekusi yang prompt-nya melarang mengubah apa pun di dalam <pre>. Perintahnya sendiri tidak pernah disentuh. Model menganggap baris itu sebagai komentar, dan menerjemahkan komentar adalah pilihan yang wajar dalam tutorial. Namun baris ini adalah yang dicetak program, dan pembaca yang membandingkannya dengan terminal mereka akan melihat bahasa Inggris. Putuskan sebelum menerjemahkan apakah contoh output dan komentar kode diterjemahkan, lalu beri tahu alatnya, atau lindungi blok <pre> sepenuhnya.

Eksekusi whole-file juga menerjemahkan content: "Note: " CSS di blok <style>, sedangkan eksekusi instructed, yang diminta membiarkan <style> saja, membiarkannya dalam bahasa Inggris. Keduanya tidak salah dengan sendirinya. Menerjemahkan stylesheet benar untuk halaman yang CSS-nya inline, dan salah untuk situs yang satu stylesheet bersamanya melayani semua bahasa. Bagaimanapun, ini adalah keputusan yang harus diambil seseorang, bukan detail yang seharusnya ditebak model.

2. Label aksesibilitas dilewati

Navigasi breadcrumb adalah <nav aria-label="Breadcrumb">. Pembaca layar mengumumkan label itu; pembaca awas tidak pernah melihatnya. Dalam keenam eksekusi whole-file dan instructed, label itu tetap dalam bahasa Inggris, meskipun prompt instructed mencantumkan aria-label di antara atribut yang harus diterjemahkan. Dalam satu eksekusi instructed, aria-label="Search" pada tombol pencarian juga tetap dalam bahasa Inggris.

Metode segmen menerjemahkannya setiap kali, karena skripnya mengumpulkan setiap nilai aria-label, alt, title, dan placeholder dan meminta masing-masing secara eksplisit. Itulah argumen terkuat untuk mengekstrak atribut teks dengan sengaja daripada berharap model memperhatikannya.

3. Menerjemahkan potongan menjaga tag tetapi merusak kalimat

Metode segmen aman untuk markup secara konstruksi: model tidak pernah melihat tag, sehingga tidak dapat merusaknya. Metode ini lolos setiap pemeriksaan struktural dalam ketiga percobaan. Metode ini juga menghasilkan satu-satunya terjemahan dalam pengujian yang memberikan instruksi salah kepada pembaca.

Kalimat bahasa Inggrisnya adalah "Type the path to the <library> folder after --out." Inline <code> membaginya menjadi tiga potongan: "Type the path to the", "folder after", dan sebuah titik. Bahasa Mandarin menempatkan kata-kata ini dalam urutan berbeda, sehingga penerjemah perlu memindahkan dua elemen kode. Metode segmen tidak dapat memindahkannya. Ketiga percobaan membalik instruksi. Percobaan 2 menghasilkan ini (percobaan 1 dan 3 menulis 后 bukan 之后, dengan makna sama):

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

Itu terbaca "setelah <library>, ketik path folder --out," kebalikan dari instruksi. Keenam percobaan whole-file dan instructed memindahkan elemen kode dan melakukannya dengan benar:

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

Pemisahan yang sama meninggalkan spasi liar di tempat tag bertemu teks Mandarin, seperti 前往 <b>设置</b> dan <b>书库</b> ，, dalam ketiga percobaan segmen, enam tempat per percobaan. Peramban menampilkannya sebagai celah yang terlihat, termasuk sebelum tanda baca Mandarin. Percobaan whole-file tidak memiliki celah; dua dari tiga percobaan instructed memiliki empat atau lima.

Pemeriksa struktural tidak dapat menangkap kalimat yang dibalik, karena setiap tag berada tepat di tempatnya. Pemeriksa kami melaporkan ketika kode inline berubah urutan, yang normal untuk banyak bahasa, tetapi peringatan itu tidak dapat membedakan benar dari salah. Dalam pengujian ini, peringatan itu muncul pada keenam terjemahan yang benar dan diam pada ketiga yang salah, karena yang salah mempertahankan urutan bahasa Inggris. Hanya orang yang membaca kalimat itu yang dapat mengetahuinya. Solusinya adalah mengirim kalimat utuh, dengan tag inline-nya, ke penerjemah, seperti yang dilakukan percobaan whole-file, dan memeriksa struktur setelahnya.

Perbedaan yang lebih kecil

• lang: percobaan whole-file mengubahnya menjadi zh-CN sendiri. Percobaan instructed menggunakan zh-Hans, sesuai permintaan. Keduanya adalah tag bahasa yang valid; zh-Hans menamai aksara (Mandarin Sederhana), zh-CN menamai wilayah. Panduan W3C tentang deklarasi bahasa merekomendasikan mendeklarasikan bahasa pada elemen <html> dan bukan dengan tag meta Content-Language.
• JSON-LD: percobaan whole-file dan instructed menerjemahkan nilai name dan description serta menjaga JSON tetap valid. Skrip segmen kami melewati konten <script>, sehingga data terstrukturnya tetap dalam bahasa Inggris, yang juga akan terjadi pada alat yang mengabaikan skrip.
• Referensi karakter: percobaan whole-file dan instructed mempertahankan ›,  , ©, dan referensi emoji sebagaimana ditulis. Lima dari enam percobaan tersebut menulis ulang rentang 2–5 dalam kata-kata Mandarin (2 到 5 atau 2 至 5); satu percobaan instructed menulis tanda hubung biasa alih-alih referensi, meskipun prompt-nya mengatakan untuk mempertahankan referensi. Skrip segmen kami mendekode semuanya dan menulis karakter kembali, yang menampilkan hal yang sama. Yang penting, <library> di dalam <code>, tetap ter-escape di kesembilan percobaan.

Sebelum Menerjemahkan: Siapkan File

1. Tandai apa yang tidak boleh berubah. Letakkan translate="no" pada nama produk, nomor model, string mirip kode dalam prosa, dan apa pun yang harus tetap seperti adanya. Itu bagian dari HTML, tidak memakan biaya, dan model menghormatinya di keenam percobaan yang mengirim seluruh file. Alat segmen yang membacanya, seperti skrip kami, melewati elemen tersebut sepenuhnya. Panduan jangan-terjemahkan kami membahas cara memutuskan apa yang masuk daftar itu.
2. Tentukan kebijakan kode. Apakah komentar kode diterjemahkan? Apakah contoh output? Apakah stylesheet dibagikan lintas bahasa? Tuliskan jawabannya, bersama nama-nama yang tidak boleh berubah, dalam glosarium terjemahan, dan berikan kepada siapa pun atau apa pun yang menerjemahkan.
3. Pertahankan ID dalam bahasa sumber. Tautan dalam halaman menunjuk ke nilai id. Jika seseorang menerjemahkan id, setiap tautan ke sana akan rusak. Tidak ada percobaan kami yang melakukannya, tetapi penerjemah yang "membantu" melokalkan anchor akan melakukannya.
4. Kumpulkan teks tersembunyi. Daftarkan atribut yang memuat kata-kata, alt, title, placeholder, aria-label, value pada tombol, tag meta, dan JSON-LD, agar diperiksa dan tidak terlupakan.
5. Jangan terjemahkan string JavaScript di tempat. Pesan yang diatur oleh skrip, seperti alert atau label tombol yang dibuat dalam kode, memerlukan langkah lokalisasi terpisah dalam kode. Tidak ada dari enam percobaan whole-file atau instructed yang mengubah blok skrip kami, yang benar, tetapi itu berarti string tersebut tetap dalam bahasa Inggris.

Setelah Menerjemahkan: Periksa

1. Jalankan pemeriksaan struktural.

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

   Pemeriksaan ini membandingkan tag dan urutannya, setiap atribut yang bukan teks untuk pembaca, isi <pre>, <script>, dan <style>, kode inline, kunci JSON-LD, teks translate="no", komentar, dan tautan dalam halaman. Pemeriksaan ini memperingatkan tentang atribut teks yang masih dalam bahasa Inggris, nilai lang yang berbeda dari yang Anda harapkan, teks terlihat yang tampak belum diterjemahkan, kode inline yang berubah urutan, dan spasi antara teks Mandarin, Jepang, atau Korea di sekitar tag inline. Pemeriksaan ini tidak menilai kualitas terjemahan.

2. Baca setiap kalimat yang mengandung tag inline. Di sinilah makna rusak dalam pengujian kami. Jangan mengandalkan peringatan "kode inline diurutkan ulang" dari pemeriksa untuk menemukan kalimat ini: dalam pengujian kami, terjemahan yang salah adalah yang mempertahankan urutan asli.

3. Buka halaman di peramban. Klik tautan dalam halaman, tab melalui formulir dengan pembaca layar jika memungkinkan, dan cari celah di sekitar teks tebal dan tertaut.

4. Untuk bahasa kanan-ke-kiri, atur juga dir="rtl" pada elemen <html>. Panduan terjemahan buku RTL kami membahas apa lagi yang berubah.

5. Untuk XHTML, seperti file bab di dalam EPUB, konfirmasikan juga bahwa file tersebut masih XML yang well-formed, misalnya dengan xmllint --noout chapter.xhtml. Peramban memaafkan tag yang tidak ditutup; pembaca e-book mungkin tidak. Daftar periksa QA terjemahan EPUB kami membahas sisanya dari sebuah e-book.

Di Mana BookTranslator Cocok

Halaman unggah BookTranslator menerima file .html, .htm, dan .xhtml bersama buku dan dokumen, sehingga Anda dapat mengunggah halaman tersimpan atau artikel bantuan statis sebagai satu file utuh. Kami tidak menjalankan sampel ini melalui BookTranslator untuk artikel ini, dan kami belum menguji bagaimana ia menangani urutan kode inline, konten CSS, atau JSON-LD, jadi periksa hasilnya dengan cara yang sama seperti Anda memeriksa alat lain mana pun. Anda melihat harganya sebelum membayar.

Apa pun yang Anda gunakan, lakukan langkah persiapan sebelum menerjemahkan dan pemeriksaan setelahnya. Halaman dengan semua tag utuh tetap bisa menyuruh pembaca mengetik hal yang salah. Jika HTML Anda sebenarnya adalah dokumentasi yang ditulis dalam Markdown, panduan penerjemahan Markdown kami membahas format sumbernya.

Dapatkan File Uji

Semua dari pengujian ini bebas digunakan kembali:

• sample-source.html: sampel bahasa Inggris 59 baris;
• check_html_translation.py: pemeriksa struktural (hanya pustaka standar Python);
• run_llm_html_test.py: tiga metode, untuk server lokal apa pun yang kompatibel dengan OpenAI;
• sembilan keluaran di folder outputs, dengan check-results.txt dan results.csv.