Jangan mengganti seluruh HTML saat menerjemahkan halaman web: hanya proses node teks yang diizinkan

Saat menerjemahkan halaman web, masalah pertama yang dihadapi banyak orang bukanlah karena terjemahannya tidak akurat, tetapi skrip dan gayanya diterjemahkan secara bersamaan. Misalnya, setelah nama variabel di <script> dan nama kelas di <style> diganti sebagai teks, browser mungkin langsung melaporkan kesalahan dan gaya halaman akan menjadi kacau. Artikel ini ditujukan untuk pengembang dan tim dokumentasi yang perlu menangani terjemahan halaman HTML dengan Python.

Di akhir artikel ini, Anda akan mengetahui cara menggunakan tipe NavigableString Beautiful Soup untuk mengidentifikasi node teks yang boleh diganti, melihat contoh penggantian yang aman, dan mengetahui batasan dan kriteria penerimaan apa yang harus ditinjau sebelum pengiriman. Sampel dalam artikel ini semuanya adalah data sintetis, dan sampel kode telah diperiksa di lingkungan yang terisolasi, namun hal ini tidak mewakili jaminan semua file atau efek produk yang sebenarnya. Harap simpan dokumen asli sebelum menangani dokumen penting.

Bagaimana cara mengganti hanya teks isi dalam terjemahan halaman web? Kesimpulan satu kalimat

Sebelum penggantian, pertama-tama kecualikan string khusus seperti Script, Stylesheet, dan Comment melalui penilaian tipe, dan hanya ganti NavigableString biasa.

Mengapa NavigableString perlu melakukan penilaian tipe terlebih dahulu?

Banyak pengembang yang terbiasa menggunakan soup.find_all(text=True) atau melintasi .strings untuk mendapatkan teks halaman. Metode ini berfungsi pada ekstraksi konten murni, namun berisiko dalam skenario penerjemahan. Beautiful Soup 4.9.0 kemudian memperkenalkan subkelas string khusus untuk dokumen HTML. Meskipun mewarisi dari NavigableString, semantiknya sangat berbeda.

• Comment: Komentar
• Script: kode JavaScript
• Stylesheet: gaya CSS
• Template: konten templat HTML

Jika Anda memanggil .replace_with() pada objek ini, konten lapisan non-presentasi akan diubah. Misalnya, menerjemahkan var userName = "admin"; ke var 用户名 = "管理员"; akan menghasilkan kesalahan sintaksis JS. Pendekatan yang benar adalah dengan membuat pernyataan tipe sebelum substitusi untuk memastikan bahwa target hanyalah NavigableString biasa dan bukan subkelas fungsional.

Saat memproses dokumen XML, Anda juga perlu memperhatikan tipe khusus seperti CData, ProcessingInstruction, dll. Juga tidak boleh diterjemahkan sebagai teks biasa.

Contoh sintesis: batas antara benar dan salah

Untuk mendemonstrasikan mekanisme ini, sebuah fragmen HTML sintetis yang berisi konten campuran dibuat di bawah ini, mencakup empat jenis node: isi, skrip, gaya, dan komentar.

Contoh masukan (contoh sintetik):

<div class="content">
  Welcome user
  <script>var msg = "Welcome user";</script>
  <style>.msg { color: red; }</style>
  <!-- Welcome user -->
</div>

Hasil yang diharapkan benar:

• Hanya node teks langsung "Welcome user" dalam tag <div> yang diganti dengan "Welcome user".
• Senar dalam <script> tetap utuh.
• Isi <style> tetap tidak berubah, dan isi anotasi tetap tidak berubah.
• Hubungan hierarki DOM dipertahankan sepenuhnya.

Masukan dan konsekuensi umum yang salah:

Jika Anda tidak menambahkan pengecekan tipe dan langsung melakukan penggantian global pada semua NavigableString, maka tag <script> akan menjadi var msg = "欢迎用户";. Beberapa penafsir longgar mungkin tidak melaporkan kesalahan, namun jika penetapan variabel melibatkan penilaian logis atau pemetaan nilai kunci yang diinternasionalkan, logika program akan gagal. Jika proses penerjemahan mengubah jenis kutipan atau karakter escape, penguraian skrip mungkin terganggu dan seluruh halaman akan muncul sebagai layar putih.

