Jak přeložit HTML soubor bez porušení značek, atributů nebo odkazů

Chcete-li přeložit HTML soubor, překládejte text, který lidé čtou, a atributy, které nesou slova určená čtenáři, jako jsou alt, title, placeholder, aria-label a meta popis stránky. Značkování nechte být: názvy značek, href, src, id, class, skripty, styly a cokoli označeného translate="no". Poté změňte jednu hodnotu, na kterou se snadno zapomíná – atribut lang na prvku <html> – aby prohlížeče, čtečky obrazovky a vyhledávače věděly, v jakém jazyce stránka nyní je.

Zachování značek se ukázalo jako ta snadná část. Přeložili jsme 59řádkovou HTML nápovědu do zjednodušené čínštiny devětkrát pomocí lokálního modelu, třemi metodami, a každý výstup zkontrolovali skriptem. Každý běh zachoval všechny značky, odkazy i ID. Co se pokazilo, bylo tišší: model přeložil řádek uvnitř bloku kódu <pre> ve všech šesti bězích, které odeslaly celý soubor, ve všech šesti nechal aria-label navigace v angličtině a metoda, která ze své podstaty udržuje značkování nejbezpečněji – překlad textových částí jednu po druhé – vytvořila ve všech třech svých bězích větu, která čtenáři říkala, aby udělal špatnou věc.

Rychlá odpověď: Co překládat a co nechat být

Tento seznam není náš výmysl. Sekce HTML Standard o atributu translate definuje „překladatelné atributy“: title na každém prvku, alt na obrázcích, placeholder na vstupech, content na prvcích meta, jejichž název je znám jako překladatelný, a lang, u kterého uvádí, že musí být změněn tak, aby odpovídal novému jazyku. Jako příklad atributu, který mohou přidat jiné specifikace, uvádí také ARIA aria-label a říká, že v prvku s translate="no" mají být text a hodnoty atributů „ponechány tak, jak jsou, když je stránka lokalizována“.

Co jsme testovali

Napsali jsme sample-source.html, stránku nápovědy pro stejnou fiktivní čtečku Shelfmark, kterou jsme použili v našem testu překladu Markdown. Obsahuje jeden příklad každého řádku z výše uvedené tabulky a několik pastí:

• větu rozdělenou vloženými značkami: „Before you export, back up your notes. An export copies your books, but it does not delete anything from Shelfmark,“ s názvem produktu uvnitř translate="no";
• větu se dvěma vloženými prvky <code>, jejichž pořadí je důležité: „Type the path to the <library> folder after --out“;
• blok <pre><code> s příkazem a jedním řádkem ukázkového výstupu, # Export finished: 128 books;
• pravidlo CSS, které před odstavec vkládá slovo „Note:“;
• odkaz na stránce na #choose-format, odkaz mailto:, vyhledávací formulář a blok JSON-LD.

Poté jsme požádali lokální model, aby to přeložil do zjednodušené čínštiny třemi způsoby:

1. Celý soubor. Vložte celý soubor a požádejte o vrácení přeloženého souboru.
2. S instrukcemi. Totéž plus osm pravidel: zachovat každý název značky a atributu, neměnit href, src, id, class a podobné hodnoty, přeložit uvedené textové atributy a meta značky, ponechat <code>, <pre>, <script> a <style> na pokoji kromě JSON-LD name a description, respektovat translate="no", zachovat odkazy na znaky a komentáře a nastavit lang na zh-Hans.
3. Segmenty. Přístup nástrojů, které extrahují text z HTML: skript rozdělí soubor na značky a text, přeskočí <code>, <pre>, <script>, <style> a prvky s translate="no", odešle zbývající textové části a textové atributy modelu jako číslovaný seznam JSON a zapíše překlady zpět do nezměněného značkování. Sám také nastaví lang="zh-Hans".

Model byl Qwen 3.6 27B (Q4_K_M) v LM Studio, s vypnutým myšlením a teplotou 0,3, na Apple M4 Max s 64 GB paměti. Každou metodu jsme spustili třikrát, celkem devět běhů, dne 27. října 2026. Skript je run_llm_html_test.py a všech devět výstupů je zveřejněno bez úprav; README uvádí každý soubor. Pokud jste ještě nenastavili lokální model, naše příručka pro překlad s lokálním LLM pokrývá nastavení.

Byl to malý test jednoho modelu, jednoho jazykového páru a jedné stránky. Ukazuje, jaké problémy nastávají a jak je odhalit. Neřadí modely ani nástroje.

Výsledek: Značkování přežilo; tři rozhodnutí ne

Každý výstup jsme zkontrolovali pomocí check_html_translation.py, kontroloru, který používá pouze standardní knihovnu Pythonu. Celý výstup je v check-results.txt a results.csv obsahuje jeden řádek na každé spuštění.

Každý z devíti běhů zachoval stejných 58 tagů ve stejném pořadí, každý href, src, id a class, cíl odkazu na stránce, komentář, escapovaný <library> a název produktu uvnitř translate="no". Pokud jste se obávali, že model rozbije značkování jednoduché stránky, nestalo se tak. Problémy byly všechny v tom, co překládat.

