Hogyan fordítsunk HTML-fájlt a címkék, attribútumok és hivatkozások törése nélkül

Egy HTML-fájl fordításához az emberek által olvasott szöveget és az olvasóknak szóló szavakat tartalmazó attribútumokat kell lefordítani, például az alt, title, placeholder, aria-label attribútumokat és az oldal meta leírását. A jelölőnyelvet hagyjuk érintetlenül: a címkeneveket, a href, src, id, class attribútumokat, a szkripteket, stíluslapokat és mindent, ami translate="no" jelöléssel van ellátva. Ezután változtassunk meg egy könnyen elfelejthető értéket, a lang attribútumot a <html> elemen, hogy a böngészők, a képernyőolvasók és a keresőmotorok tudják, milyen nyelven van most az oldal.

A címkék érintetlenül hagyása bizonyult a könnyebb résznek. Egy 59 soros HTML súgóoldalt fordítottunk le egyszerűsített kínaira kilenc alkalommal egy helyi modellel, három módszert használva, és minden kimenetet egy szkripttel ellenőriztünk. Minden futás megtartotta az összes címkét, hivatkozást és azonosítót. Ami rosszul sült el, az csendesebb volt: a modell lefordított egy sort egy <pre> kódblokkon belül mind a hat futásban, amelyek az egész fájlt küldték, az angolul hagyta a navigáció aria-label attribútumát mind a hatban, és a módszer, amely a legbiztonságosabban őrzi meg a jelölőnyelvet, a szövegrészek egyenkénti fordítása, egy olyan mondatot eredményezett, amely rossz cselekvésre utasította az olvasót mind a három futásában.

Gyors válasz: mit kell lefordítani és mit kell érintetlenül hagyni

Ez a lista nem a mi találmányunk. Az HTML szabvány translate attribútumról szóló része meghatározza a „fordítható attribútumokat”: title minden elemen, alt a képeken, placeholder az inputokon, content azokon a meta elemeken, amelyek neve ismerten fordítható, valamint lang, amelyet az új nyelvnek megfelelően módosítani kell. Ugyanitt az ARIA aria-label attribútumát is példaként említi olyan attribútumra, amelyet más specifikációk is hozzáadhatnak, és kimondja, hogy egy translate="no" elemben a szöveget és az attribútumértékeket „a lap lokalizálásakor változatlanul kell hagyni”.

Mit teszteltünk

Megírtuk a sample-source.html fájlt, egy súgóközpont-oldalt ugyanahhoz a fiktív olvasóalkalmazáshoz, a Shelfmarkhoz, amelyet a Markdown-fordítási tesztünkben is használtunk. Minden fenti táblázatsorhoz tartalmaz egy példát, valamint néhány csapdát:

• egy beágyazott tagekkel szétdarabolt mondat: „Before you export, back up your notes. An export copies your books, but it does not delete anything from Shelfmark,” a terméknévvel translate="no" belsejében;
• egy mondat két beágyazott <code> elemmel, amelyek sorrendje számít: „Type the path to the <library> folder after --out”;
• egy <pre><code> blokk egy paranccsal és egy sor mintakimenettel, # Export finished: 128 books;
• egy CSS-szabály, amely a „Note:” szót szúrja be egy bekezdés elé;
• egy oldalon belüli hivatkozás a #choose-format-ra, egy mailto: hivatkozás, egy keresőűrlap és egy JSON-LD blokk.

Ezután megkértünk egy helyi modellt, hogy háromféleképpen fordítsa le egyszerűsített kínaira:

1. Teljes fájl. Illeszd be a teljes fájlt, és kérd vissza a lefordított fájlt.
2. Utasításokkal. Ugyanaz, plusz nyolc szabály: tartsd meg az összes tag- és attribútumnevet, ne változtasd meg a href, src, id, class és hasonló értékeket, fordítsd le a felsorolt szövegattribútumokat és meta tageket, hagyd érintetlenül a <code>, <pre>, <script> és <style> elemeket, kivéve a JSON-LD name és description mezőit, tartsd tiszteletben a translate="no" attribútumot, őrizd meg a karakterhivatkozásokat és megjegyzéseket, és állítsd a lang attribútumot zh-Hans-ra.
3. Szegmensek. Azoknak az eszközöknek a megközelítése, amelyek szöveget nyernek ki HTML-ből: egy szkript felosztja a fájlt tagekre és szövegre, kihagyja a <code>, <pre>, <script>, <style> és translate="no" elemeket, a maradék szövegrészeket és szövegattribútumokat számozott JSON-listaként elküldi a modellnek, majd a fordításokat visszaírja az érintetlen jelölésbe. A lang="zh-Hans" beállítást maga végzi el.

