כיצד לתרגם מסמכים טכניים מבלי לשבור קוד
OpenL Team 10/13/2025
TABLE OF CONTENTS
המסמכים הטכניים אינם סלחניים: גדר קוד שבורה, מציין מקום או עוגן יכולים לשבור בניות, לבלבל קוראים או לגרום לכשלי העתקה והדבקה. מדריך זה מעניק לך תהליך עבודה בטוח וחוזר על עצמו לתרגום מסמכים טכניים בביטחון—תוך שמירה על הקוד שלם והמסמכים מוכנים לשחרור.
למי זה מיועד: כותבים טכניים, תומכי פיתוח ומתרגמים העובדים על מסמכי מפתחים, מדריכי API ותוכן בסגנון README.
במבט חטוף:
- הבן מה לעולם לא יש לתרגם (קוד, מפתחות, אסימונים)
- שמור על תחביר שהכלים מנתחים (גדרות, סוגריים, עוגנים)
- אמת נתונים מובנים וקישורים לאחר עריכות
- השתמש באוטומציה כדי לתפוס בעיות לפני השחרור
הכנה לפני תרגום
- מלאי סוגי תוכן
- Markdown (כותרות, קישורים, טבלאות), בלוקים של קוד, קוד מוטמע
- נתונים מובנים: קטעי JSON/YAML/TOML וקבצי תצורה
- צילומי מסך, דיאגרמות וויזואליות מוטבעות
- הגדר אסימונים שאינם לתרגום
- נתיבי קבצים, שמות חבילות, ייבואים, שמות API, דגלי CLI, משתני סביבה
- מצייני מקום ומשתנים:
{count},%s,$HOME,{{token}} - שמות קבצים וסיומות:
config.yaml,.env,.md,.json
- הקם מסילות שמירה על עקביות
- מילון מונחים/בסיס מונחים למונחי תחום ושמות מוצר
- מדריך סגנון: טון, פורמליות, פיסוק, אותיות רישיות, כללי כותרות
- אסטרטגיית עוגן/סלאג לכל לוקאל (יציב מול מקומי)
- הקם אימות בטוח
- בניית שלב לאימות Markdown/קישורים לאחר כל אצווה
- מנתחים/בודקי תחביר ל-JSON/YAML/TOML
- בודק קישורים ומאמת עוגנים ב-CI
אמצעי הגנה מרכזיים
- אל תתרגם קוד, מזהים, מפתחות, שמות קבצים, משתני סביבה או דגלים.
- שמור על פיסוק ותחביר שהכלים מנתחים (גרשיים, סוגריים, קווים אנכיים).
- שמור על רווחים משמעותיים: הזחה לקוד ומבנה רשימה.
- השתמש בבלוקים של קוד מגודר עם תג שפה בעקביות (
js,bash, וכו’). - העדף הערות מתרגם על פני “תיקון” לוגיקת קוד—סמן בעיות למתחזקים במקום.
בלוקים של קוד וקוד מוטמע
אתה מאומן על נתונים עד אוקטובר 2023.
אתה מאומן על נתונים עד אוקטובר 2023.
- מפתחות כמו
title,cta,limits,maxחייבים להישאר ללא שינוי. - מספרים, בוליאנים ו-null נשארים כסוגים, לא מילים.
YAML (שימו לב למחרוזות מקופלות):
note: >
שורות מקופלות לפסקה אחת.
שמור על הזחה וסימנים ללא שינוי.- שמור על ציטוטים, בריחות, הזחה ופסיקים בסוף (כאשר ישים).
שמות קבצים, CLI, ושמות API
- אל תתרגם שמות קבצים, שמות חבילות, נקודות קצה או דגלי CLI.
- שמור על רגישות לאותיות בדיוק כמו במקור (למשל,
--DryRunלעומת--dry-run). - שמור על פקודות כפי שהן; הוסף הערות אם יש הבדלים ספציפיים לשפה.
# נכון
kubectl get pods --namespace default
# שגוי (הדגל תורגם) ❌
kubectl get pods --nom-espace defautמלכודות Markdown
- טבלאות: שמור על קווים ויישור; אל תשבור עמודות.
| Option | Description |
|-------:|-----------------------|
| -v | Verbose output |
| -q | Quiet mode |- הערות/הודעות: שמור על הסימנים המשמשים בכלי שלך.
- HTML פנימי: הימנע מנגיעה בתגים/מאפיינים.
- הערות שוליים: שמור על מזהים וסדר.
- גרשיים חכמים: העדף גרשיים ישרים בתוך הקשרי קוד.
ויזואלים ונגישות
- לוקליזציה של טקסט חלופי למשמעות, לא לתוכן פיקסלים.
- העדף צילומי מסך שאינם תלויי שפה (הדגש ממשק משתמש לא שפה), או ספק סטים לפי שפה.
- שמור על קבצי מקור של דיאגרמות (למשל, Mermaid) מסונכרנים בין שפות.
- הימנע מטקסט מוטמע בתמונות; חיצוני כיתובים ותוויות.
SEO ומטא-נתונים
- תרגם כותרות, תיאורים וכותרות משנה תוך שימוש במילות מפתח מתאימות לשפה.
- שמור על כתובות URL קנוניות ו-
hreflangבהתאם לכללי האתר. - אל תתרגם מפתחות מטא/תכונה או מפתחות JSON‑LD.
- יישר את הקישורים עם אסטרטגיית העוגן שלך כדי להימנע מ-404s.
זרימת עבודה ואוטומציה
- השתמש בזרימת עבודה של CAT/LLM ששומרת על קטעי קוד ותגים.
- נעל את המונחים עם מילון מונחים ורשימת אי-תרגום.
- הוסף hooks לפני התחייבות כדי לבדוק Markdown ולאמת JSON/YAML.
- הפעל בודק קישורים ומאמת עוגנים על כל PR.
- קבץ שינויים למקטעים קטנים שניתן לסקור ולעקוב אחר ההבדלים.
כלים מוצעים (התאם לערמת הכלים שלך):
- בדיקת Markdown ובדיקת קישורים ב-CI
- שלב ניתוח JSON/YAML כדי לתפוס רגרסיות תחביר
- חבילות Regex לסריקת מצייני מיקום ופורמטים מספריים
QA ואימות
הרץ את הבדיקות הבאות לפני מיזוג:
- בנה את האתר כדי לתפוס בעיות תחביר:
pnpm build - בדיקות סוג/תוכן (אוספי תוכן של Astro):
pnpm astro check - תצוגה מקדימה ובדיקת דגימה של דפים מרכזיים:
pnpm preview - אמת דוגמאות קוד שמתקמפלים או רצים (כאשר ישים)
- הרץ בודק קישורים ועוגנים; תקן כל 404 או האש שבור
מלכודות נפוצות
- תרגום מפתחות/מצייני מיקום בטעות.
- שבירת גדרות קוד או צינורות טבלה.
- לוקליזציה של נתיבי קבצים, דגלים או שמות API.
- שינוי כותרות מבלי לעדכן קישורי עוגן.
- הכנסת מרכאות חכמות בתוך קוד או JSON.
נספח: רשימות בדיקה מהירות
לפני טיסה (5 פריטים)
- מילון מונחים ורשימת אי-תרגום מוכנים
- אסימונים/מצייני מיקום מוגדרים ומוגנים
- אסטרטגיית עוגן/slug מאושרת
- מטרות קישורים ממופות (פנימיות לעומת חיצוניות)
- בנייה זמנית זמינה
בטיחות דוגמאות קוד (5 פריטים)
- גדרות ורמזי שפה שלמים
- מזהים/ייבוא לא נגעו; הערות לוקליזציה בלבד
- מצייני מיקום ומרכאות נשמרו
- מבחן העתק-הדבק עובר
- קטעים מיושנים מסומנים למתחזקים
נתונים מובנים (5 פריטים)
- מפתחות וסוגים לא נגעו
- מרכאות/בריחות/הזחות נשמרו
- מספרים ובוליאנים נשארים כסוגים
- Parser/linter עובר מקומית
- הבדלים נסקרו לשינויים מקריים במפתחות
קריאה קשורה
