Dịch nội dung¶

Bắt đầu dịch¶

Nếu bạn muốn đóng góp cho công tác dịch thuật của BeeWare, bạn cần có một tài khoản trên Weblate. Tạo tài khoản mới nếu bạn chưa có; sau đó hãy cho chúng tôi biết rằng bạn muốn tham gia hỗ trợ công tác dịch thuật.

Có hai cách để bạn cho chúng tôi biết rằng bạn muốn tham gia hỗ trợ công việc dịch thuật:

Nếu bạn đang dùng Discord, hãy tham gia máy chủ BeeWare, và vào kênh #translations.
Nếu bạn chưa tham gia Discord, bạn có thể tạo một vấn đề mới trên kho lưu trữ BeeWare Docs Tools.

Trong cả hai trường hợp, vui lòng để lại tin nhắn kèm theo các thông tin sau:

Tên người dùng Weblate của bạn
Ngôn ngữ mà bạn dự định dịch nội dung sang

Khi chúng tôi có thông tin này, chúng tôi sẽ thêm bạn vào đội.

Thêm bản dịch mới¶

Nếu ngôn ngữ mà bạn dự định hỗ trợ chưa có sẵn, bạn cần thực hiện thêm một số bước trước khi có thể bắt đầu:

Tạo tệp /docs/mkdocs.language-code.yml, với nội dung dành riêng cho ngôn ngữ đó.
Cập nhật tox.ini để bổ sung các lệnh xây dựng ngôn ngữ mới.
Cập nhật /docs/config.yml để bao gồm ngôn ngữ trong extra: alternate:.

Phần sau đây trình bày các thay đổi cần thiết bằng cách lấy tiếng Đức làm ví dụ; bản dịch tiếng Đức đã có sẵn; hãy thay thế các tham chiếu đến tiếng Đức, de, hoặc nội dung khác bằng ngôn ngữ mà bạn đang nhắm đến.

Một tệp cấu hình MkDocs mới¶

Đầu tiên, hãy tạo một tệp mới có tên mkdocs.de.yml trong thư mục docs, với nội dung như sau:

INHERIT: config.yml
site_name: BeeWare Docs Tools Dokumentation
site_url: https://beeware-docs-tools.beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  language_url: de/
  translation_type: machine
  header:
    About: Über
    Documentation: Dokumentation
    Community: Gemeinschaft
    Contributing: Mitwirken
    News: Neuigkeiten
    Sponsor: Förderer

Đây là những gì đang diễn ra trong tệp này:

Tệp này kế thừa nội dung cấu hình từ config.yml.
Giá trị site_name đã được dịch.
Giá trị site_url là URL của trang web dự án, kèm theo mã ngôn ngữ.
Dấu docs_dir phải là mã ngôn ngữ.
Giá trị theme: language: phải là mã ngôn ngữ, như được quy định trong chủ đề MkDocs Material. Đối với hầu hết các ngôn ngữ, giá trị này sẽ giống với mã ngôn ngữ docs_dir; nhưng đối với một số ngôn ngữ (đặc biệt là những ngôn ngữ có các biến thể vùng như zh_CN), sẽ có sự khác biệt.
Dấu extra: language_url: phải là mã ngôn ngữ, tiếp theo là một dấu gạch chéo, ví dụ: de/ cho tiếng Đức.
extra: translation_type: sẽ giữ nguyên là machine cho đến khi bản dịch đạt 100% lần đầu tiên; khi đó, nó sẽ chuyển thành human. Nó sẽ quay trở lại machine từ human nếu tỷ lệ dịch giảm xuống dưới 90%.
Nội dung trong extra: header là bản dịch của các tiêu đề xuất hiện trên thanh tiêu đề. Định nghĩa này không bắt buộc trên trang web chính của BeeWare; nó chỉ bắt buộc trên các trang web khác (chẳng hạn như trang hướng dẫn hoặc tài liệu dự án).

Cập nhật `tox.ini`¶

Bạn sẽ cần thực hiện một số thay đổi đối với tệp tox.ini.

Bạn sẽ thêm nội dung sau:

