כיצד לתרגם קובץ HTML בלי לשבור תגיות, מאפיינים או קישורים

כדי לתרגם קובץ HTML, תרגמו את הטקסט שאנשים קוראים ואת המאפיינים שנושאים מילים המיועדות לקורא, כגון alt, title, placeholder, aria-label ותיאור המטא של העמוד. השאירו את הסימון (markup) כמו שהוא: שמות תגיות, href, src, id, class, סקריפטים, סגנונות וכל דבר המסומן translate="no". לאחר מכן שנו ערך אחד שקל לשכוח, מאפיין ה-lang ברכיב ה-<html>, כדי שדפדפנים, קוראי מסך ומנועי חיפוש ידעו באיזו שפה העמוד נמצא כעת.

התברר ששמירה על שלמות התגיות הייתה החלק הקל. תרגמנו עמוד עזרה ב-HTML בן 59 שורות לסינית מפושטת תשע פעמים עם מודל מקומי, בשלוש שיטות, ובדקנו כל פלט עם סקריפט. כל הרצה שמרה על כל תגית, קישור ומזהה. מה שהשתבש היה שקט יותר: המודל תרגם שורה בתוך בלוק קוד <pre> בכל שש ההרצות ששלחו את הקובץ כולו, הוא השאיר את ה-aria-label של הניווט באנגלית בכל שש, והשיטה ששומרת על הסימון בצורה הבטוחה ביותר מעצם תכנונה, תרגום קטעי טקסט אחד אחד, יצרה משפט שאמר לקורא לעשות את הדבר הלא נכון בכל שלוש ההרצות שלה.

תשובה מהירה: מה לתרגם ומה להשאיר כמו שהוא

הרשימה הזו אינה המצאה שלנו. הסעיף בתקן HTML העוסק במאפיין translate מגדיר "מאפיינים ניתנים לתרגום": 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 וכדומה, תרגמו את מאפייני הטקסט ו תגי ה-meta המפורטים, השאירו את <code>, <pre>, <script> ו-<style> ללא שינוי למעט ה-name וה-description של JSON-LD, כבדו translate="no", שמרו על הפניות תווים והערות, והגדירו lang ל-zh-Hans.
3. מקטעים. הגישה של כלים שמחלצים טקסט מ-HTML: סקריפט מפצל את הקובץ לתגים ולטקסט, מדלג על אלמנטי <code>, <pre>, <script>, <style> ו-translate="no", שולח למודל את קטעי הטקסט ומאפייני הטקסט הנותרים כרשימת JSON ממוספרת, וכותב את התרגומים חזרה לתוך הסימון שלא נגעו בו. הוא גם מגדיר 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 מקומי שלנו מכסה את ההגדרות.

זה היה מבחן קטן של מודל אחד, זוג שפות אחד ועמוד אחד. הוא מראה אילו בעיות קורות ואיך לתפוס אותן. הוא לא מדרג מודלים או כלים.

תוצאה: הסימון שרד; שלוש החלטות לא

בדקנו כל פלט עם 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", ונקודה. הסינית מסדרת את המילים האלה בסדר אחר, ולכן מתרגם צריך להזיז את שני רכיבי הקוד. שיטת הפילוח אינה יכולה להזיז אותם. כל שלוש ההרצות הפכו את ההוראה. הרצה 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> ，, בכל שלוש הרצות הפילוח, שישה מקומות בכל הרצה. דפדפן מציג אותם כרווחים גלויים, כולל לפני פיסוק סיני. בהרצות של קובץ שלם לא היו כאלה; בשתיים משלוש ההרצות עם הוראות היו ארבעה או חמישה.

בודק מבני אינו יכול לתפוס את המשפט ההפוך, משום שכל תגית נמצאת בדיוק במקום שבו הייתה. הבודק שלנו מדווח כאשר קוד מוטבע משנה סדר, וזה נורמלי בשפות רבות, אך האזהרה הזו אינה יכולה להבחין בין נכון לשגוי. במבחן הזה היא הופעלה בכל שש התרגומים הנכונים ושתקה בשלושת השגויים, משום שהשגויים שמרו על הסדר האנגלי. רק אדם שקורא את המשפט יכול לדעת. התיקון הוא לשלוח למתרגם משפטים שלמים עם התגיות המוטבעות שלהם, וזה מה שההרצות של קובץ שלם עשו, ולבדוק את המבנה afterwards.

הבדלים קטנים יותר

• 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, כל קישור אליו נשבר. אף אחת מההרצות שלנו לא עשתה זאת, אבל מתרגם ש"בעוזרו" ימקם עוגנים יעשה זאת.
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 ששונה ממה שציפית, טקסט גלוי שנראה לא מתורגם, קוד מוטבע ששינה סדר, ורווחים בין טקסט סיני, יפני או קוריאני across תגית מוטבעת. היא אינה שופטת את איכות התרגום.

2. קרא כל משפט שמכיל תגית מוטבעת. כאן נשברה המשמעות במבחן שלנו. אל תסתמך על אזהרת "קוד מוטבע ששינה סדר" של הבודק כדי למצוא את המשפטים האלה: במבחן שלנו, התרגומים השגויים היו אלה ששמרו על הסדר המקורי.

3. פתח את הדף בדפדפן. לחץ על הקישורים שבתוך הדף, עבור בטופס עם קורא מסך אם אפשר, וחפש רווחים סביב טקסט מודגש ומקושר.

4. לשפות מימין לשמאל, הגדר גם dir="rtl" על רכיב ה-<html>. המדריך שלנו לתרגום ספרים מימין לשמאל מכסה מה עוד משתנה.

5. ל-XHTML, כגון קובצי הפרקים בתוך EPUB, ודא גם שהקובץ עדיין XML תקין, למשל עם xmllint --noout chapter.xhtml. דפדפן סולח לתגית לא סגורה; קורא ספרים אלקטרוני אולי לא. רשימת הבדיקה שלנו לתרגום EPUB מכסה את שאר הספר האלקטרוני.

איפה BookTranslator נכנס לתמונה

דף ההעלאה של BookTranslator מקבל קבצי .html, .htm ו-.xhtml לצד ספרים ומסמכים, כך שתוכלו להעלות עמוד שמור או מאמר עזרה סטטי כקובץ שלם. לא העברנו את הדוגמה הזו דרך BookTranslator עבור מאמר זה, ולא בדקנו כיצד הוא מטפל בסדר קוד מוטבע, בתוכן CSS או ב-JSON-LD, לכן בדקו את הפלט שלו כפי הייתם בודקים כל כלי אחר. המחיר מוצג לפני התשלום.

יהיה אשר יהיה הכלי שתבחרו, בצעו את שלבי ההכנה לפני התרגום ואת הבדיקות afterwards. עמוד שכל התגיות בו שלמות עדיין עלול לומר לקורא להקליד דבר שגוי. אם ה-HTML שלכם הוא למעשה תיעוד שנכתב ב-Markdown, מדריך תרגום ה-Markdown שלנו מכסה את פורמט המקור במקום זאת.

הורידו את קבצי הבדיקה

הכל מהבדיקה הזו חופשי לשימוש חוזר:

• sample-source.html: דוגמת האנגלית בת 59 השורות;
• check_html_translation.py: בודק המבנה (ספריית התקן של Python בלבד);
• run_llm_html_test.py: שלוש השיטות, עבור כל שרת מקומי תואם OpenAI;
• תשעת הפלטים בתיקיית הפלטים, עם check-results.txt ו-results.csv.