A modell a Qwen 3.6 27B (Q4_K_M) volt LM Studioban, gondolkodás kikapcsolva, hőmérséklet 0,3, egy Apple M4 Max 64 GB memóriával. Minden módszert háromszor futtattunk, összesen kilenc futást, 2026. október 27-én. A szkript a run_llm_html_test.py, és mind a kilenc kimenet szerkesztetlenül megjelent; a README minden fájlt felsorol. Ha még nem állítottál be helyi modellt, a helyi LLM-fordítási útmutatónk ismerteti a beállításokat.

Ez egy kis teszt volt egy modellel, egy nyelvpárral és egy oldallal. Megmutatja, milyen problémák fordulnak elő, és hogyan lehet elkapni őket. Nem rangsorol modelleket vagy eszközöket.

Eredmény: A jelölés túlélte; három döntés nem

Minden kimenetet a check_html_translation.py ellenőrzővel vizsgáltunk, amely csak a Python szabványos könyvtárát használja. A teljes kimenet a check-results.txt fájlban található, a results.csv pedig futtatásonként egy sort tartalmaz.

Mind a kilenc futás ugyanazt az 58 taget tartotta meg ugyanabban a sorrendben, minden href, src, id és class értéket, az oldalon belüli hivatkozás célját, a megjegyzést, a kimentett <library> szöveget és a translate="no" attribútumban lévő terméknevet. Ha attól tartottál, hogy egy modell elrontja egy egyszerű oldal jelölőnyelvét, nem tette. A problémák mind abból adódtak, hogy mit kell lefordítani.

1. A <pre> belsejében lévő mintakimenet le lett fordítva

A mintánkban szereplő kódblokk egy programkimeneti sorral végződik:

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

Mind a hat teljes fájlos és utasításos futásban a modell # 导出完成：128 本书 szöveget adott vissza azon a soron, beleértve azt a három futást is, ahol a prompt azt mondta, hogy ne változtasson semmin a <pre> belsejében. Magához a parancshoz soha nem nyúlt. A modell megjegyzésként kezelte a sort, és a megjegyzések fordítása ésszerű választás egy útmutatóban. De ez a sor az, amit a program kiír, és az olvasó, aki összeveti a termináljával, angolul fogja látni. Fordítás előtt döntsd el, hogy a mintakimenetet és a kódmegjegyzéseket lefordítod-e, és mondd meg az eszköznek, vagy védd teljesen a <pre> blokkokat.

A teljes fájlos futások lefordították a <style> blokkban lévő CSS content: "Note: " értékét is, míg az utasításos futások, amelyeknek azt mondták, hogy hagyják békén a <style>-et, angolul hagyták. Egyik sem hibás önmagában. A stíluslap fordítása helyes egy olyan oldalon, ahol a CSS beágyazott, és helytelen egy olyan webhelyen, ahol egy közös stíluslap szolgál ki minden nyelvet. Akárhogy is, ez egy döntés, amit valakinek meg kell hoznia, nem egy részlet, amit egy modellnek ki kellene találnia.

2. Az akadálymentesítési címkék kimaradtak

A morzsanavigáció <nav aria-label="Breadcrumb">. A képernyőolvasó bemondja ezt a címkét; a látó olvasók soha nem látják. Mind a hat teljes fájlos és utasításos futásban angolul maradt, pedig az utasításos prompt az aria-label-t a fordítandó attribútumok között sorolta fel. Egy utasításos futásban a keresőgomb aria-label="Search" értéke is angolul maradt.

A szegmensmódszer minden alkalommal lefordította, mert a szkriptje összegyűjtött minden aria-label, alt, title és placeholder értéket, és mindegyiket külön kérte. Ez a legerősebb érv amellett, hogy szándékosan kinyerjük a szöveges attribútumokat, ahelyett hogy reménykednénk, hogy a modell észreveszi őket.

3. A darabokra bontás megtartotta a címkéket, de elrontotta a mondatot

A szegmensmódszer a szerkezetéből adódóan biztonságos a jelölőkód szempontjából: a modell soha nem lát egyetlen címkét sem, így nem tud kárt tenni bennük. Mindhárom futásban átment minden szerkezeti ellenőrzésen. Ugyanakkor ez a módszer adta a teszt egyetlen olyan fordítását, amely helytelen utasítást adott az olvasónak.

