Bản dịch
Hướng dẫn bản địa hóa chủ đề.
Các chủ đề tích hợp đi kèm với MkDocs cung cấp hỗ trợ cho bản dịch. Đây là hướng dẫn dành cho người dịch, ghi lại quy trình đóng góp bản dịch mới và/hoặc cập nhật bản dịch hiện có. Để biết hướng dẫn về việc sửa đổi các chủ đề hiện có, hãy xem Hướng dẫn đóng góp . Để bật một bản dịch cụ thể, hãy xem tài liệu về chủ đề cụ thể mà bạn đang sử dụng trong Hướng dẫn sử dụng . Đối với bản dịch của các chủ đề của bên thứ ba, vui lòng xem tài liệu cho các chủ đề đó. Để một chủ đề của bên thứ ba sử dụng các công cụ và phương pháp dịch của MkDocs, chủ đề đó phải được cấu hình đúng để sử dụng các công cụ đó.
Ghi chú
Bản dịch chỉ áp dụng cho văn bản có trong mẫu của chủ đề, chẳng hạn như liên kết "tiếp theo" và "trước đó". Nội dung Markdown của một trang không được dịch. Nếu bạn muốn tạo tài liệu đa ngôn ngữ, bạn cần kết hợp bản địa hóa chủ đề với plugin quốc tế hóa/bản địa hóa của bên thứ ba.
Bản địa hóa chủ đề sử dụng dự án babel để tạo và biên dịch các tệp bản địa hóa. Bạn sẽ cần phải làm việc từ cây làm việc git trên máy cục bộ của mình để sử dụng các lệnh dịch.
Xem Hướng dẫn đóng góp để biết hướng dẫn về cách Cài đặt để Phát triển và Gửi Yêu cầu kéo . Các hướng dẫn trong tài liệu này giả định rằng bạn đang làm việc từ một môi trường phát triển được cấu hình đúng.
Đảm bảo các yêu cầu dịch thuật được cài đặt trong môi trường của bạn:
pip install 'mkdocs[i18n]'
Thêm bản dịch ngôn ngữ vào chủ đề
Nếu ngôn ngữ yêu thích của bạn chưa được hỗ trợ trên một (hoặc cả hai) chủ đề tích hợp ( mkdocsvà readthedocs), bạn có thể dễ dàng đóng góp bản dịch bằng cách làm theo các bước dưới đây.
Sau đây là tóm tắt nhanh về những gì bạn cần làm:
- Phân nhánh và sao chép kho lưu trữ MkDocs , sau đó cài đặt MkDocs để phát triển nhằm thêm và thử nghiệm bản dịch.
- Khởi tạo danh mục bản địa hóa mới cho ngôn ngữ của bạn (nếu đã có bản dịch cho ngôn ngữ của bạn, hãy làm theo hướng dẫn để cập nhật tệp bản địa hóa chủ đề ).
- Thêm bản dịch cho mọi chỗ giữ chỗ văn bản trong danh mục đã bản địa hóa.
- Phục vụ và thử nghiệm các chủ đề đã dịch cho ngôn ngữ của bạn tại địa phương.
- Cập nhật tài liệu về các bản dịch được hỗ trợ cho từng chủ đề đã dịch.
- Đóng góp bản dịch của bạn thông qua Yêu cầu kéo.
Ghi chú
Ngôn ngữ bản dịch thường được xác định bằng mã ngôn ngữ ISO-639-1 (2 chữ cái). Mặc dù mã lãnh thổ/khu vực/quận cũng được hỗ trợ, nhưng chỉ nên thêm bản dịch theo vị trí cụ thể sau khi bản dịch ngôn ngữ chung đã hoàn tất và phương ngữ khu vực yêu cầu sử dụng thuật ngữ khác với bản dịch ngôn ngữ chung.
Phân nhánh và sao chép kho lưu trữ MkDocs
Trong các bước sau, bạn sẽ làm việc với một nhánh của kho lưu trữ MkDocs. Làm theo hướng dẫn để nhánh và sao chép kho lưu trữ MkDocs .
Để kiểm tra bản dịch, bạn cũng cần cài đặt MkDocs để phát triển từ nhánh của mình.
Khởi tạo danh mục bản địa hóa
Các mẫu cho mỗi chủ đề đều chứa các chỗ giữ chỗ văn bản đã được trích xuất vào tệp Mẫu đối tượng di động ( messages.pot), có trong thư mục của mỗi chủ đề.
Khởi tạo một danh mục bao gồm việc chạy lệnh sẽ tạo cấu trúc thư mục cho ngôn ngữ mong muốn của bạn và chuẩn bị messages.potệp Portable Object ( ) bắt nguồn từ pottệp chủ đề.
Sử dụng init_cataloglệnh trên thư mục của từng chủ đề và cung cấp mã ngôn ngữ phù hợp ( -l <language>).
Mã ngôn ngữ hầu như luôn chỉ là hai chữ cái viết thường, chẳng hạn như sv, nhưng trong một số trường hợp, nó cần phải được giải thích rõ ràng hơn.
Nhìn thấy:
Đặc biệt, cách để biết ptngôn ngữ đó nên được phân biệt rõ ràng là pt_PTvà pt_BRlà trang đăng ký thẻ phụ Ngôn ngữ có chứa pt-nếu bạn tìm kiếm nó. Trong khi đó svnên chỉ giữ nguyên sv, vì trang đó không chứa sv-.
Vì vậy, nếu chúng ta chọn es(tiếng Tây Ban Nha) làm mã ngôn ngữ ví dụ, để thêm bản dịch cho cả hai chủ đề tích hợp, hãy chạy các lệnh sau:
pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es
Lệnh trên sẽ tạo ra cấu trúc tệp như sau:
mkdocs/themes/mkdocs/locales ├── es │ └── LC_MESSAGES │ └── messages.po
Bây giờ bạn có thể chuyển sang bước tiếp theo và thêm bản dịch cho mọi chỗ giữ chỗ văn bản trong danh mục đã bản địa hóa.
Cập nhật bản dịch chủ đề
messages.potNếu tệp mẫu của chủ đề đã được cập nhật kể từ messages.polần cập nhật cuối cùng cho ngôn ngữ của bạn, hãy làm theo các bước dưới đây để cập nhật tệp chủ đề messages.po:
- Cập nhật danh mục bản dịch của chủ đề để làm mới chỗ giữ chỗ văn bản có thể dịch của mỗi chủ đề.
- Dịch các chỗ giữ chỗ văn bản có thể dịch mới được thêm vào sang mọi
messages.pongôn ngữ tệp danh mục mà bạn có thể. - Phục vụ và thử nghiệm các chủ đề đã dịch cho ngôn ngữ của bạn tại địa phương.
- Đóng góp bản dịch của bạn thông qua Yêu cầu kéo.
Cập nhật danh mục bản dịch
Bước này phải được hoàn tất sau khi mẫu chủ đề đã được cập nhật cho từng ngôn ngữ mà bạn cảm thấy thoải mái khi đóng góp bản d ịch.
Để cập nhật frdanh mục bản dịch của cả hai chủ đề tích hợp, hãy sử dụng các lệnh sau:
pybabel update --ignore-obsolete --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr pybabel update --ignore-obsolete --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l fr
Bây giờ bạn có thể chuyển sang bước tiếp theo và thêm bản dịch cho mọi chỗ giữ chỗ văn bản được cập nhật trong danh mục đã bản địa hóa.
Biên dịch các chủ đề MkDocs
Bây giờ messages.pocác tệp đã bản địa hóa của bạn đã sẵn sàng, tất cả những gì bạn cần làm là thêm bản dịch vào từng msgstrmục msgidtrong tệp.
msgid "Next" msgstr "Siguiente"
Cảnh báo
Không sửa đổi msgidvì nó là chung cho tất cả các bản dịch. Chỉ cần thêm bản dịch của nó vào msgstrmục.
Sau khi dịch xong tất cả các thuật ngữ được liệt kê trong potệp, bạn sẽ muốn kiểm tra chủ đề đã bản địa hóa của mình .
Kiểm tra bản dịch chủ đề
Để kiểm tra một chủ đề có bản dịch, trước tiên bạn cần biên dịch messages.po các tệp của chủ đề thành messages.mocác tệp. Các lệnh sau sẽ biên dịch esbản dịch cho cả hai chủ đề tích hợp:
pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -l es
Lệnh trên cho kết quả là cấu trúc tệp sau:
mkdocs/themes/mkdocs/locales ├── es │ └── LC_MESSAGES │ ├── messages.mo │ └── messages.po
Lưu ý rằng messages.motệp đã biên dịch được tạo dựa trên messages.potệp bạn vừa chỉnh sửa.
Sau đó sửa đổi mkdocs.ymltệp ở thư mục gốc của dự án để kiểm tra ngôn ngữ mới và/hoặc ngôn ngữ đã cập nhật:
theme: name: mkdocs locale: es
Cuối cùng, hãy chạy mkdocs serveđể kiểm tra phiên bản địa phương mới của chủ đề.
Ghi chú
Quá trình xây dựng và phát hành sẽ đảm nhiệm việc biên dịch và phân phối tất cả các ngôn ngữ cho người dùng cuối để bạn chỉ phải lo đóng góp các messages.potệp dịch văn bản thực tế (phần còn lại sẽ bị git bỏ qua).
Sau khi bạn hoàn tất việc kiểm tra công việc của mình, hãy chắc chắn hoàn tác thay đổi cài localeđặt trong mkdocs.ymltệp trước khi gửi thay đổi.
Cập nhật tài liệu chủ đề
Trang Chọn chủ đề của bạn sẽ tự động cập nhật với tất cả các tùy chọn ngôn ngữ có sẵn.
Đóng góp bản dịch
Bây giờ đã đến lúc bạn đóng góp công sức của mình cho dự án. Cảm ơn bạn!