Kako prevesti HTML datoteku bez razbijanja oznaka, atributa ili poveznica

Da biste preveli HTML datoteku, prevedite tekst koji ljudi čitaju i atribute koji sadrže riječi namijenjene čitatelju, poput alt, title, placeholder, aria-label i meta opisa stranice. Ostavite oznake na miru: nazive oznaka, href, src, id, class, skripte, stilove i sve što je označeno s translate="no". Zatim promijenite jednu vrijednost koju je lako zaboraviti, atribut lang na elementu <html>, kako bi preglednici, čitači zaslona i tražilice znali na kojem je jeziku stranica sada.

Očuvanje oznaka pokazalo se lakšim dijelom. Preveli smo 59-rednu HTML stranicu pomoći na pojednostavljeni kineski devet puta pomoću lokalnog modela, koristeći tri metode, i svaki smo izlaz provjerili skriptom. Svako pokretanje zadržalo je svaku oznaku, poveznicu i ID. Ono što je pošlo po zlu bilo je tiše: model je preveo jedan redak unutar <pre> bloka koda u svih šest pokretanja koja su poslala cijelu datoteku, ostavio je navigacijski aria-label na engleskom u svih šest, a metoda koja po dizajnu najsigurnije čuva oznake, prevođenje tekstualnih dijelova jedan po jedan, proizvela je rečenicu koja je čitatelju rekla da učini pogrešnu stvar u sva tri svoja pokretanja.

Kratki odgovor: što prevoditi, a što ostaviti na miru

Ovaj popis nije naša izmišljotina. Odjeljak HTML standarda o atributu translate definira "prevedive atribute": title na svakom elementu, alt na slikama, placeholder na inputima, content na meta elementima čiji je naziv poznat kao prevediv, te lang, za koji kaže da se mora promijeniti kako bi odgovarao novom jeziku. Također navodi ARIA-in aria-label kao primjer atributa koji mogu dodati druge specifikacije i kaže da se u elementu s translate="no" tekst i vrijednosti atributa "ostavljaju kakvi jesu kada se stranica lokalizira".

Što smo testirali

Napisali smo sample-source.html, stranicu centra za pomoć za istu izmišljenu aplikaciju za čitanje, Shelfmark, koju smo koristili u našem testu prevođenja Markdowna. Sadrži po jedan primjer svakog retka iz gornje tablice, plus nekoliko zamki:

• rečenicu podijeljenu inline oznakama: "Prije izvoza sigurnosno kopirajte svoje bilješke. Izvoz kopira vaše knjige, ali ne briše ništa iz Shelfmarka," s imenom proizvoda unutar translate="no";
• rečenicu s dva inline <code> elementa čiji je redoslijed važan: "Upišite putanju do mape <library> nakon --out";
• blok <pre><code> s naredbom i jednim retkom primjera izlaza, # Export finished: 128 books;
• CSS pravilo koje umeće riječ "Napomena:" prije odlomka;
• link unutar stranice na #choose-format, mailto: link, obrazac za pretraživanje i JSON-LD blok.

Zatim smo zamolili lokalni model da to prevede na pojednostavljeni kineski na tri načina:

1. Cijela datoteka. Zalijepite cijelu datoteku i zatražite prevedenu datoteku natrag.
2. S uputama. Isto, plus osam pravila: zadržite svaki naziv oznake i atributa, ne mijenjajte href, src, id, class i slične vrijednosti, prevedite navedene tekstualne atribute i meta oznake, ostavite <code>, <pre>, <script> i <style> na miru osim JSON-LD name i description, poštujte translate="no", zadržite znakovne reference i komentare te postavite lang na zh-Hans.
3. Segmenti. Pristup alata koji izvlače tekst iz HTML-a: skripta dijeli datoteku na oznake i tekst, preskače <code>, <pre>, <script>, <style> i elemente s translate="no", šalje preostale tekstualne dijelove i tekstualne atribute modelu kao numerirani JSON popis i upisuje prijevode natrag u netaknuti markup. Također sama postavlja lang="zh-Hans".