Implementasi Python untuk penggantian node teks yang aman

Kode berikut menunjukkan cara menangani sampel sintetis di atas dengan aman di memori. Contohnya tergantung pada beautifulsoup4. Silakan jalankan di lingkungan yang mengunci dependensi. Versi yang disarankan adalah 4.9.0 atau lebih tinggi untuk mendukung deteksi subkelas string khusus. Kode ini tidak menyertakan permintaan jaringan, tetapi hanya menunjukkan logika penguraian dan penggantian.

from bs4 import BeautifulSoup, NavigableString, Comment
# BS4 4.9.0+ 才引入 Script, Stylesheet 等子类
try:
    from bs4 import Script, Stylesheet, Template
    HAS_SPECIAL_STRINGS = True
except ImportError:
    HAS_SPECIAL_STRINGS = False

def safe_translate_text(html_content: str, translation_map: dict) -> str:
    """
    仅替换普通文本节点，跳过脚本、样式、注释及模板。
    :param html_content: 原始HTML字符串（若处理文件请先读取为字符串）
    :param translation_map: 原文到译文的映射字典
    :return: 替换后的HTML字符串
    """
    soup = BeautifulSoup(html_content, 'html.parser')

    # 收集所有需要处理的字符串节点
    # 注意：不能边遍历边修改，需先收集再处理
    targets = []
    for element in soup.descendants:
        if not isinstance(element, NavigableString):
            continue
        # 核心防护：排除特殊功能字符串
        if isinstance(element, Comment):
            continue
        if HAS_SPECIAL_STRINGS and isinstance(element, (Script, Stylesheet, Template)):
            continue
        # 可选：跳过纯空白节点以减少无效API调用
        if not str(element).strip():
            continue

        targets.append(element)

    # 执行安全替换
    for node in targets:
        original = str(node)
        if original in translation_map:
            # 显式创建NavigableString确保DOM引用完整性
            new_node = NavigableString(translation_map[original])
            node.replace_with(new_node)

    return str(soup)

# --- 合成数据验证 ---
SAMPLE_HTML = '''<div>Welcome user<script>var x="Welcome user";</script><!-- Welcome user --></div>'''
DICT_MAP = {"Welcome user": "欢迎用户"}

result = safe_translate_text(SAMPLE_HTML, DICT_MAP)
assert "欢迎用户" in result, "正文应被翻译"
assert 'var x="Welcome user";' in result, "脚本内容不应被修改"
assert "<!-- Welcome user -->" in result, "注释不应被修改"
print("逻辑校验通过（教学示例，非生产环境实测证明）")

Kunci dari kode ini adalah beberapa pemeriksaan isinstance. Meskipun Beautiful Soup lebih lama dan tidak mendukung kelas seperti Script, Anda dapat memeriksa nama tag induk sebagai solusi cadangan, namun pemeriksaan tipe eksplisit selalu lebih disukai. Menggunakan replace_with dengan konstruksi NavigableString eksplisit lebih aman daripada penugasan langsung. Itu dapat menangani hubungan referensi node di pohon dengan benar dan menghindari objek yatim piatu atau kebingungan mengetik.

Kriteria penerimaan dan batasan tinjauan manual

Pemfilteran tipe hanyalah garis pertahanan pertama. Sebelum pengiriman, matriks penerimaan yang jelas perlu ditetapkan untuk membedakan antara pemrosesan otomatis dan intervensi manual untuk menghindari kepercayaan buta terhadap keluaran skrip.

Tabel ini hanya cocok untuk verifikasi logika pada tingkat demonstrasi kode. Efek end-to-end memerlukan verifikasi hasil rendering di browser sebenarnya. Meskipun atribut content dari tag <meta>, tag ARIA, dll. bukan milik NavigableString, atribut tersebut mungkin juga perlu diterjemahkan. Hal ini mengharuskan parser memiliki kemampuan traversal atribut dan berada di luar cakupan simpul artikel ini.

Bacaan lebih lanjut

