วิธีแปลเอกสารทางเทคนิคโดยไม่ทำให้โค้ดเสียหาย

OpenL Team Oct 13, 2025
วิธีแปลเอกสารทางเทคนิคโดยไม่ทำให้โค้ดเสียหาย

TABLE OF CONTENTS

เอกสารทางเทคนิคไม่ยอมให้มีข้อผิดพลาด: รั้วโค้ดที่เสีย, ตัวแทน, หรือแองเคอร์ที่ผิดพลาดเพียงหนึ่งเดียวสามารถทำให้การสร้างล้มเหลว, ทำให้ผู้อ่านสับสน, หรือทำให้การคัดลอกและวางล้มเหลวได้ คู่มือนี้ให้ขั้นตอนการทำงานที่ปลอดภัยและสามารถทำซ้ำได้เพื่อแปลเอกสารทางเทคนิคด้วยความมั่นใจ—ในขณะที่รักษาโค้ดให้คงอยู่และเอกสารสามารถส่งได้

สำหรับใคร: นักเขียนทางเทคนิค, ผู้สนับสนุนการพัฒนา, และนักแปลที่ทำงานเกี่ยวกับเอกสารสำหรับนักพัฒนา, คู่มือ API, และเนื้อหาในรูปแบบ README

ภาพรวม:

  • เข้าใจสิ่งที่ไม่ควรแปล (โค้ด, คีย์, โทเค็น)
  • รักษารูปแบบที่เครื่องมือใช้ในการวิเคราะห์ (รั้ว, วงเล็บ, แองเคอร์)
  • ตรวจสอบข้อมูลที่มีโครงสร้างและลิงก์หลังจากแก้ไข
  • ใช้ระบบอัตโนมัติเพื่อตรวจจับปัญหาก่อนการปล่อย

การเตรียมก่อนการแปล

  1. ตรวจสอบประเภทเนื้อหา
  • Markdown (หัวข้อ, ลิงก์, ตาราง), บล็อกโค้ด, โค้ดในบรรทัด
  • ข้อมูลที่มีโครงสร้าง: ตัวอย่าง JSON/YAML/TOML และไฟล์การตั้งค่า
  • ภาพหน้าจอ, แผนภาพ, และภาพที่ฝัง
  1. กำหนดโทเค็นที่ไม่ควรแปล
  • เส้นทางไฟล์, ชื่อแพ็คเกจ, การนำเข้า, ชื่อ API, ธง CLI, ตัวแปรสภาพแวดล้อม
  • ตัวแทนและตัวแปร: {count}, %s, $HOME, {{token}}
  • ชื่อไฟล์และนามสกุล: config.yaml, .env, .md, .json
  1. สร้างแนวทางความสม่ำเสมอ
  • พจนานุกรม/ฐานคำศัพท์สำหรับคำศัพท์ในโดเมนและชื่อผลิตภัณฑ์
  • คู่มือสไตล์: โทน, ความเป็นทางการ, การเว้นวรรค, การใช้ตัวพิมพ์, กฎหัวข้อ
  • กลยุทธ์แองเคอร์/สลักต่อท้องถิ่น (คงที่ vs แปล)
  1. ตั้งค่าการตรวจสอบที่ปลอดภัย
  • สร้างสเตจเพื่อยืนยัน 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:

// ปลอดภัย: แปลเฉพาะความคิดเห็น
// รับโทเค็นผู้ใช้
import { getToken } from "@acme/sdk";
const token = await getToken();

// ไม่ปลอดภัย: อย่าแปลตัวระบุ/การนำเข้า/ชื่อแพ็คเกจ
// 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.

# อย่าเปลี่ยนโทเค็นหรือการเว้นวรรค
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ เพิ่มช่องว่างภายในวงเล็บ

ICU example:

{count, plural,
  =0 {ไม่มีข้อความ}
  one {# ข้อความ}
  other {# ข้อความ}
}
  • 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.

Keep Markdown link syntax and resolve strategy consistent.

[อ่านคู่มือ API](/api/getting-started)  
[ดูส่วนการตั้งค่า](#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": "คู่มือผู้ใช้",
  "cta": "เริ่มต้นใช้งาน",
  "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: >
  บรรทัดจะถูกพับเป็นย่อหน้าเดียว
  รักษาการเยื้องและเครื่องหมายให้คงเดิม
  • 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.
# ถูกต้อง
kubectl get pods --namespace default

# ผิด (แปล flag) ❌
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 แบบอินไลน์: หลีกเลี่ยงการแตะต้องแท็ก/แอตทริบิวต์
  • เชิงอรรถ: รักษา ids และลำดับ
  • เครื่องหมายคำพูดอัจฉริยะ: ชอบเครื่องหมายคำพูดตรงในบริบทของโค้ด

ภาพและการเข้าถึง

  • แปลข้อความ alt เพื่อความหมาย, ไม่ใช่เนื้อหาพิกเซล
  • ชอบภาพหน้าจอที่ไม่ขึ้นกับท้องถิ่น (เน้น UI ไม่ใช่ภาษา), หรือให้ชุดตามท้องถิ่น
  • รักษาไฟล์ต้นฉบับของไดอะแกรม (เช่น Mermaid) ให้สอดคล้องกันในทุกท้องถิ่น
  • หลีกเลี่ยงข้อความฝังในภาพ; แยกคำบรรยายและป้ายออกมา

SEO และเมตาดาต้า

  • แปลชื่อ, คำอธิบาย, และหัวข้อโดยใช้คำหลักที่เหมาะสมกับท้องถิ่น
  • รักษา URLs ที่เป็นมาตรฐานและ hreflang ให้สอดคล้องกับกฎของเว็บไซต์
  • อย่าแปลคีย์ meta/property หรือคีย์ JSON‑LD
  • จัดให้ slugs สอดคล้องกับกลยุทธ์ anchor ของคุณเพื่อหลีกเลี่ยง 404s

เวิร์กโฟลว์และระบบอัตโนมัติ

  • ใช้กระบวนการทำงาน CAT/LLM ที่รักษาช่วงโค้ดและแท็ก
  • ล็อคคำศัพท์ด้วยอภิธานศัพท์และรายการคำที่ไม่ต้องแปล
  • เพิ่ม pre‑commit hooks เพื่อตรวจสอบ Markdown และตรวจสอบความถูกต้องของ JSON/YAML
  • รันตัวตรวจสอบลิงก์และตัวตรวจสอบแองเคอร์ในทุก PR
  • รวมการเปลี่ยนแปลงในชิ้นเล็ก ๆ ที่สามารถตรวจสอบได้และติดตามความแตกต่าง

เครื่องมือที่แนะนำ (ปรับให้เข้ากับสแต็กของคุณ):

  • การตรวจสอบ Markdown และลิงก์ใน CI
  • ขั้นตอนการแยกวิเคราะห์ JSON/YAML เพื่อจับข้อผิดพลาดทางไวยากรณ์
  • ชุด Regex เพื่อสแกนตัวแทนและรูปแบบตัวเลข

QA และการตรวจสอบความถูกต้อง

รันการตรวจสอบเหล่านี้ก่อนการรวม:

  • สร้างเว็บไซต์เพื่อตรวจจับปัญหาทางไวยากรณ์: pnpm build
  • การตรวจสอบประเภท/เนื้อหา (Astro content collections): pnpm astro check
  • ดูตัวอย่างและทดสอบหน้าหลัก: pnpm preview
  • ตรวจสอบตัวอย่างโค้ดว่าคอมไพล์หรือรันได้ (ถ้าใช้ได้)
  • รันตัวตรวจสอบลิงก์และแองเคอร์; แก้ไข 404s หรือแฮชที่เสียหาย

ข้อผิดพลาดทั่วไป

  • แปลคีย์/ตัวแทนโดยบังเอิญ
  • ทำลายรั้วโค้ดหรือตารางท่อ
  • โลคัลไลซ์เส้นทางไฟล์, ธง, หรือชื่อ API
  • เปลี่ยนหัวข้อโดยไม่อัปเดตลิงก์แองเคอร์
  • แนะนำเครื่องหมายคำพูดอัจฉริยะภายในโค้ดหรือ JSON

ภาคผนวก: เช็คลิสต์ด่วน

ก่อนบิน (5 รายการ)

  • อภิธานศัพท์และรายการคำที่ไม่ต้องแปลพร้อม
  • โทเค็น/ตัวแทนถูกกำหนดและป้องกัน
  • ยุทธศาสตร์แองเคอร์/สลักได้รับการยืนยัน
  • เป้าหมายลิงก์ถูกแมป (ภายใน vs ภายนอก)
  • การสร้างสเตจพร้อมใช้งาน

ความปลอดภัยของตัวอย่างโค้ด (5 รายการ)

  • รั้วและคำใบ้ภาษายังคงอยู่
  • ตัวระบุ/การนำเข้าไม่ได้รับการแก้ไข; คำอธิบายประกอบโลคัลไลซ์เท่านั้น
  • ตัวแทนและการอ้างอิงยังคงอยู่
  • การทดสอบคัดลอกและวางผ่าน
  • ตัวอย่างที่ล้าสมัยถูกตั้งค่าสถานะให้ผู้ดูแล

ข้อมูลที่มีโครงสร้าง (5 รายการ)

  • คีย์และประเภทไม่ได้รับการแก้ไข
  • การอ้างอิง/การหลบหนี/การเยื้องยังคงอยู่
  • ตัวเลขและบูลีนยังคงเป็นประเภท
  • ตัวแยกวิเคราะห์/ตัวตรวจสอบผ่านในเครื่อง
  • ความแตกต่างได้รับการตรวจสอบสำหรับการเปลี่ยนแปลงคีย์โดยบังเอิญ

การอ่านที่เกี่ยวข้อง

Related Posts

วิธีแปลข้อเสนอทางธุรกิจโดยไม่เสียพลังในการโน้มน้าว

วิธีแปลข้อเสนอทางธุรกิจโดยไม่เสียพลังในการโน้มน้าว

คู่มือปฏิบัติสำหรับการแปลข้อเสนอทางธุรกิจ สไลด์นำเสนอ และคำตอบ RFP โดยยังรักษาคุณค่าที่เสนอ โทนเสียง ตัวเลข ถ้อยคำทางกฎหมาย และเลย์เอาต์ให้โน้มน้าวใจได้

2026/10/25
เครื่องมือแปล Markdown ที่ดีที่สุดในปี 2026: รักษารูปแบบให้สมบูรณ์

เครื่องมือแปล Markdown ที่ดีที่สุดในปี 2026: รักษารูปแบบให้สมบูรณ์

เปรียบเทียบเครื่องมือแปล Markdown 6 ตัวที่รักษาหัวข้อ โค้ดบล็อก และลิงก์ไว้ — OpenL, qlot, DeepL, MD Translator, Vitra และ Crowdin — พร้อมราคาและกรณีการใช้งาน

2026/10/15
ทำไมฟอนต์จึงพังหลังการแปล

ทำไมฟอนต์จึงพังหลังการแปล

เรียนรู้สาเหตุที่ตัวอักษรหาย การแทนฟอนต์ การจัดวางอักษร และข้อความล้นหลังแปล พร้อมขั้นตอนแก้ปัญหาใน PDF เอกสาร และสไลด์

2026/7/24