Az angol mondat így szól: „Type the path to the <library> folder after --out.” A beágyazott <code> három darabra bontja: „Type the path to the”, „folder after” és egy pont. A kínai más szórendet használ, ezért a fordítónak át kell helyeznie a két kódelemet. A szegmensmódszer nem tudja áthelyezni őket. Mindhárom futás megfordította az utasítást. A 2. futás ezt eredményezte (az 1. és 3. futásban 后 szerepel 之后 helyett, azonos jelentéssel):

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

Ez így olvasható: „a <library> után írja be a --out mappa elérési útját”, ami az utasítás fordítottja. Mind a hat teljes fájlos és utasításos futás áthelyezte a kódelemeket, és helyesen fordított:

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

Ugyanez a felosztás felesleges szóközöket hagyott ott, ahol egy címke kínai szöveggel találkozik, például 前往 <b>设置</b> és <b>书库</b> ， formában, mindhárom szegmensfutásban, futásonként hat helyen. A böngésző ezeket látható hézagokként jeleníti meg, a kínai írásjelek előtt is. A teljes fájlos futásokban egyáltalán nem voltak ilyenek; a három utasításos futás közül kettőben négy vagy öt volt.

Egy szerkezeti ellenőrző nem tudja elkapni a megfordított mondatot, mert minden címke pontosan ott van, ahol volt. Az ellenőrzőnk jelzi, ha a beágyazott kód sorrendje megváltozik, ami sok nyelvnél normális, de ez a figyelmeztetés nem tud különbséget tenni helyes és helytelen között. Ebben a tesztben mind a hat helyes fordításnál jelzett, a három helytelen esetében pedig hallgatott, mert a helytelenek megtartották az angol szórendet. Ezt csak egy ember tudja megállapítani a mondat elolvasásával. A megoldás az, hogy teljes mondatokat küldünk a fordítónak a beágyazott címkéikkel együtt, ahogy a teljes fájlos futások tették, és utána ellenőrizzük a szerkezetet.

Kisebb eltérések

• lang: a teljes fájlos futások maguktól zh-CN-re változtatták. Az utasításos futások a kért módon zh-Hans-t használtak. Mindkettő érvényes nyelvcímke; a zh-Hans az írásmódot (egyszerűsített kínai) nevezi meg, a zh-CN egy régiót. A W3C nyelvdeklarációkra vonatkozó útmutatása azt javasolja, hogy a nyelvet a <html> elemen deklaráljuk, és ne Content-Language meta címkével.
• JSON-LD: a teljes fájlos és utasításos futások lefordították a name és description értékeket, és érvényben tartották a JSON-t. A szegmensszkriptünk kihagyta a <script> tartalmát, így annak strukturált adatai angolul maradtak, ami ugyanígy történik egy szkripteket figyelmen kívül hagyó eszköznél is.
• Karakterhivatkozások: a teljes fájlos és utasításos futások megtartották a ›,  , © és az emoji-hivatkozást úgy, ahogy le volt írva. E hat futás közül öt kínai szavakkal írta át a 2–5 tartományt (2 到 5 vagy 2 至 5); egy utasításos futás sima gondolatjelet írt a hivatkozás helyett, pedig az utasítása azt kérte, hogy tartsa meg a hivatkozásokat. A szegmensszkriptünk mindegyiket dekódolta, és karakterekként írta vissza, ami ugyanúgy jelenik meg. Az egyetlen lényeges eset, a <code> belsejében lévő <library>, mind a kilenc futásban escape-elve maradt.

A fordítás előtt: készítse elő a fájlt

