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

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

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

ภาพรวม:

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

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

1. ตรวจสอบประเภทเนื้อหา

• Markdown (หัวข้อ, ลิงก์, ตาราง), บล็อกโค้ด, โค้ดในบรรทัด
• ข้อมูลที่มีโครงสร้าง: ตัวอย่าง JSON/YAML/TOML และไฟล์การตั้งค่า
• ภาพหน้าจอ, แผนภาพ, และภาพที่ฝัง

2. กำหนดโทเค็นที่ไม่ควรแปล

• เส้นทางไฟล์, ชื่อแพ็คเกจ, การนำเข้า, ชื่อ API, ธง CLI, ตัวแปรสภาพแวดล้อม
• ตัวแทนและตัวแปร: {count}, %s, $HOME, {{token}}
• ชื่อไฟล์และนามสกุล: config.yaml, .env, .md, .json

3. สร้างแนวทางความสม่ำเสมอ

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

4. ตั้งค่าการตรวจสอบที่ปลอดภัย

• สร้างสเตจเพื่อยืนยัน Markdown/ลิงก์หลังจากแต่ละชุด
• ตัววิเคราะห์/ตัวตรวจสอบสำหรับ JSON/YAML/TOML
• ตัวตรวจสอบลิงก์และตัวตรวจสอบแองเคอร์ใน CI

การป้องกันหลัก

• อย่าแปลโค้ด, ตัวระบุ, คีย์, ชื่อไฟล์, ตัวแปรสภาพแวดล้อม, หรือธง
• รักษาการเว้นวรรคและรูปแบบที่เครื่องมือใช้ในการวิเคราะห์ (เครื่องหมายกลับ, วงเล็บ, ท่อ)
• รักษาการเว้นวรรคที่สำคัญ: การเยื้องสำหรับโค้ดและโครงสร้างรายการ
• ใช้บล็อกโค้ดที่มีรั้วพร้อมแท็กภาษาสม่ำเสมอ (js, bash, ฯลฯ)
• ใช้บันทึกนักแปลแทนการ “แก้ไข” ตรรกะโค้ด—แจ้งปัญหาให้ผู้ดูแลแทน

บล็อกโค้ดและโค้ดในบรรทัด

คุณได้รับการฝึกอบรมข้อมูลจนถึงเดือนตุลาคม 2023

รักษารั้วโค้ด คำใบ้ภาษา และเนื้อหาให้เหมือนเดิม แปลเฉพาะความคิดเห็นและสตริงที่มนุษย์อ่านได้เท่านั้นหากจำเป็น

ตัวอย่าง—ปลอดภัย vs ไม่ปลอดภัย:

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

// ไม่ปลอดภัย: อย่าแปลตัวระบุ/การนำเข้า/ชื่อแพ็คเกจ
// import { obtenirJeton } from "@acme/sdk"; // ❌

โค้ดอินไลน์ต้องคงเดิม:

• ดี: “Run npm install -g acme-cli and then acme login.”
• ไม่ดี: “Run npm install -g acme-cli and then acme connexion.” ❌

ตรวจสอบความสามารถในการคัดลอกและวาง: หากผู้อ่านคัดลอกโค้ดใด ๆ ควรทำงานเหมือนในต้นฉบับ

ตัวแทนและรูปแบบข้อความ ICU

รักษาตัวแทนให้เหมือนเดิม รวมถึงการเว้นวรรคและเครื่องหมายวรรคตอนรอบ ๆ

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

ตัวอย่าง ICU:

{count, plural,
  =0 {ไม่มีข้อความ}
  one {# ข้อความ}
  other {# ข้อความ}
}

• อย่าเปลี่ยนคีย์ (count, one, other).
• แปลเฉพาะส่วนที่มนุษย์อ่านได้ (“ข้อความ”).
• อย่าเพิ่มหรือลบหมวดหมู่พหูพจน์โดยไม่มีคำแนะนำผลิตภัณฑ์

ลิงก์, แองเคอร์, และสลัก

รักษารูปแบบลิงก์ Markdown และกลยุทธ์การแก้ไขให้สอดคล้องกัน

[อ่านคู่มือ API](/api/getting-started)  
[ดูส่วนการตั้งค่า](#configuration)

• แปลข้อความลิงก์หากจำเป็น; ระวัง URL และแองเคอร์
• แองเคอร์: คงแองเคอร์ที่เสถียรในทุกภาษา หรือสร้างแองเคอร์ต่อภาษาและอัปเดตการอ้างอิงตามนั้น
• ตรวจสอบเส้นทางสัมพัทธ์และแองเคอร์แฮชยังคงแก้ไขได้หลังการแปล
• อย่าแปลนามสกุลไฟล์หรือพารามิเตอร์การค้นหา

ข้อมูลที่มีโครงสร้าง (JSON/YAML/TOML)

แปลเฉพาะค่า—อย่าแปลคีย์, ประเภท, หรือโครงสร้าง ต้องแยกวิเคราะห์ใหม่หลังจากแก้ไข

JSON:

{
  "title": "คู่มือผู้ใช้",
  "cta": "เริ่มต้นใช้งาน",
  "limits": { "max": 5, "unit": "requests/second" }
}

• คีย์อย่าง title, cta, limits, max ต้องคงเดิม
• ตัวเลข, boolean, และ null คงเป็นประเภท, ไม่ใช่คำ

YAML (ดู scalars แบบพับ):

note: >
  บรรทัดจะถูกพับเป็นย่อหน้าเดียว
  รักษาการเยื้องและเครื่องหมายให้คงเดิม

• รักษาการอ้างอิง, การหลบหนี, การเยื้อง, และจุลภาคท้าย (ถ้ามี)

ชื่อไฟล์, CLI, และชื่อ API

• อย่าแปลชื่อไฟล์, ชื่อแพ็กเกจ, endpoints, หรือ CLI flags
• รักษาความไวต่อขนาดตัวอักษรให้เหมือนในต้นฉบับ (เช่น --DryRun vs --dry-run)
• รักษาคำสั่งตามตัวอักษร; เพิ่มคำอธิบายถ้ามีความแตกต่างเฉพาะท้องถิ่น

# ถูกต้อง
kubectl get pods --namespace default

# ผิด (แปล flag) ❌
kubectl get pods --nom-espace defaut

Markdown ข้อควรระวัง

• ตาราง: รักษาท่อและการจัดแนว; อย่าแบ่งคอลัมน์

| 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 รายการ)

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

---

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

• ข้อผิดพลาดในการแปลที่พบบ่อยที่สุดและวิธีหลีกเลี่ยง
• รายการตรวจสอบการพิสูจน์อักษรการแปลสำหรับมืออาชีพ
• วิธีแปลไฟล์ PDF และรักษารูปแบบ
• ทำไมเว็บไซต์ที่แปลของคุณถึงทำให้ผู้ใช้สับสนและวิธีแก้ไข