Cách Dịch Tài Liệu Kỹ Thuật Mà Không Làm Hỏng Mã Code

TABLE OF CONTENTS

Tài liệu kỹ thuật không khoan nhượng: chỉ một lỗi nhỏ như code fence bị hỏng, placeholder sai, hoặc anchor lỗi cũng có thể làm hỏng quá trình build, gây nhầm lẫn cho người đọc hoặc khiến thao tác sao chép-dán thất bại. Hướng dẫn này cung cấp cho bạn một quy trình làm việc an toàn, có thể lặp lại để dịch tài liệu kỹ thuật một cách tự tin—đồng thời giữ nguyên mã nguồn và đảm bảo tài liệu luôn sẵn sàng phát hành.

Đối tượng phù hợp: các biên tập viên kỹ thuật, chuyên gia truyền thông cho lập trình viên, và dịch giả làm việc với tài liệu dành cho nhà phát triển, hướng dẫn API, và nội dung dạng README.

Tóm tắt nhanh:

Hiểu rõ những gì tuyệt đối không được dịch (mã nguồn, khóa, token)
Bảo toàn cú pháp mà công cụ cần phân tích (fence, dấu ngoặc, anchor)
Kiểm tra lại dữ liệu có cấu trúc và liên kết sau khi chỉnh sửa
Sử dụng tự động hóa để phát hiện lỗi trước khi phát hành

Chuẩn Bị Trước Khi Dịch

Kiểm kê các loại nội dung

Markdown (tiêu đề, liên kết, bảng), khối mã, mã nội tuyến
Dữ liệu có cấu trúc: đoạn mã JSON/YAML/TOML và file cấu hình
Ảnh chụp màn hình, sơ đồ, và hình ảnh nhúng

Xác định các token không được dịch

Đường dẫn file, tên gói, import, tên API, cờ CLI, biến môi trường
Placeholder và biến: {count}, %s, $HOME, {{token}}
Tên file và phần mở rộng: config.yaml, .env, .md, .json

Thiết lập quy tắc nhất quán

Bảng thuật ngữ cho từ chuyên ngành và tên sản phẩm
Hướng dẫn phong cách: giọng điệu, mức độ trang trọng, dấu câu, viết hoa, quy tắc tiêu đề
Chiến lược anchor/slug cho từng ngôn ngữ (giữ ổn định hoặc bản địa hóa)

Thiết lập kiểm tra an toàn

Build thử nghiệm để kiểm tra Markdown/liên kết sau mỗi đợt dịch
Trình phân tích cú pháp/kiểm tra lỗi cho JSON/YAML/TOML
Công cụ kiểm tra liên kết và anchor trong CI

Nguyên Tắc Bảo Toàn Cốt Lõi

Không dịch mã nguồn, định danh, khóa, tên file, biến môi trường hoặc cờ.
Giữ nguyên dấu câu và cú pháp mà công cụ cần phân tích (backtick, dấu ngoặc, dấu gạch dọc).
Bảo toàn khoảng trắng quan trọng: thụt lề cho mã nguồn và cấu trúc danh sách.
Luôn sử dụng code fence có tag ngôn ngữ nhất quán (js, bash, v.v.).
Ưu tiên ghi chú cho dịch giả thay vì “sửa” logic mã nguồn—hãy báo lỗi cho người bảo trì nếu phát hiện vấn đề.

Khối Mã và Mã Nội Tuyến

Giữ nguyên dấu phân cách mã, gợi ý ngôn ngữ và nội dung bên trong. Chỉ dịch chú thích và các chuỗi có thể đọc được bởi con người nếu cần thiết.

Ví dụ—an toàn vs không an toàn:

// AN TOÀN: Chỉ chú thích được bản địa hóa
// Lấy mã thông báo người dùng
import { getToken } from "@acme/sdk";
const token = await getToken();

