Как да преведете HTML файл, без да счупите тагове, атрибути или връзки

За да преведете HTML файл, преведете текста, който хората четат, и атрибутите, които съдържат думи, насочени към читателя, като alt, title, placeholder, aria-label и мета описанието на страницата. Оставете разметката непокътната: имена на тагове, href, src, id, class, скриптове, стилове и всичко, маркирано с translate="no". След това променете една стойност, която лесно се забравя – атрибута lang на елемента <html>, така че браузърите, екранните четци и търсачките да знаят на какъв език е страницата сега.

Опазването на таговете се оказа лесната част. Преведохме 59-редова HTML помощна страница на опростен китайски девет пъти с локален модел, използвайки три метода, и проверихме всеки резултат със скрипт. Всяко пускане запази всеки таг, връзка и ID. Проблемите бяха по-незабележими: моделът преведе ред вътре в кодов блок <pre> във всичките шест пускания, при които изпратихме целия файл, остави aria-label на навигацията на английски във всичките шест, а методът, който по дизайн пази разметката най-сигурно – превеждане на текстовите части една по една – създаде изречение, което казва на читателя да направи грешното нещо, във всичките три свои пускания.

Бърз отговор: какво да превеждате и какво да оставите непокътнато

Този списък не е наше изобретение. Разделът за атрибута translate в HTML стандарта дефинира „преводими атрибути“: title на всеки елемент, alt на изображенията, placeholder на полетата за въвеждане, content на meta елементи, чието име е известно като преводимо, и lang, за който се казва, че трябва да бъде променен, за да съответства на новия език. Той също така посочва aria-label на ARIA като пример за атрибут, който други спецификации могат да добавят, и казва, че в елемент с translate="no" текстът и стойностите на атрибутите „трябва да бъдат оставени както са, когато страницата се локализира.“

Какво тествахме

Написахме sample-source.html – страница от помощен център за същото измислено приложение за четене Shelfmark, което използвахме в нашия тест за превод на Markdown. Тя съдържа по един пример за всеки ред от таблицата по-горе, плюс няколко капана:

• изречение, разделено от вградени тагове: „Преди да експортирате, направете резервно копие на бележките си. Експортирането копира книгите ви, но не изтрива нищо от Shelfmark,“ като името на продукта е вътре в translate="no";
• изречение с два вградени <code> елемента, чийто ред е важен: „Въведете пътя до папката <library> след --out“;
• блок <pre><code> с команда и един ред примерно изходно съобщение, # Export finished: 128 books;
• CSS правило, което вмъква думата „Забележка:“ преди абзац;
• връзка в страницата към #choose-format, връзка mailto:, форма за търсене и JSON-LD блок.

След това помолихме локален модел да го преведе на опростен китайски по три начина:

1. Цял файл. Поставете целия файл и поискайте обратно преведения файл.
2. С инструкции. Същото, плюс осем правила: запазете всеки таг и име на атрибут, не променяйте href, src, id, class и подобни стойности, преведете изброените текстови атрибути и мета тагове, оставете <code>, <pre>, <script> и <style> без промяна с изключение на JSON-LD name и description, спазвайте translate="no", запазете символните препратки и коментарите и задайте lang на zh-Hans.
3. Сегменти. Подходът на инструментите, които извличат текст от HTML: скрипт разделя файла на тагове и текст, пропуска <code>, <pre>, <script>, <style> и елементите с translate="no", изпраща останалите текстови части и текстови атрибути на модела като номериран JSON списък и записва преводите обратно в непокътнатия markup. Той също така сам задава lang="zh-Hans".

Моделът беше Qwen 3.6 27B (Q4_K_M) в LM Studio, с изключено мислене и температура 0.3, на Apple M4 Max с 64 GB памет. Пуснахме всеки метод три пъти, общо девет пускания, на 27 октомври 2026 г. Скриптът е run_llm_html_test.py, а всичките девет изхода са публикувани без редакция; README изброява всеки файл. Ако не сте настройвали локален модел преди, нашето ръководство за превод с локален LLM покрива настройките.

Това беше малък тест на един модел, една езикова двойка и една страница. Той показва какви проблеми се случват и как да ги хванете. Не класира модели или инструменти.

Резултат: Markup-ът оцеля; три решения – не

Проверихме всеки резултат с check_html_translation.py – скрипт за проверка, който използва само стандартната библиотека на Python. Пълният изход е в check-results.txt, а results.csv съдържа по един ред за всяко изпълнение.

Всяко от деветте изпълнения запази същите 58 тага в същия ред, всеки href, src, id и class, целта на връзката в страницата, коментара, екранирания <library> и името на продукта в translate="no". Ако се притеснявахте, че моделът ще развали разметката на проста страница, той не го направи. Проблемите бяха изцяло в това какво да се преведе.