• Dokumentasi Resmi Sup Cantik: NavigableString
• Dokumentasi Resmi Sup Cantik: Jenis benda

Gunakan daftar periksa untuk terjemahan dokumen

Teks, tautan, kode, dan struktur dokumen halaman web harus diproses secara terpisah. Tambahkan bagian yang dilindungi ke daftar penerimaan, lalu evaluasi keterbacaan dan presentasi halaman setelah terjemahan.

OmniDoc menyediakan portal terjemahan dokumen multi-format. Situs web resmi memperkenalkan fungsi-fungsi seperti OCR, glosarium, dan perbandingan bilingual. Jika tim ingin memulai pemrosesan langsung dari file, jalur ini dapat dievaluasi dengan sampel nyata. Harap gunakan file yang tidak peka dan Anda mempunyai izin untuk mengunggahnya, dan gunakan item centang dalam artikel ini untuk meninjau hasilnya. Hal ini tidak melibatkan klaim bahwa OmniDoc menggunakan pustaka sumber terbuka atau algoritme internal yang dijelaskan dalam artikel ini, dan contoh tersebut bukan pengganti pengujian kinerja produk.

📊 Perbandingan inti

🎯 Metode mana yang cocok untuk Anda?

jika kamu……

• Menangani terjemahan isi halaman web: memfilter dengan tipe eksplisit dan hanya mengganti NavigableString biasa.
• Isi di <script> dan <style> perlu diterjemahkan: Pertama-tama konfirmasikan apakah itu sumber daya i18n, lalu putuskan apakah akan memprosesnya. Ini dilewati secara default.
• Menggunakan Beautiful Soup versi lama: Anda dapat menggunakan nama tag induk untuk penilaian penurunan versi, tetapi disarankan untuk meningkatkan ke 4.9.0 atau lebih tinggi.
• Untuk menerjemahkan alt, title dan atribut lainnya: Logika traversal atribut perlu ditulis secara terpisah, dan metode ini tidak mencakup bagian ini.

❓ Pertanyaan yang Sering Diajukan (FAQ)

1. Bisakah saya langsung menggunakan find_all(text=True) untuk mendapatkan teks yang akan diterjemahkan?

Metode ini cocok untuk ekstraksi konten murni, namun dalam skenario penerjemahan, subkategori khusus seperti Script dan Stylesheet juga akan diperlakukan sebagai teks biasa, sehingga berisiko.

2. Apa yang harus saya lakukan jika versi Beautiful Soup lebih lama?

Dimungkinkan untuk memeriksa nama tag induk sebagai skenario penurunan versi, tetapi pemeriksaan tipe eksplisit selalu lebih disukai dan versi 4.9.0+ disarankan.

3. Panjang HTML berubah drastis setelah penggantian. Apa yang harus kita perhatikan?

Peringatan harus ditandai ketika panjangnya berubah lebih dari 300%, dan terjemahan harus diperiksa untuk karakter khusus yang tidak lolos untuk mencegah injeksi atau tata letak meluap.

4. Apakah nilai atribut seperti alt dan title akan diproses oleh kode ini?

Tidak akan. Nilai atribut berada di luar cakupan artikel ini, dan logika traversal atribut perlu ditulis secara terpisah.

5. Bisakah digunakan langsung pada file asli?

Disarankan untuk menyimpan dokumen asli terlebih dahulu dan mengujinya dengan dokumen yang tidak peka dan Anda memiliki izin untuk mengunggahnya. Kode tersebut lolos pemeriksaan sampel sintetis dan tidak mewakili jaminan semua file asli.

📝 Ringkasan

Kunci penerjemahan halaman web adalah mengidentifikasi jenis node terlebih dahulu dan kemudian memutuskan apakah node tersebut dapat diganti. Filter string khusus secara eksplisit seperti Script, Stylesheet, dan Komentar, dan gunakan matriks penerimaan untuk meninjau hasilnya, sehingga teks dapat diterjemahkan sambil memastikan bahwa halaman dapat berjalan normal.

Coba sekarang: Unggah dokumen untuk memulai penerjemahan, dengan tetap mempertahankan tata letak aslinya