// KHÔNG AN TOÀN: Không dịch tên định danh/import/tên gói
// import { obtenirJeton } from "@acme/sdk"; // ❌

Mã nội tuyến phải giữ nguyên:

Đúng: “Chạy npm install -g acme-cli rồi acme login.”
Sai: “Chạy npm install -g acme-cli rồi acme connexion.” ❌

Kiểm tra khả năng sao chép-dán: Nếu người đọc sao chép bất kỳ đoạn mã nào, nó phải chạy được như bản gốc.

Placeholder và ICU MessageFormat

Giữ nguyên placeholder, bao gồm cả khoảng trắng và dấu câu xung quanh.

# Không thay đổi token hoặc khoảng trắng
echo "Đang xử lý {count} tệp"   # ✅
echo "Đang xử lý { count } tệp" # ❌ thêm khoảng trắng trong dấu ngoặc nhọn

Ví dụ ICU:

{count, plural,
  =0 {Không có tin nhắn nào}
  one {# tin nhắn}
  other {# tin nhắn}
}

Không thay đổi khóa (count, one, other).
Chỉ dịch phần có thể đọc được (“tin nhắn”, “tin nhắn”).
Không thêm hoặc bớt các dạng số nhiều nếu không có hướng dẫn từ sản phẩm.

Liên kết, Anchor và Slug

Giữ nguyên cú pháp liên kết Markdown và chiến lược xử lý.

[Xem hướng dẫn API](/api/getting-started)  
[Xem phần cấu hình](#configuration)

Dịch văn bản liên kết nếu cần; cẩn thận với URL và anchor.
Anchor: hoặc giữ anchor ổn định giữa các ngôn ngữ hoặc tạo anchor riêng cho từng ngôn ngữ và cập nhật tham chiếu tương ứng.
Kiểm tra lại đường dẫn tương đối và anchor sau khi dịch để đảm bảo vẫn hoạt động.
Không dịch phần mở rộng tệp hoặc tham số truy vấn.

Dữ liệu có cấu trúc (JSON/YAML/TOML)

Chỉ dịch giá trị—không bao giờ dịch khóa, kiểu hoặc cấu trúc. Luôn kiểm tra lại bằng cách phân tích lại sau khi chỉnh sửa.

JSON:

{
  "title": "Hướng dẫn người dùng",
  "cta": "Bắt đầu ngay",
  "limits": { "max": 5, "unit": "yêu cầu/giây" }
}

Các khóa như title, cta, limits, max phải giữ nguyên không thay đổi.
Số, giá trị boolean và null giữ nguyên kiểu dữ liệu, không chuyển thành chữ.

YAML (chú ý đến folded scalars):

note: >
  Các dòng sẽ được gộp thành một đoạn văn duy nhất.
  Giữ nguyên thụt lề và các ký hiệu đánh dấu.

Giữ nguyên dấu nháy, ký tự escape, thụt lề và dấu phẩy cuối dòng (nếu có).

Tên tệp, CLI và API

Không dịch tên tệp, tên gói, endpoint hoặc cờ CLI.
Giữ nguyên phân biệt chữ hoa/thường như bản gốc (ví dụ: --DryRun so với --dry-run).
Giữ nguyên lệnh; nếu có khác biệt theo ngôn ngữ địa phương, hãy thêm chú thích.

# Đúng
kubectl get pods --namespace default

# Sai (cờ bị dịch) ❌
kubectl get pods --nom-espace defaut

Lưu ý về Markdown

Bảng: giữ nguyên dấu gạch dọc và căn chỉnh; không làm vỡ cột.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

Chú thích/cảnh báo: giữ nguyên ký hiệu mà công cụ của bạn sử dụng.
HTML nội tuyến: tránh chỉnh sửa thẻ/thuộc tính.
Chú thích cuối trang: giữ nguyên id và thứ tự.
Dấu ngoặc kép thông minh: ưu tiên dấu ngoặc thẳng trong ngữ cảnh mã nguồn.

Hình ảnh và Trợ năng

Địa phương hóa văn bản thay thế (alt text) theo ý nghĩa, không theo nội dung điểm ảnh.
Ưu tiên ảnh chụp màn hình không phụ thuộc ngôn ngữ (làm nổi bật giao diện thay vì ngôn ngữ), hoặc cung cấp bộ ảnh riêng cho từng ngôn ngữ.
Giữ đồng bộ tệp nguồn sơ đồ (ví dụ: Mermaid) giữa các ngôn ngữ.
Tránh văn bản nhúng trong hình ảnh; tách chú thích và nhãn ra ngoài.

SEO và Metadata

Dịch tiêu đề, mô tả và tiêu đề bằng từ khóa phù hợp với ngôn ngữ địa phương.
Giữ nguyên URL chuẩn và hreflang theo quy tắc của trang web.
Không dịch các khóa meta/property hoặc khóa JSON‑LD.
Đồng bộ slug với chiến lược anchor để tránh lỗi 404.

Quy trình làm việc và Tự động hóa

Sử dụng quy trình CAT/LLM để giữ nguyên các đoạn mã và thẻ.
Khóa thuật ngữ bằng bảng thuật ngữ và danh sách không dịch.
Thêm pre-commit hooks để lint Markdown và kiểm tra hợp lệ JSON/YAML.
Chạy công cụ kiểm tra liên kết và xác thực anchor trên mỗi PR.
Gom các thay đổi thành từng phần nhỏ, dễ kiểm tra và theo dõi sự khác biệt.

Công cụ đề xuất (tùy chỉnh theo stack của bạn):

Lint Markdown và kiểm tra liên kết trong CI
Bước phân tích cú pháp JSON/YAML để phát hiện lỗi cú pháp
Bộ regex để quét các placeholder và định dạng số

QA và Kiểm định

Thực hiện các kiểm tra sau trước khi merge:

Build trang web để phát hiện lỗi cú pháp: pnpm build
Kiểm tra kiểu dữ liệu/nội dung (Astro content collections): pnpm astro check
Xem trước và kiểm tra nhanh các trang quan trọng: pnpm preview
Xác thực các ví dụ mã có thể biên dịch hoặc chạy được (nếu áp dụng)
Chạy công cụ kiểm tra liên kết và anchor; sửa mọi lỗi 404 hoặc anchor hỏng

Các lỗi thường gặp

Vô tình dịch các key/placeholder.
Làm hỏng code fence hoặc dấu phân cách bảng.
Địa phương hóa đường dẫn file, cờ hoặc tên API.
Thay đổi tiêu đề mà không cập nhật liên kết anchor.
Thêm dấu ngoặc kép thông minh vào trong mã hoặc JSON.

Phụ lục: Danh sách kiểm tra nhanh

Trước khi bắt đầu (5 mục)

Đã chuẩn bị bảng thuật ngữ và danh sách không dịch
Đã xác định và bảo vệ token/placeholder
Đã xác nhận chiến lược anchor/slug
Đã lập bản đồ các liên kết (nội bộ và bên ngoài)
Có bản dựng staging

An toàn cho ví dụ mã (5 mục)

Code fence và gợi ý ngôn ngữ còn nguyên vẹn
Không thay đổi identifier/import; chỉ dịch chú thích
Giữ nguyên placeholder và dấu ngoặc kép
Kiểm tra copy-paste thành công
Đánh dấu snippet lỗi thời cho người bảo trì

Dữ liệu có cấu trúc (5 mục)

Không thay đổi key và kiểu dữ liệu
Giữ nguyên dấu ngoặc kép/ký tự escape/thụt lề
Số và boolean giữ đúng kiểu dữ liệu
Parser/linter chạy thành công tại máy local
Xem lại diff để tránh thay đổi key ngoài ý muốn

Bài đọc liên quan