Model je bio Qwen 3.6 27B (Q4_K_M) u LM Studiju, s isključenim razmišljanjem i temperaturom 0,3, na Apple M4 Max sa 64 GB memorije. Svaku metodu pokrenuli smo tri puta, ukupno devet pokretanja, 27. listopada 2026. Skripta je run_llm_html_test.py, a svih devet izlaza objavljeno je neuređeno; README navodi svaku datoteku. Ako još niste postavili lokalni model, naš vodič za lokalno prevođenje LLM-om pokriva postavke.

Ovo je bio mali test jednog modela, jednog jezičnog para i jedne stranice. Pokazuje koji se problemi događaju i kako ih uhvatiti. Ne rangira modele ni alate.

Rezultat: Markup je preživio; tri odluke nisu

Svaki smo izlaz provjerili pomoću check_html_translation.py, alata za provjeru koji koristi samo Pythonovu standardnu biblioteku. Cjelokupni izlaz nalazi se u check-results.txt, a results.csv sadrži jedan redak po pokretanju.

Svih devet pokretanja zadržalo je istih 58 tagova u istom redoslijedu, svaki href, src, id i class, cilj unutarnje poveznice, komentar, escapeani <library> i naziv proizvoda unutar translate="no". Ako ste se brinuli da će model iskriviti označavanje jednostavne stranice, nije. Problemi su bili isključivo u tome što treba prevesti.

1. Primjer izlaza unutar <pre> je preveden

Blok koda u našem primjeru završava retkom programskog izlaza:

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

U svih šest pokretanja na cijeloj datoteci i s uputama, model je na tom retku vratio # 导出完成：128 本书, uključujući tri pokretanja u kojima je prompt naložio da se ništa unutar <pre> ne mijenja. Sama naredba nikada nije dirana. Model je taj redak tretirao kao komentar, a prevođenje komentara razuman je izbor u tutorijalu. No ovaj redak je ono što program ispisuje, pa će čitatelj koji ga usporedi sa svojim terminalom vidjeti engleski. Odlučite prije prevođenja hoće li se primjeri izlaza i komentari u kodu prevoditi i recite to alatu ili u potpunosti zaštitite <pre> blokove.

Pokretanja na cijeloj datoteci također su prevela CSS content: "Note: " u bloku <style>, dok su ga pokretanja s uputama, kojima je rečeno da <style> ostave na miru, zadržala na engleskom. Ni jedno ni drugo samo po sebi nije pogrešno. Prevođenje stilova ispravno je za stranicu na kojoj je CSS umetnut, a pogrešno za site na kojem jedna zajednička stilova služi svim jezicima. U svakom slučaju, to je odluka koju netko mora donijeti, a ne detalj koji model treba nagađati.

2. Oznake pristupačnosti su preskočene

Navigacija za krušne mrvice je <nav aria-label="Breadcrumb">. Čitač zaslona izgovara tu oznaku; čitatelji koji vide nikada je ne vide. U svih šest pokretanja na cijeloj datoteci i s uputama ostala je na engleskom, iako je prompt s uputama naveo aria-label među atributima za prevođenje. U jednom pokretanju s uputama i aria-label="Search" gumba za pretraživanje ostao je na engleskom.

Metoda segmenata prevela ga je svaki put jer je njezina skripta prikupila svaku vrijednost aria-label, alt, title i placeholder i zatražila prijevod svake pojedinačno. To je najjači argument za namjerno izdvajanje tekstualnih atributa umjesto nade da će ih model primijetiti.

3. Prevođenje dijelova sačuvalo je oznake, ali je slomilo rečenicu

Metoda segmenata je sigurna za oznake po konstrukciji: model nikada ne vidi oznaku pa je ne može oštetiti. Prošla je sve strukturne provjere u sva tri pokretanja. Također je proizvela jedini prijevod u testu koji je čitatelju dao pogrešne upute.