1. Jelölje meg, minek nem szabad megváltoznia. Tegyen translate="no" attribútumot a terméknevekre, típusszámokra, a prózaszövegben előforduló kódszerű karakterláncokra és minden másra, aminek változatlannak kell maradnia. Ez az HTML része, semmibe nem kerül, és a modell mind a hat futásban tiszteletben tartotta, amelyik megkapta a teljes fájlt. Az ezt olvasó szegmenseszközök, mint a mi szkriptünk, teljesen kihagyják ezeket az elemeket. A fordításból kihagyandó elemekről szóló útmutatónk segít eldönteni, mi kerüljön erre a listára.
2. Döntse el a kódra vonatkozó szabályt. Lefordítjuk a kódmegjegyzéseket? A mintakimenetet? A stíluslap közös a nyelvek között? Írja le a választ, együtt a változatlanul hagyandó nevekkel, egy fordítási szójegyzékben, és adja oda annak, aki vagy ami fordít.
3. Tartsa meg az azonosítókat a forrásnyelven. Az oldalon belüli hivatkozások id értékekre mutatnak. Ha valaki lefordít egy id-t, minden rá mutató hivatkozás eltörik. Egyik futásunkban sem történt ilyen, de egy „segítőkész” fordító, aki lokalizálja a horgonyokat, meg fogja tenni.
4. Gyűjtse össze a rejtett szöveget. Sorolja fel a szavakat tartalmazó attribútumokat: alt, title, placeholder, aria-label, a gombokon lévő value, a meta címkék és a JSON-LD, hogy ellenőrizve legyenek, és ne feledkezzen el róluk.
5. Ne fordítsa le a JavaScript-karakterláncokat helyben. A szkript által beállított üzenetek, például egy alert vagy egy kódban létrehozott gombfelirat, külön lokalizációs lépést igényelnek a kódban. A hat teljes fájlos vagy utasításos futás egyike sem változtatta meg a szkriptblokkunkat, ami helyes, de ez azt jelenti, hogy ezek a karakterláncok angolul maradnak.

A fordítás után: ellenőrizze

1. Futtassa a szerkezeti ellenőrzést.

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

   Összehasonlítja a címkéket és sorrendjüket, minden olyan attribútumot, amely nem olvasóknak szóló szöveg, a <pre>, <script> és <style> tartalmát, a beágyazott kódot, a JSON-LD kulcsokat, a translate="no" szöveget, a megjegyzéseket és az oldalon belüli hivatkozásokat. Figyelmeztet az angolul maradt szövegattribútumokra, a várt értéktől eltérő lang értékre, a láthatóan lefordítatlan szövegre, a sorrendet változtató beágyazott kódra, valamint a kínai, japán vagy koreai szöveg közötti szóközökre egy beágyazott címke mentén. Nem ítéli meg a fordítás minőségét.

2. Olvasson el minden mondatot, amely beágyazott címkét tartalmaz. A tesztünkben itt sérült a jelentés. Ne hagyatkozzon az ellenőrző „beágyazott kód átrendezve” figyelmeztetésére ezeknek a mondatoknak a megtalálásához: a tesztünkben éppen a helytelen fordítások tartották meg az eredeti sorrendet.

3. Nyissa meg az oldalt böngészőben. Kattintson az oldalon belüli hivatkozásokra, ha tud, járja végig a képernyőolvasóval az űrlapot, és keressen hézagokat a félkövér és hivatkozott szövegek körül.

4. Jobbról balra író nyelveknél állítsa be a dir="rtl" attribútumot is a <html> elemen. A jobbról balra író könyvek fordításáról szóló útmutatónk leírja, mi változik még.

5. XHTML esetén, például egy EPUB belsejében lévő fejezetfájloknál, azt is ellenőrizze, hogy a fájl továbbra is jól formált XML-e, például a xmllint --noout chapter.xhtml paranccsal. A böngésző megbocsát egy lezáratlan címkét; az e-olvasó talán nem. Az EPUB-fordítás QA-ellenőrzőlistánk lefedi az e-könyv többi részét.

Hogyan illeszkedik ide a BookTranslator

A BookTranslator feltöltési oldala elfogad .html, .htm és .xhtml fájlokat is a könyvek és dokumentumok mellett, így egy mentett oldalt vagy egy statikus súgócikket egyetlen fájlként tölthet fel. Ezt a mintát nem futtattuk át a BookTranslatoron ehhez a cikkhez, és nem teszteltük, hogyan kezeli a beágyazott kód sorrendjét, a CSS-tartalmat vagy a JSON-LD-t, ezért ugyanúgy ellenőrizze a kimenetét, ahogy bármely más eszközét ellenőrizné. Az árat a fizetés előtt látja.

Bármit is használ, az előkészítő lépéseket a fordítás előtt, az ellenőrzéseket pedig utána végezze el. Egy oldal, amelyen minden tag sértetlen, még mindig rossz dolgot írhat elő az olvasónak. Ha a HTML valójában Markdownban írt dokumentáció, akkor forrásformátumként a Markdown-fordítási útmutatónk foglalkozik vele.

Töltse le a tesztfájlokat

A teszt minden anyaga szabadon felhasználható:

• sample-source.html: az 59 soros angol minta;
• check_html_translation.py: a szerkezeti ellenőrző (csak Python szabványos könyvtár);
• run_llm_html_test.py: a három módszer, bármely OpenAI-kompatibilis helyi szerverhez;
• a kilenc kimenet az outputs mappában, a check-results.txt és a results.csv fájlokkal együtt.