1. Ukázkový výstup uvnitř <pre> byl přeložen

Blok kódu v naší ukázce končí řádkem výstupu programu:

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

Ve všech šesti bězích s celým souborem a s instrukcemi model vrátil na tomto řádku # 导出完成：128 本书, včetně tří běhů, kde prompt říkal, aby se nic uvnitř <pre> neměnilo. Samotného příkazu se to nikdy nedotklo. Model považoval řádek za komentář a překládat komentáře je v tutoriálu rozumná volba. Ale tento řádek je to, co program vypisuje, a čtenář, který si ho porovná se svým terminálem, uvidí angličtinu. Před překladem se rozhodněte, zda se ukázkový výstup a komentáře v kódu překládají, a řekněte to nástroji, nebo bloky <pre> zcela chraňte.

Běhy s celým souborem také přeložily CSS content: "Note: " v bloku <style>, zatímco běhy s instrukcemi, kterým bylo řečeno nechat <style> na pokoji, jej ponechaly v angličtině. Ani jedno není samo o sobě špatně. Překládat stylesheet je správné pro stránku, kde je CSS inline, a špatné pro web, kde jeden sdílený stylesheet slouží všem jazykům. Ať tak či onak, je to rozhodnutí, které musí někdo udělat, ne detail, který by měl model hádat.

2. Popisky pro přístupnost byly vynechány

Navigace s drobečkovou navigací je <nav aria-label="Breadcrumb">. Čtečka obrazovky tento popisek oznamuje; vidící čtenáři ho nikdy nevidí. Ve všech šesti bězích s celým souborem a s instrukcemi zůstal v angličtině, i když prompt s instrukcemi uváděl aria-label mezi atributy k překladu. V jednom běhu s instrukcemi zůstal v angličtině i aria-label="Search" u tlačítka vyhledávání.

Metoda segmentů jej přeložila pokaždé, protože její skript shromáždil každou hodnotu aria-label, alt, title a placeholder a každou explicitně zadal k překladu. To je nejsilnější argument pro cílené extrahování textových atributů, místo spoléhání na to, že si jich model všimne.

3. Překlad po částech zachoval značky, ale rozbil větu

Metoda segmentace je pro značkování bezpečná už ze své podstaty: model nikdy nevidí značku, takže ji nemůže poškodit. Prošla všemi strukturálními kontrolami ve všech třech bězích. Také však vytvořila jediný překlad v testu, který dal čtenáři nesprávné pokyny.

Anglická věta zní: „Type the path to the <library> folder after --out.“ Inline <code> ji rozdělí na tři části: „Type the path to the“, „folder after“ a tečku. Čeština staví tato slova v jiném pořadí, takže překladatel musí oba kódové prvky přesunout. Metoda segmentace je přesunout nedokáže. Všechny tři běhy pokyn obrátily. Běh 2 vytvořil toto (běhy 1 a 3 uvádějí 后 místo 之后 se stejným významem):

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

To znamená „after <library>, type the path of the --out folder“, tedy opak pokynu. Všech šest běhů s celým souborem a s pokyny kódové prvky přesunulo a mělo to správně:

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

Stejné dělení zanechalo ve všech třech segmentovaných bězích volné mezery tam, kde se značka stýká s čínským textem, například 前往 <b>设置</b> a <b>书库</b> ，, šest míst na běh. Prohlížeč je zobrazí jako viditelné mezery, včetně mezery před čínskou interpunkcí. Běhy s celým souborem žádné neměly; dva ze tří běhů s pokyny měly čtyři nebo pět.

Strukturální kontrola obrácenou větu odhalit nedokáže, protože každá značka je přesně tam, kde byla. Náš kontrolor hlásí, když inline kód změní pořadí, což je pro mnoho jazyků normální, ale toto varování nedokáže rozlišit správné od nesprávného. V tomto testu se spustilo u všech šesti správných překladů a mlčelo u tří nesprávných, protože ty nesprávné zachovaly anglické pořadí. Pozná to jen člověk, který větu čte. Řešením je posílat překladateli celé věty s jejich inline značkami, což dělaly běhy s celým souborem, a strukturu kontrolovat afterwards.

Menší rozdíly

• lang: běhy s celým souborem jej samy změnily na zh-CN. Běhy s pokyny použily zh-Hans, jak bylo požadováno. Oba jsou platné jazykové značky; zh-Hans pojmenovává písmo (zjednodušená čínština), zh-CN pojmenovává oblast. Pokyny W3C k deklaracím jazyka doporučují deklarovat jazyk na prvku <html>, a ne meta značkou Content-Language.
• JSON-LD: běhy s celým souborem a s pokyny přeložily hodnoty name a description a JSON zůstal platný. Náš segmentační skript obsah <script> přeskakoval, takže jeho strukturovaná data zůstala v angličtině, což je přesně to, jak se zachová i nástroj, který skripty ignoruje.
• Odkazy na znaky: běhy s celým souborem a s pokyny zachovaly ›,  , © a odkaz na emoji tak, jak byly napsány. Pět z těchto šesti běhů přepsalo rozsah 2–5 čínskými slovy (2 到 5 nebo 2 至 5); jeden běh s pokyny napsal místo odkazu obyčejnou pomlčku, přestože jeho prompt říkal, aby odkazy zachoval. Náš segmentační skript všechny dekódoval a zapsal zpět znaky, což se zobrazí stejně. Ten důležitý, <library> uvnitř <code>, zůstal escapovaný ve všech devíti bězích.

