Dịch API Documentation: thuật ngữ nào nên dịch và thuật ngữ nào nên giữ nguyên? Đây là câu hỏi quyết định trực tiếp đến khả năng sử dụng của tài liệu. Một bản dịch quá sát chữ có thể khiến lập trình viên khó đối chiếu với mã nguồn; ngược lại, giữ quá nhiều tiếng Anh lại làm người mới khó tiếp cận. Cách phù hợp là dịch những nội dung mang tính diễn giải cho người đọc, đồng thời bảo toàn các thành phần có giá trị định danh hoặc cần được nhập chính xác vào hệ thống.
Thay vì áp dụng một quy tắc cho mọi từ, nhóm biên dịch nên xây dựng quy ước thuật ngữ, xác định đối tượng độc giả và kiểm tra tài liệu trong bối cảnh triển khai thực tế. Mục tiêu không chỉ là câu văn tự nhiên mà còn là để người đọc thực hiện đúng thao tác.
Nguyên tắc cốt lõi khi dịch API Documentation
API Documentation thường gồm hai lớp nội dung: lớp giao diện kỹ thuật mà lập trình viên phải sao chép, gọi hoặc cấu hình chính xác; và lớp diễn giải giúp họ hiểu mục đích, điều kiện và cách dùng. Lớp thứ nhất cần ưu tiên tính nguyên vẹn, còn lớp thứ hai nên được dịch rõ ràng theo ngôn ngữ của độc giả.
Một tiêu chí đơn giản để ra quyết định là đặt câu hỏi: người đọc có phải gõ đúng cụm từ này vào mã nguồn, URL, công cụ hay tệp cấu hình không? Nếu có, thông thường cần giữ nguyên. Nếu cụm từ chỉ dùng để giải thích khái niệm hoặc hướng dẫn thao tác, có thể dịch, kèm thuật ngữ gốc ở lần xuất hiện đầu tiên khi điều đó hữu ích.
- Ưu tiên khả năng thực thi: người đọc không được hiểu nhầm chuỗi cần nhập.
- Ưu tiên tính nhất quán: một khái niệm không nên lúc dịch, lúc giữ nguyên mà không có quy ước.
- Ưu tiên bối cảnh: cùng một từ có thể là thuật ngữ chung trong đoạn giải thích nhưng lại là tên trường trong ví dụ JSON.
- Không Việt hóa tùy tiện: tên gọi quen thuộc trong hệ sinh thái lập trình thường nên được giữ để dễ tra cứu và đối chiếu.
Những thành phần nên giữ nguyên
Các chuỗi có vai trò định danh kỹ thuật cần được bảo toàn nguyên dạng. Việc dịch chúng có thể làm ví dụ không chạy, gây sai cấu hình hoặc khiến người đọc không tìm thấy mục tương ứng trong giao diện, thư viện và mã nguồn.
Tên API, endpoint và phương thức yêu cầu
Giữ nguyên tên API, đường dẫn endpoint, phiên bản và phương thức như GET, POST, PUT, PATCH, DELETE. Phần mô tả có thể dịch: “Gửi yêu cầu GET đến endpoint /users để lấy danh sách người dùng.” Không chuyển đường dẫn thành tiếng Việt và không đổi chữ hoa/thường của phương thức.
Tên biến, trường dữ liệu và giá trị định danh
Các key trong JSON, tên tham số, tên thuộc tính, tên hàm, lớp, gói, module, biến môi trường, header, mã lỗi, chuỗi enum và giá trị cấu hình nên giữ nguyên. Chẳng hạn, giữ access_token, Content-Type, client_id, invalid_request. Có thể dịch phần giải thích thành “Tham số client_id: mã định danh của ứng dụng khách”.
Mã nguồn và nội dung cần sao chép
Không dịch nội dung bên trong code block, lệnh CLI, mẫu request/response, biểu thức chính quy, URL, tên tệp, khóa bí mật hoặc chuỗi thông báo mà hệ thống yêu cầu khớp chính xác. Khi cần làm rõ, thêm diễn giải ở câu trước hoặc sau đoạn mã thay vì chỉnh sửa mã.
Những thuật ngữ nên dịch để tài liệu dễ đọc
Phần lớn văn bản giải thích nên được Việt hóa: mục đích của endpoint, điều kiện tiên quyết, mô tả tham số, luồng xác thực, giới hạn sử dụng, hướng dẫn xử lý lỗi và cảnh báo bảo mật. Đây là phần giúp người đọc hiểu “vì sao” và “khi nào” cần thực hiện một thao tác.
Nhiều thuật ngữ phổ biến có thể dịch nhất quán sang tiếng Việt, đặc biệt khi chúng không phải tên riêng của đối tượng trong mã:
| Ngữ cảnh tiếng Anh | Cách diễn đạt tiếng Việt phù hợp |
|---|---|
| request / response | yêu cầu / phản hồi |
| parameter | tham số |
| authentication | xác thực |
| authorization | phân quyền hoặc cấp quyền, tùy ngữ cảnh |
| rate limit | giới hạn tần suất yêu cầu |
| pagination | phân trang |
| retry | thử lại |
| timeout | hết thời gian chờ hoặc thời gian chờ, tùy câu |
Không nhất thiết phải ép mọi thuật ngữ thành một từ thuần Việt. Nếu một khái niệm tiếng Anh được dùng rộng rãi trong cộng đồng kỹ thuật và bản dịch có thể gây mơ hồ, cách viết “thuật ngữ tiếng Việt (English term)” ở lần đầu thường cân bằng tốt giữa khả năng đọc và khả năng tra cứu.
Dịch API Documentation: xử lý thuật ngữ nửa kỹ thuật nửa nghiệp vụ
Nhóm khó nhất là các từ vừa có nghĩa kỹ thuật vừa gắn với nghiệp vụ sản phẩm, ví dụ resource, payload, callback, webhook, scope, token hoặc schema. Không nên quyết định chỉ dựa trên nghĩa từ điển; cần xem từ đó đang xuất hiện trong giao diện, mã mẫu hay câu giải thích.
Với các từ có nhiều cách dịch, hãy chọn một cách gọi chính và ghi nhận vào bảng thuật ngữ nội bộ. Ví dụ, payload có thể được diễn giải là “dữ liệu trong nội dung yêu cầu/phản hồi”, thay vì cố thay thế bằng một từ đơn trong mọi trường hợp. Webhook thường có thể giữ nguyên, rồi giải thích ngắn ở lần đầu là cơ chế hệ thống gửi thông báo đến một URL đã đăng ký khi sự kiện xảy ra.
Không dịch tên hiển thị của một trường nếu người dùng cần tìm đúng tên đó trong dashboard hoặc cần dùng đúng chuỗi đó trong request. Hãy dịch nhãn giải thích xung quanh tên trường.
Cũng cần phân biệt authentication với authorization. Hai khái niệm này thường bị gộp chung thành “xác thực”, nhưng một bên liên quan đến việc chứng minh danh tính, bên kia liên quan đến quyền truy cập. Dịch tách bạch giúp hướng dẫn bảo mật chính xác hơn.
Cách trình bày song ngữ mà không làm tài liệu rối
Trình bày song ngữ phù hợp khi tài liệu hướng đến lập trình viên quen tra cứu bằng tiếng Anh, hoặc khi thuật ngữ gốc xuất hiện trong công cụ, SDK và thông báo lỗi. Tuy nhiên, lặp tiếng Anh trong từng câu sẽ làm nội dung nặng nề. Nên giới thiệu thuật ngữ gốc tại lần đầu xuất hiện trong một phạm vi nội dung hợp lý, sau đó dùng nhất quán cách gọi đã chọn.
Một số mẫu trình bày dễ áp dụng:
- “Xác thực (authentication) được thực hiện trước khi gửi yêu cầu.”
- “Tham số page_size (kích thước trang) xác định số bản ghi tối đa trong mỗi phản hồi.”
- “Khi nhận lỗi rate_limit_exceeded, hãy giảm tần suất gửi yêu cầu và thử lại sau.”
Phần tiêu đề bảng tham số cũng nên tách rõ giữa tên kỹ thuật và diễn giải. Có thể dùng các cột như “Tên tham số”, “Kiểu dữ liệu”, “Bắt buộc”, “Mô tả”. Trong đó tên tham số giữ nguyên, còn kiểu dữ liệu và mô tả được dịch theo quy ước của tài liệu.
Quy trình kiểm soát nhất quán trước khi xuất bản
Một bản dịch tốt cần được kiểm tra như một phần của quy trình phát triển tài liệu, không chỉ đọc lại về ngữ pháp. Trước hết, lập danh sách thuật ngữ gồm thuật ngữ gốc, cách viết được chấp nhận, cách dịch, ví dụ ngữ cảnh và ghi chú “giữ nguyên” nếu cần. Danh sách này đặc biệt hữu ích khi nhiều người cùng dịch hoặc tài liệu được cập nhật theo phiên bản API.
- Đánh dấu toàn bộ chuỗi không được thay đổi: mã, URL, endpoint, key JSON, header, enum, tên SDK và lệnh.
- Thống nhất bản dịch cho các khái niệm lặp lại trong phần diễn giải.
- Đối chiếu tên kỹ thuật trong câu văn với ví dụ request, response và giao diện liên quan.
- Rà soát các câu cảnh báo, điều kiện bắt buộc, đơn vị thời gian và hướng dẫn lỗi để tránh thay đổi ý nghĩa thao tác.
- Nhờ người hiểu API đọc thử theo một tác vụ cụ thể, chẳng hạn tạo yêu cầu, xác thực hoặc phân trang, để phát hiện chỗ dịch đúng chữ nhưng khó dùng.
Khi API thay đổi, hãy cập nhật đồng thời bảng thuật ngữ và bản dịch. Điều này hạn chế tình trạng tài liệu tiếng Việt dùng tên cũ trong khi tài liệu kỹ thuật hoặc mã mẫu đã chuyển sang tên mới.
Câu hỏi thường gặp
Có nên dịch tên endpoint API không?
Không nên. Đường dẫn endpoint là chuỗi kỹ thuật cần giữ nguyên để người dùng gọi API chính xác; chỉ dịch phần mô tả chức năng của endpoint.
GET, POST và DELETE có cần dịch không?
Nên giữ nguyên vì đây là tên phương thức HTTP. Có thể viết phần giải thích bằng tiếng Việt, chẳng hạn “dùng GET để lấy dữ liệu”.
Tên trường JSON có được Việt hóa không?
Không nên nếu tên trường xuất hiện trong request hoặc response. Giữ nguyên key JSON và dịch mô tả ý nghĩa của trường.
Khi nào nên ghi cả tiếng Việt lẫn tiếng Anh?
Nên dùng ở lần đầu thuật ngữ quan trọng xuất hiện, nhất là khi thuật ngữ gốc có trong SDK, dashboard hoặc tài liệu tham chiếu khác.
Làm sao tránh dịch thuật ngữ không nhất quán giữa các trang API?
Hãy dùng bảng thuật ngữ chung, quy định rõ từ nào giữ nguyên và từ nào dịch, rồi rà soát lại khi API hoặc tài liệu được cập nhật.