Engleska rečenica glasi: "Type the path to the <library> folder after --out." Umetnuti <code> dijeli je na tri dijela: "Type the path to the", "folder after" i točku. Kineski slaže te riječi drugačijim redoslijedom pa prevoditelj mora premjestiti dva elementa koda. Metoda segmenata ne može ih premjestiti. Sva tri pokretanja obrnula su uputu. Pokretanje 2 dalo je ovo (pokretanja 1 i 3 kažu 后 umjesto 之后, istog značenja):

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

To znači "nakon <library> upišite putanju mape --out", obrnuto od upute. Svih šest pokretanja s cijelom datotekom i s uputama premjestilo je elemente koda i dobilo točan rezultat:

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

Isto je dijeljenje ostavilo suvišne razmake gdje se oznaka spaja s kineskim tekstom, poput 前往 <b>设置</b> i <b>书库</b> ，, u sva tri pokretanja sa segmentima, šest mjesta po pokretanju. Preglednik ih prikazuje kao vidljive praznine, uključujući i prije kineskog interpunkcijskog znaka. Pokretanja s cijelom datotekom nisu imala nijednu; dva od tri pokretanja s uputama imala su četiri ili pet.

Strukturni provjeravač ne može uhvatiti obrnutu rečenicu jer je svaka oznaka točno tamo gdje je bila. Naš provjeravač prijavljuje kada umetnuti kod promijeni redoslijed, što je normalno za mnoge jezike, ali to upozorenje ne razlikuje ispravno od neispravnog. U ovom testu aktiviralo se na svih šest točnih prijevoda, a ostalo nijemo na tri pogrešna jer su pogrešni zadržali engleski redoslijed. Samo osoba koja čita rečenicu može to prepoznati. Rješenje je prevoditelju slati cijele rečenice s njihovim umetnutim oznakama, što su pokretanja s cijelom datotekom i činila, te nakon toga provjeriti strukturu.

Manje razlike

• lang: pokretanja s cijelom datotekom sama su ga promijenila u zh-CN. Pokretanja s uputama upotrijebila su zh-Hans, kako je zatraženo. Oba su valjane oznake jezika; zh-Hans imenuje pismo (pojednostavljeni kineski), a zh-CN imenuje regiju. W3C-ove smjernice o deklariranju jezika preporučuju deklariranje jezika na elementu <html>, a ne meta oznakom Content-Language.
• JSON-LD: pokretanja s cijelom datotekom i s uputama prevela su vrijednosti name i description i zadržala valjan JSON. Naša skripta za segmente preskočila je sadržaj <script> pa su njegovi strukturirani podaci ostali na engleskom, što je i ponašanje alata koji zanemaruje skripte.
• Znakovne reference: pokretanja s cijelom datotekom i s uputama zadržala su ›,  , © i referencu za emoji kako su napisane. Pet od tih šest pokretanja prepisalo je raspon 2–5 kineskim riječima (2 到 5 ili 2 至 5); jedno pokretanje s uputama napisalo je običnu crticu umjesto reference, iako je njegov upit naložio zadržavanje referenci. Naša skripta za segmente dekodirala je sve njih i zapisala znakove natrag, što se prikazuje isto. Ono što je važno, <library> unutar <code>, ostalo je escapeano u svih devet pokretanja.

Prije prevođenja: pripremite datoteku

1. Označite što se ne smije mijenjati. Stavite translate="no" na nazive proizvoda, brojeve modela, nizove nalik kodu u prozi i sve ostalo što mora ostati kako jest. Dio je HTML-a, ne košta ništa, a model ga je poštovao u svih šest pokretanja kojima je poslana cijela datoteka. Alati za segmente koji to čitaju, poput naše skripte, u potpunosti preskaču te elemente. Naš vodič o tome što ne prevoditi objašnjava kako odlučiti što ide na taj popis.
2. Odredite pravila za kod. Prevode li se komentari u kodu? A ogledni izlaz? Dijeli li se stilski list među jezicima? Zapišite odgovor, zajedno s nazivima koji se ne smiju mijenjati, u glosar za prevođenje i dajte ga onome tko ili što prevodi.
3. Zadržite ID-ove na izvornom jeziku. Veze unutar stranice pokazuju na vrijednosti id. Ako netko prevede id, svaka veza na njega puca. Nijedno naše pokretanje to nije učinilo, ali prevoditelj koji "uslužno" lokalizira sidra hoće.
4. Prikupite skriveni tekst. Popišite atribute koji sadrže riječi, alt, title, placeholder, aria-label, value na gumbima, meta oznake i JSON-LD, kako bi se provjerili i ne bi bili zaboravljeni.
5. Ne prevodite JavaScript nizove na mjestu. Poruke koje postavlja skripta, poput upozorenja ili oznake gumba stvorene u kodu, zahtijevaju zaseban korak lokalizacije u kodu. Nijedno od šest pokretanja s cijelom datotekom ili s uputama nije promijenilo naš blok skripte, što je ispravno, ali to znači da ti nizovi ostaju na engleskom.