1. Примерният изход в <pre> беше преведен

Блокът с код в нашия пример завършва с ред от изхода на програмата:

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

Във всичките шест изпълнения на цял файл и с инструкции моделът върна # 导出完成：128 本书 на този ред, включително в трите изпълнения, където подсказката казваше да не се променя нищо в <pre>. Самата команда никога не беше докосвана. Моделът третира реда като коментар, а превеждането на коментари е разумен избор в урок. Но този ред е това, което програмата отпечатва, и читател, който го сравни с терминала си, ще види английски. Решете преди превода дали примерният изход и коментарите в кода се превеждат, и кажете на инструмента, или защитете напълно блоковете <pre>.

Изпълненията на цял файл също преведоха CSS content: "Note: " в блока <style>, докато изпълненията с инструкции, на които беше казано да оставят <style> на мира, го запазиха на английски. Нито едно от двете не е грешно само по себе си. Превеждането на стиловото описание е правилно за страница, където CSS е вграден, и грешно за сайт, където едно споделено стилово описание обслужва всички езици. Както и да е, това е решение, което някой трябва да вземе, а не подробност, която моделът да отгатва.

2. Етикетите за достъпност бяха пропуснати

Навигацията с трохи е <nav aria-label="Breadcrumb">. Екранният четец обявява този етикет; зрящите читатели никога не го виждат. Във всичките шест изпълнения на цял файл и с инструкции той остана на английски, въпреки че подсказката с инструкции изброяваше aria-label сред атрибутите за превод. В едно изпълнение с инструкции aria-label="Search" на бутона за търсене също остана на английски.

Методът на сегментите го превеждаше всеки път, защото неговият скрипт събираше всяка стойност на aria-label, alt, title и placeholder и питаше за всяка изрично. Това е най-силният аргумент за извличане на текстовите атрибути нарочно, вместо да се надяваме, че моделът ще ги забележи.

3. Преводът на части запази таговете, но развали изречението

Сегментният метод е безопасен за разметката по своята същност: моделът никога не вижда таг, така че не може да го повреди. Той премина всички структурни проверки и в трите пуска. Той също така произведе единствения превод в теста, който даде на читателя грешни инструкции.

Английското изречение е „Type the path to the <library> folder after --out.“ Вграденият <code> го разделя на три части: „Type the path to the“, „folder after“ и точка. Китайският поставя тези думи в различен ред, така че преводачът трябва да премести двата кодови елемента. Сегментният метод не може да ги премести. И трите пуска обърнаха инструкцията. Пусk 2 произведе това (пускове 1 и 3 казват 后 вместо 之后, със същото значение):

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

Това се чете „след <library>, въведете пътя до папката --out“, обратното на инструкцията. Всичките шест пуска с цял файл и с инструкции преместиха кодовите елементи и го направиха правилно:

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

Същото разделяне остави излишни интервали там, където таг се среща с китайски текст, като 前往 <b>设置</b> и <b>书库</b> ，, и в трите сегментни пуска, по шест места на пуск. Браузърът ги показва като видими празнини, включително преди китайска пунктуация. Пусковете с цял файл нямаха такива; два от трите пуска с инструкции имаха четири или пет.

Структурният проверяващ не може да хване обърнатото изречение, защото всеки таг е точно там, където е бил. Нашият проверяващ съобщава, когато вграденият код промени реда си, което е нормално за много езици, но това предупреждение не може да различи правилно от грешно. В този тест то се задейства при всичките шест правилни превода и остана безмълвно при трите грешни, защото грешните запазиха английския ред. Само човек, който чете изречението, може да каже. Решението е да се изпращат цели изречения, с техните вградени тагове, на преводача, което направиха пусковете с цял файл, и структурата да се проверява след това.

По-малки разлики

• lang: пусковете с цял файл го промениха на zh-CN сами. Пусковете с инструкции използваха zh-Hans, както беше поискано. И двете са валидни езикови тагове; zh-Hans именува писмеността (опростен китайски), zh-CN именува регион. Насоките на W3C за езикови декларации препоръчват да се декларира езикът на елемента <html>, а не с мета таг Content-Language.
• JSON-LD: пусковете с цял файл и с инструкции преведоха стойностите на name и description и запазиха JSON валиден. Нашият сегментен скрипт пропусна съдържанието на <script>, така че структурираните му данни останаха на английски, което е и как ще се държи инструмент, който игнорира скриптове.
• Знакови препратки: пусковете с цял файл и с инструкции запазиха ›,  , © и емоджи препратката както са написани. Пет от тези шест пуска презаписаха диапазона 2–5 с китайски думи (2 到 5 или 2 至 5); един пуск с инструкции написа обикновено тире вместо препратката, въпреки че подсказката му казваше да запази препратките. Нашият сегментен скрипт декодира всички тях и записа символите обратно, което изглежда по същия начин. Единствената, която има значение, <library> вътре в <code>, остана екранирана и в деветте пуска.

