כיצד לתרגם מסמכים טכניים מבלי לשבור קוד

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, וכו’).
Prefer translator notes over “fixing” code logic—flag issues to maintainers instead.

Code Blocks and Inline Code

Keep code fences, language hints, and content intact. Translate only comments and human‑readable strings if required.

Example—safe vs unsafe:

// SAFE: Only the comment is localized
// Obtains a user token
import { getToken } from "@acme/sdk";
const token = await getToken();

// UNSAFE: Do not translate identifiers/imports/package names
// import { obtenirJeton } from "@acme/sdk"; // ❌

Inline code must stay verbatim:

Good: “Run npm install -g acme-cli and then acme login.”
Bad: “Run npm install -g acme-cli and then acme connexion.” ❌

Validate copy‑pasteability: If a reader copies any snippet, it should run as in the source.

Placeholders and ICU MessageFormat

Preserve placeholders exactly, including spacing and punctuation around them.

# Do not alter tokens or spacing
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ adds spaces inside braces

ICU example:

{count, plural,
  =0 {No messages}
  one {# message}
  other {# messages}
}

Do not change keys (count, one, other).
Translate only the human‑readable parts (“message”, “messages”).
Do not introduce or remove plural categories without product guidance.

Links, Anchors, and Slugs

Keep Markdown link syntax and resolve strategy consistent.

[Read the API guide](/api/getting-started)  
[See the config section](#configuration)

Translate link text if needed; be cautious with URLs and anchors.
Anchors: either keep stable anchors across locales or generate per‑locale anchors and update references accordingly.
Verify relative paths and hash anchors still resolve after translation.
Do not translate file extensions or query params.

Structured Data (JSON/YAML/TOML)

Translate values only—never keys, types, or structure. Always re‑parse after editing.

JSON:

{
  "title": "User Guide",
  "cta": "Get Started",
  "limits": { "max": 5, "unit": "requests/second" }
}

Keys like title, cta, limits, max must remain unchanged.
Numbers, booleans, and nulls stay as types, not words.

YAML (watch folded scalars):

note: >
  Lines are folded into a single paragraph.
  Keep indentation and markers intact.

Preserve quoting, escapes, indentation, and trailing commas (where applicable).

Filenames, CLI, and API Names

Do not translate filenames, package names, endpoints, or CLI flags.
Keep case sensitivity exactly as in source (e.g., --DryRun vs --dry-run).
Maintain commands verbatim; add callouts if locale‑specific differences exist.

# Correct
kubectl get pods --namespace default

# Wrong (flag translated) ❌
kubectl get pods --nom-espace defaut

Markdown Gotchas

Tables: keep pipes and alignment; do not break columns.

| 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 עובר מקומית
הבדלים נסקרו לשינויים מקריים במפתחות

קריאה קשורה