Než začnete překládat: připravte soubor

1. Označte, co se nesmí změnit. Dejte translate="no" na názvy produktů, čísla modelů, řetězce podobné kódu v próze a na cokoli dalšího, co musí zůstat tak, jak je. Je to součást HTML, nic to nestojí a model to respektoval ve všech šesti bězích, které dostaly celý soubor. Segmentační nástroje, které to čtou, jako náš skript, tyto prvky úplně přeskakují. Náš průvodce nepřekládaným obsahem pokrývá, jak rozhodnout, co na tento seznam patří.
2. Rozhodněte o politice kódu. Překládají se komentáře v kódu? Překládá se ukázkový výstup? Sdílí se stylopis mezi jazyky? Odpověď zapište spolu s názvy, které se nesmí změnit, do překladatelského slovníku a dejte ji tomu, kdo nebo co překládá.
3. Ponechte ID ve zdrojovém jazyce. Odkazy v rámci stránky ukazují na hodnoty id. Pokud někdo přeloží id, každý odkaz na něj se rozbije. Žádný z našich běhů to neudělal, ale překladatel, který „ochotně“ lokalizuje kotvy, to udělá.
4. Shromážděte skrytý text. Vypište atributy, které obsahují slova: alt, title, placeholder, aria-label, value u tlačítek, meta značky a JSON-LD, aby byly zkontrolovány a nezapomenuty.
5. Nepřekládejte řetězce JavaScriptu na místě. Zprávy nastavené skriptem, jako je upozornění nebo popisek tlačítka vytvořený v kódu, potřebují samostatný lokalizační krok v kódu. Žádný ze šesti běhů s celým souborem nebo s pokyny nezměnil náš blok skriptu, což je správně, ale znamená to, že tyto řetězce zůstávají v angličtině.

Po překladu: zkontrolujte to

1. Spusťte strukturální kontrolu.

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

   Porovnává značky a jejich pořadí, každý atribut, který není textem pro čtenáře, obsah <pre>, <script> a <style>, inline kód, klíče JSON-LD, text s translate="no", komentáře a odkazy v rámci stránky. Varuje před textovými atributy, které zůstaly v angličtině, hodnotou lang, která se liší od očekávané, viditelným textem, který vypadá nepřeloženě, inline kódem, který změnil pořadí, a mezerami mezi čínským, japonským nebo korejským textem přes inline značku. Nehodnotí kvalitu překladu.

2. Přečtěte každou větu, která obsahuje inline značku. Tady se v našem testu zlomil význam. Nespoléhejte na varování kontroloru „inline kód přeuspořádán“, abyste tyto věty našli: v našem testu byly nesprávné překlady právě ty, které zachovaly původní pořadí.

3. Otevřete stránku v prohlížeči. Klikejte na odkazy v rámci stránky, projděte formulář čtečkou obrazovky, pokud můžete, a hledejte mezery kolem tučného a odkazovaného textu.

4. U jazyků psaných zprava doleva také nastavte dir="rtl" na prvku <html>. Náš průvodce překladem knih RTL pokrývá, co dalšího se mění.

5. U XHTML, jako jsou soubory kapitol uvnitř EPUB, také ověřte, že soubor je stále dobře utvořené XML, například pomocí xmllint --noout chapter.xhtml. Prohlížeč neuzavřenou značku odpustí; čtečka e-knih možná ne. Náš kontrolní seznam QA pro překlad EPUB pokrývá zbytek e-knihy.

Kam zapadá BookTranslator

Nahrávací stránka BookTranslatoru přijímá soubory .html, .htm a .xhtml vedle knih a dokumentů, takže můžete nahrát uloženou stránku nebo statický článek nápovědy jako celý soubor. Tento vzorek jsme pro tento článek neproháněli přes BookTranslator a netestovali jsme, jak si poradí s pořadím inline kódu, obsahem CSS nebo JSON-LD, takže jeho výstup zkontrolujte stejně jako u jakéhokoli jiného nástroje. Cenu vidíte před zaplacením.

Ať už použijete cokoli, proveďte přípravné kroky před překladem a kontroly po něm. Stránka se všemi neporušenými značkami může čtenáři stále říkat, aby napsal něco špatného. Pokud je vaše HTML ve skutečnosti dokumentace napsaná v Markdownu, náš průvodce překladem Markdownu se zabývá zdrojovým formátem.

Získejte testovací soubory

Vše z tohoto testu lze zdarma znovu použít:

• sample-source.html: anglický vzorek o 59 řádcích;
• check_html_translation.py: nástroj pro strukturální kontrolu (pouze standardní knihovna Pythonu);
• run_llm_html_test.py: tři metody pro jakýkoli lokální server kompatibilní s OpenAI;
• devět výstupů ve složce outputs, spolu s check-results.txt a results.csv.