Преди да превеждате: подгответе файла

1. Отбележете какво не трябва да се променя. Поставете translate="no" на имена на продукти, номера на модели, кодоподобни низове в прозата и всичко друго, което трябва да остане както е. Това е част от HTML, не струва нищо и моделът го спази и в шестте пуска, които му изпратиха целия файл. Сегментни инструменти, които го четат, като нашия скрипт, пропускат тези елементи изцяло. Нашето ръководство за това какво да не се превежда обхваща как да решите какво да влезе в този списък.
2. Решете политиката за код. Превеждат ли се коментарите в кода? Примерният изход? Споделя ли се стиловата таблица между езиците? Запишете отговора, заедно с имената, които не трябва да се променят, в глосар за превод и го дайте на този, който или което превежда.
3. Запазете ID в изходния език. Връзките в страницата сочат към стойности на id. Ако някой преведе id, всяка връзка към него се чупи. Нито един от нашите пускове не го направи, но преводач, който „услужливо“ локализира котви, ще го направи.
4. Съберете скрития текст. Изброете атрибутите, които съдържат думи: alt, title, placeholder, aria-label, value на бутони, мета тагове и JSON-LD, за да бъдат проверени и да не бъдат забравени.
5. Не превеждайте JavaScript низове на място. Съобщенията, зададени от скрипт, като предупреждение или етикет на бутон, създаден в код, се нуждаят от отделна стъпка за локализация в кода. Нито един от шестте пуска с цял файл или с инструкции не промени нашия скриптов блок, което е правилно, но това означава, че тези низове остават на английски.

След като преведете: проверете го

1. Изпълнете структурната проверка.

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

   Тя сравнява таговете и техния ред, всеки атрибут, който не е текст за читателя, съдържанието на <pre>, <script> и <style>, вградения код, ключовете на JSON-LD, текста с translate="no", коментарите и връзките в страницата. Тя предупреждава за текстови атрибути, които все още са на английски, стойност на lang, която се различава от очакваната, видим текст, който изглежда непреведен, вграден код, който е променил реда си, и интервали между китайски, японски или корейски текст през вграден таг. Тя не съди за качеството на превода.

2. Прочетете всяко изречение, което съдържа вграден таг. Тук значението се развали в нашия тест. Не разчитайте на предупреждението на проверяващия „вграденият код е пренареден“, за да намерите тези изречения: в нашия тест грешните преводи бяха тези, които запазиха оригиналния ред.

3. Отворете страницата в браузър. Кликнете върху връзките в страницата, преминете през формуляра с екранен четец, ако можете, и потърсете празнини около удебелен и свързан текст.

4. За езици с писане от дясно на ляво също задайте dir="rtl" на елемента <html>. Нашето ръководство за превод на книги с RTL писане обхваща какво друго се променя.

5. За XHTML, като файловете с глави в EPUB, също потвърдете, че файлът все още е добре оформен XML, например с xmllint --noout chapter.xhtml. Браузърът прощава незатворен таг; електронният четец може и да не го направи. Нашият контролен списък за QA при превод на EPUB обхваща останалото за една електронна книга.

Къде се вписва BookTranslator

Страницата за качване на BookTranslator приема файлове с разширения .html, .htm и .xhtml заедно с книги и документи, така че можете да качите запазена страница или статична помощна статия като цял файл. Не сме прекарвали тази извадка през BookTranslator за тази статия и не сме тествали как се справя с реда на вградения код, CSS съдържание или JSON-LD, затова проверявайте резултата по същия начин, по който бихте проверили резултата от всеки друг инструмент. Виждате цената, преди да платите.

Каквото и да използвате, направете подготвителните стъпки преди превода и проверките след това. Страница с всички непокътнати тагове все още може да каже на читателя да напише грешното нещо. Ако вашият HTML всъщност е документация, написана на Markdown, нашето ръководство за превод на Markdown разглежда изходния формат вместо това.

Вземете тестовите файлове

Всичко от този тест е свободно за повторна употреба:

• sample-source.html: английската извадка от 59 реда;
• check_html_translation.py: структурната проверка (само стандартната библиотека на Python);
• run_llm_html_test.py: трите метода, за всеки локален сървър, съвместим с OpenAI;
• деветте резултата в папката с резултати, заедно с check-results.txt и results.csv.