Thêm cờ mã ngôn ngữ mới vào dòng tiêu đề bắt đầu bằng [testenv:docs, trong đó mã ngôn ngữ được đặt trước dấu -, không có khoảng trắng, ví dụ: -de.
Quy tắc loại trừ mã ngôn ngữ mới đối với lệnh đầu tiên, bắt đầu bằng !lint, được đặt trước bởi -!, không có khoảng trắng, ví dụ: -!de.
Thêm mã ngôn ngữ mới vào dòng bắt đầu bằng translate : build_po_translations.
Thêm mã ngôn ngữ mới vào dòng bắt đầu bằng translate : update_machine_translations
Một lệnh mới, bắt đầu bằng, ví dụ như de : build_md_translations cho tiếng Đức, được sắp xếp theo thứ tự bảng chữ cái trong danh sách các lệnh dành riêng cho ngôn ngữ hiện có và có nội dung tương ứng với các lệnh đó, kèm theo mã ngôn ngữ mới.
Thêm mã ngôn ngữ mới vào dòng bắt đầu bằng all:.

Cập nhật `config.yml`¶

Thêm ngôn ngữ vào config.yml để nó xuất hiện trong trình chọn ngôn ngữ ở đầu trang. Tìm phần bắt đầu bằng extra:, sau đó tìm phần con bắt đầu bằng alternate:. Đối với tiếng Đức, bạn cần thêm đoạn sau:

- name: Deutsch
      link: /de/
      lang: de

Tên ngôn ngữ cần được dịch sang ngôn ngữ đó. Liên kết phải bao gồm các dấu /.

Chạy `tox translate`¶

Bây giờ bạn có thể chạy tox -e docs-translate. Thao tác này sẽ tạo ra một tệp dịch trống; nếu bạn có tài khoản DeepL, bạn có thể sử dụng tài khoản đó để điền các bản dịch máy ban đầu. Nếu bạn không có tài khoản DeepL, cũng không sao — chúng tôi sẽ tự thực hiện các bản dịch ban đầu trước khi chấp nhận yêu cầu pull.

Hướng dẫn dịch thuật¶

Sau khi bạn đã được thêm vào nhóm, đã đến lúc đăng nhập vào Weblate và bắt đầu dịch các chuỗi văn bản.

Dịch theo ngữ cảnh so với dịch từng từ¶

Việc giữ nguyên giọng điệu của bản gốc tiếng Anh quan trọng hơn là cố gắng dịch từng từ một. Chúng tôi cố gắng viết nội dung một cách thân thiện và hơi mang tính khẩu ngữ; mong bạn cũng cố gắng giữ nguyên tinh thần đó trong bản dịch của mình.

Nếu văn bản tiếng Anh chứa một thành ngữ tiếng Anh mang tính đặc trưng mạnh mẽ, đừng cảm thấy bắt buộc phải giữ nguyên thành ngữ đó nếu trong ngôn ngữ của bạn có một cách diễn đạt tương đương mà vẫn truyền tải ý nghĩa tốt không kém. Nếu thuật ngữ hoặc cụm từ trong văn bản tiếng Anh là một thành ngữ hoặc từ lóng đặc biệt, đừng ngần ngại đề xuất với chúng tôi rằng nên xem xét điều chỉnh. Ngay cả với người nói tiếng Anh, thành ngữ và từ lóng cũng có thể gây khó khăn. Đôi khi chúng tôi cần điều chỉnh văn bản tiếng Anh để làm cho nó dễ hiểu hơn cho cả người dịch lẫn người đọc.

Tôi có nên dịch nó không?¶

Các mục sau đây không nên được dịch hoặc cập nhật:

Lệnh. Ví dụ, trong câu "Bạn nên chạy `briefcase create`.", chỉ phần "Bạn nên chạy" mới cần được dịch.
Không gian tên, chẳng hạn như tên lớp, phương thức hoặc thuộc tính.
URL liên kết. Các liên kết Markdown tiêu chuẩn nên được hiển thị trong Weblate dưới dạng [Link text]{1}, trong đó 1 là vị trí của liên kết trong chuỗi so với các liên kết khác có thể có. Nếu URL đầy đủ được bao gồm trong chuỗi, như [Link text](https://example.com/), thì URL đó nên được bỏ qua khi dịch.
Các liên kết tham chiếu chứa tên lớp, phương thức hoặc thuộc tính. Những liên kết này nên được giữ nguyên, bao gồm cả dấu gạch chéo ngược. Mọi phần của liên kết ví dụ được hiển thị ở đây sẽ không được dịch.
```
[`Class.attribute`][Class.attribute]
```
Nội dung của một liên kết tham chiếu. Ví dụ, link-content sẽ bị bỏ qua trong đoạn sau:
```
[Nội dung liên kết][link-content]
```
Hướng dẫn Jinja. Đây là bất kỳ nội dung nào được bao bọc bởi hai cặp dấu ngoặc nhọn đối xứng, hoặc một cặp dấu ngoặc nhọn đơn đối xứng có chứa ký hiệu phần trăm ở mỗi đầu. Lưu ý: Việc đưa ví dụ về cú pháp vào đây sẽ khiến plugin Macros cố gắng hiển thị nó; hãy xem tài liệu về Macros để tham khảo các ví dụ.
Điểm neo tùy chỉnh. Chúng thường xuất hiện sau các tiêu đề hoặc phía trên một số nội dung, và được định dạng dưới dạng { #anchor }.
Cấu trúc câu cảnh báo. Trong ví dụ sau, từ "cảnh báo" không nên được dịch. Quy tắc này áp dụng cho tất cả các dạng cảnh báo, bao gồm chú thích, cảnh báo, v.v. Vui lòng tham khảo phần tiếp theo để biết thông tin về cách dịch phần nội dung còn lại.
```
/// admonition | Tiêu đề trang

Nội dung.

///
```
Dấu nháy đơn. Chúng được thiết kế để hiển thị dưới dạng dấu nháy đơn; chúng được sử dụng để định dạng cả mã trong dòng và khối mã.
Cú pháp để nhúng nội dung bên ngoài. Đây là bất kỳ nội dung nào nằm trên cùng một dòng với -8<-, hoặc nằm trên các dòng nằm giữa hai cặp -8<- trên các dòng riêng biệt.

Các mục sau đây nên được dịch:

Văn bản liên kết. Trong cú pháp liên kết, văn bản được đặt trước URL và được bao quanh bởi dấu ngoặc nhọn, như [Link text](URL). Các liên kết Markdown tiêu chuẩn nên xuất hiện trong Weblate dưới dạng [Link text]{1}, trong đó 1 là vị trí của liên kết trong chuỗi văn bản so với các liên kết khác có thể có.
Văn bản liên kết tham chiếu. Ví dụ: Link text sẽ được dịch như sau:
```
[Nội dung liên kết][link-content]
```
Tiêu đề và nội dung của lời khuyên. Trong ví dụ về lời khuyên trước đó, "Tiêu đề trang" và "Nội dung" cần được dịch.

Weblate¶

Chúng tôi sử dụng Weblate để dịch nội dung. Khi thêm bản dịch mới, chúng tôi sử dụng DeepL để dịch máy nhằm tạo ra bản dịch sơ bộ. Điều đó có nghĩa là, thông thường, nội dung mà bạn sẽ dịch đã được dịch máy sẵn. Chúng tôi mong rằng bạn, với tư cách là người dịch, sẽ rà soát, chỉnh sửa và hoàn thiện bản dịch máy hiện có.

Weblate xử lý mọi thứ theo từng chuỗi. Hệ thống sẽ gom các thay đổi lại và cứ sau vài giờ, nó sẽ gửi một bản cập nhật hàng loạt bao gồm tất cả các chuỗi đã thay đổi trong khoảng thời gian đó. Do đó, có thể mất vài giờ để các thay đổi của bạn hiển thị trên trang web, nhưng bạn có thể mong đợi bản cập nhật sẽ xuất hiện trong vòng bốn giờ.

Nếu sau khoảng thời gian đó, các thay đổi của bạn vẫn chưa hiển thị, nguyên nhân có thể là do lỗi định dạng, dẫn đến việc quá trình biên dịch tài liệu cho ngôn ngữ đó bị lỗi. Bất kỳ lỗi định dạng nào trong bất kỳ chuỗi văn bản nào cũng sẽ ngăn toàn bộ bản dịch được công khai. Bạn có thể theo dõi trang biên dịch của ngôn ngữ mình để xem liệu quá trình biên dịch đã thành công hay chưa. Liên kết được định dạng tương tự như liên kết này đến trang xây dựng tiếng Pháp https://app.readthedocs.org/projects/beeware-docs-tools/; hãy thay đổi mã ngôn ngữ thành ngôn ngữ của bạn để xem trang xây dựng tương ứng. Điều này sẽ hiển thị trạng thái của bản xây dựng mới nhất của trang web. Nếu quá trình xây dựng thất bại, hãy xem nhật ký xây dựng và xem liệu bạn có thể xác định được nguyên nhân của vấn đề hay không.