Nakon prevođenja: provjerite

1. Pokrenite strukturnu provjeru.

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

   Uspoređuje oznake i njihov redoslijed, svaki atribut koji nije tekst namijenjen čitatelju, sadržaj <pre>, <script> i <style>, umetnuti kod, ključeve JSON-LD, tekst s translate="no", komentare i veze unutar stranice. Upozorava na tekstualne atribute koji su još na engleskom, vrijednost lang koja se razlikuje od očekivane, vidljiv tekst koji izgleda neprevedeno, umetnuti kod koji je promijenio redoslijed i razmake između kineskog, japanskog ili korejskog teksta preko umetnute oznake. Ne procjenjuje kvalitetu prijevoda.

2. Pročitajte svaku rečenicu koja sadrži umetnutu oznaku. Tu se u našem testu slomilo značenje. Ne oslanjajte se na upozorenje provjeravača "umetnuti kod promijenio redoslijed" da biste pronašli te rečenice: u našem su testu pogrešni prijevodi bili upravo oni koji su zadržali izvorni redoslijed.

3. Otvorite stranicu u pregledniku. Kliknite veze unutar stranice, prođite kroz obrazac tipkom Tab uz čitač zaslona ako možete i potražite praznine oko podebljanog i povezanog teksta.

4. Za jezike s pisanjem zdesna nalijevo također postavite dir="rtl" na element <html>. Naš vodič za prevođenje knjiga zdesna nalijevo objašnjava što se još mijenja.

5. Za XHTML, poput datoteka poglavlja unutar EPUB-a, također potvrdite da je datoteka još valjani XML, primjerice s xmllint --noout chapter.xhtml. Preglednik oprašta nezatvorenu oznaku; čitač e-knjiga možda neće. Naš kontrolni popis za QA prijevoda EPUB-a pokriva ostatak e-knjige.

Gdje se uklapa BookTranslator

BookTranslatorova stranica za učitavanje prihvaća datoteke .html, .htm i .xhtml uz knjige i dokumente, pa možete učitati spremljenu stranicu ili statični članak pomoći kao cijelu datoteku. Ovaj primjer nismo proveli kroz BookTranslator za ovaj članak i nismo testirali kako rukuje redoslijedom ugrađenog koda, CSS sadržajem ili JSON-LD-om, stoga provjerite njegov izlaz na isti način na koji biste provjerili bilo koji drugi alat. Cijenu vidite prije plaćanja.

Što god koristili, obavite pripremne korake prije prevođenja i provjere nakon toga. Stranica sa svim netaknutim oznakama još uvijek može čitatelju reći da upiše pogrešnu stvar. Ako je vaš HTML zapravo dokumentacija napisana u Markdownu, naš vodič za prevođenje Markdowna pokriva izvorni format.

Preuzmite testne datoteke

Sve iz ovog testa slobodno je za ponovnu upotrebu:

• sample-source.html: engleski uzorak od 59 redaka;
• check_html_translation.py: strukturni provjerivač (samo Python standardna biblioteka);
• run_llm_html_test.py: tri metode, za bilo koji lokalni poslužitelj kompatibilan s OpenAI-jem;
• devet izlaza u mapi outputs, s check-results.txt i results.csv.