Cách tạo tệp .pot cho giao diện hoặc plugin
Bạn vừa hoàn thành một plugin WordPress mà bạn muốn chia sẻ với thế giới. Mã nguồn hoạt động, các tính năng ổn định, và một người ở Đức gửi email hỏi cách dịch nó sang tiếng Đức. Bạn chỉ họ đến thư mục languages và nhận ra không có gì ở đó. Không có template, không có chuỗi, không có cách nào để người dịch biết được những gì cần dịch. Plugin của bạn về mặt kỹ thuật chỉ "sẵn sàng dịch" trên danh nghĩa mà thôi.
Mọi dự án WordPress có thể dịch đều bắt đầu với một tệp: template .pot. Trước khi bất kỳ ai có thể tạo ra phiên bản tiếng Đức, tiếng Pháp hoặc tiếng Nhật, bạn phải tạo một tệp POT liệt kê mọi chuỗi hướng tới người dùng trong mã của bạn. Bỏ qua bước này và người dịch sẽ phải đọc mã nguồn của bạn từng dòng một, đoán xem chuỗi nào được dùng để hiển thị.
Hướng dẫn này sẽ trình bày hai phần của công việc: chuẩn bị mã nguồn của bạn để các chuỗi có thể được phát hiện, và sau đó tạo ra tệp .pot bằng ba công cụ khác nhau. Chúng ta sẽ sử dụng WP-CLI, Poedit, và phương pháp cũ makepot/grunt, với các lệnh thực tế mà bạn có thể sao chép. Cuối cùng bạn sẽ có một template sạch sẵn sàng để giao cho bất kỳ người dịch nào.
Bước Một: Đánh Dấu Các Chuỗi Của Bạn Là Có Thể Dịch
Trước khi bạn có thể tạo một tệp POT, mọi chuỗi mà người dùng có thể thấy cần được gói gọn trong một hàm Gettext. Một bộ quét chỉ có thể trích xuất các chuỗi mà nó nhận ra, và nó nhận ra chúng thông qua các lời gọi hàm này — các chuỗi ký tự thông thường sẽ không nhìn thấy được đối với nó.
WordPress cung cấp một nhóm các hàm bản địa hóa, mỗi hàm cho một ngữ cảnh hơi khác nhau:
// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );
// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );
// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );
// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );
Đối số thứ hai trong mọi lời gọi — 'my-plugin' — là text domain. Nó nhóm tất cả các chuỗi của một plugin hoặc theme dưới một không gian tên để WordPress biết tệp .mo nào sẽ tải cho chúng. Mọi chuỗi có thể dịch trong dự án của bạn phải chia sẻ cùng một text domain chính xác, nếu không một số chuỗi sẽ không bao giờ được dịch.
Sử dụng _x() bất cứ khi nào một từ mơ hồ. Từ "Post" trong tiếng Anh có thể là danh từ hoặc động từ, và nhiều ngôn ngữ dịch chúng khác nhau. Các chuỗi ngữ cảnh cho phép người dịch phân biệt chúng. Và sử dụng các biến thể esc_html__() và esc_attr__() bất cứ khi nào chuỗi được dịch được in ra HTML, để bạn vừa an toàn vừa được bản địa hóa.
Có một vài thói quen giúp các chuỗi của bạn có thể trích xuất được. Luôn truyền một chuỗi ký tự đơn giản làm đối số đầu tiên — không bao giờ là một biến hoặc một phép nối chuỗi như __( 'Hello ' . $name, 'my-plugin' ), bởi vì bộ quét đọc văn bản nguồn một cách tĩnh và không thể phân giải các giá trị thời gian chạy. Đối với các câu có số, hãy sử dụng _n() để các dạng số nhiều được thu thập chính xác, và đối với các câu có giá trị động, hãy sử dụng sprintf() xung quanh một placeholder như %s thay vì nối các chuỗi lại với nhau. Tính nhất quán ở đây là điều làm cho bước tiếp theo — tạo template — tạo ra một kết quả hoàn chỉnh, có thể sử dụng được.
Bước Hai: Khai Báo Text Domain Trong Tiêu Đề Của Bạn
WordPress cần hai trường tiêu đề để biết nơi lưu trữ các bản dịch của bạn: Text Domain và Domain Path. Đặt chúng trong tệp chính của plugin hoặc tệp style.css của theme của bạn, và WordPress sẽ tự động tải tệp .mo phù hợp trong thời gian chạy.
<?php
/**
* Plugin Name: My Plugin
* Description: A perfectly localized WordPress plugin.
* Version: 1.0.0
* Requires at least: 6.4
* Text Domain: my-plugin
* Domain Path: /languages
*/
Text Domain phải khớp với chuỗi bạn đã truyền vào mọi lời gọi __() và _e() — my-plugin ở đây. Domain Path cho WordPress biết thư mục con nào chứa các tệp dịch, tương đối so với thư mục gốc của plugin hoặc theme. Quy ước là /languages, và đó chính xác là nơi tệp .pot được tạo của bạn nên được đặt.
Với các chuỗi đã được gói và tiêu đề đã khai báo, mã của bạn đã sẵn sàng để quét. Bức tranh tổng thể về việc chuẩn bị một dự án để dịch — bao gồm cả các theme không phải của bạn — được trình bày trong cách bản địa hóa bất kỳ theme WordPress nào ngay cả khi bạn không phải là nhà phát triển.
Làm Thế Nào để Tạo Tệp .pot? Ba Phương Pháp
Bạn tạo một tệp .pot bằng cách chạy một bộ quét trên mã nguồn của bạn để tìm mọi lời gọi Gettext và ghi các chuỗi vào một template. Dưới đây là ba cách đáng tin cậy để thực hiện, từ phương pháp hiện đại mặc định đến phương pháp cũ.
Phương Pháp 1: WP-CLI (Được Khuyến Nghị)
Cách chính thức, hiện đại để tạo tệp POT là sử dụng WP-CLI với lệnh i18n. Nó được phát hành như một phần của công cụ cốt lõi WordPress, hiểu các chuỗi PHP và JavaScript, và tạo ra một template tuân thủ tiêu chuẩn chỉ trong một dòng lệnh.
# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot
# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules
Đối số đầu tiên là thư mục nguồn (. cho thư mục hiện tại), và đối số thứ hai là đường dẫn đầu ra. WP-CLI duyệt qua các tệp của bạn, trích xuất mọi chuỗi được gói, ghi lại tệp nguồn và số dòng làm bình luận, và ghi tệp .pot. Nó nhanh chóng, có thể viết script, và là lựa chọn đúng đắn cho bất kỳ dự án nghiêm túc nào.
Template được tạo bao gồm các siêu dữ liệu hữu ích mà bạn có thể điều chỉnh bằng các cờ bổ sung. Truyền --headers để đặt tên dự án, phiên bản và địa chỉ liên hệ của người dịch, để khối tiêu đề .pot được điền đúng cách thay vì để trống các placeholder. WP-CLI cũng tự động trích xuất các chuỗi JavaScript từ các lời gọi wp_set_script_translations(), điều này quan trọng đối với các block theme hiện đại và plugin Gutenberg nơi một nửa văn bản hướng tới người dùng nằm trong JavaScript thay vì PHP. Một lệnh duy nhất bao gồm cả hai thế giới.
Phương Pháp 2: Poedit (Giao Diện Đồ Họa)
Nếu bạn thích một ứng dụng máy tính để bàn, Poedit có thể quét mã nguồn của bạn và tạo template thông qua giao diện của nó. Mở Poedit, chọn tạo bản dịch mới từ POT hoặc quét trực tiếp các nguồn, trỏ nó vào thư mục dự án của bạn và cấu hình các từ khóa nguồn (__, _e, _x, esc_html__) trong thuộc tính catalog.
Các tính năng quét nguồn và tạo tệp .pot của Poedit nằm trong phiên bản Pro của nó, nhưng quy trình làm việc thân thiện với các nhà phát triển thích nhấp chuột hơn là gõ lệnh. Nó cũng là một trình soạn thảo vững chắc cho giai đoạn dịch sau đó. Poedit và một số tùy chọn máy tính để bàn khác được so sánh trong top 5 công cụ miễn phí để chỉnh sửa và dịch tệp PO trên Mac và Windows.
Phương Pháp 3: makepot / grunt (Cũ)
Trước WP-CLI, công cụ tiêu chuẩn là script makepot.php từ kho lưu trữ WordPress i18n-tools, thường được tích hợp vào một tác vụ xây dựng Grunt với grunt-wp-i18n. Bạn vẫn sẽ thấy nó trong các plugin và theme cũ hơn.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Nó hoạt động, nhưng không được duy trì so với WP-CLI và chậm hơn trong việc thiết lập. Chỉ sử dụng nó khi bạn đang duy trì một dự án cũ đã phụ thuộc vào nó; đối với bất kỳ điều gì mới, hãy ưu tiên wp i18n make-pot.
Giữ Template Được Cập Nhật Khi Mã Của Bạn Thay Đổi
Một tệp .pot là một bản chụp các chuỗi của bạn tại một thời điểm nhất định. Mỗi khi bạn thêm một tính năng, thay đổi một nhãn, hoặc sửa lỗi chính tả trong một chuỗi hiển thị, template sẽ trở nên lỗi thời và người dịch sẽ bỏ lỡ cách diễn đạt mới.
Hãy biến việc tạo lại thành một phần của quy trình phát hành của bạn. Chạy lại wp i18n make-pot trước mỗi lần tăng phiên bản, sau đó hợp nhất template đã làm mới vào các bản dịch hiện có bằng wp i18n update-po hoặc msgmerge để người dịch giữ được công việc đã hoàn thành của họ và chỉ thấy những khoảng trống mới. Hãy coi tệp .pot như một tạo phẩm xây dựng mà bạn tạo lại, chứ không phải một tệp bạn chỉnh sửa thủ công.
Một template lỗi thời gây ra một lỗi tinh vi, khó chịu: các chuỗi mới xuất hiện bằng tiếng Anh ngay cả trên một trang web "đã dịch hoàn chỉnh", bởi vì chúng chưa bao giờ có trong tệp .pot mà người dịch đã làm việc. Phát hiện điều này đơn giản như việc đưa việc tạo lại vào script xây dựng của bạn, để template không bao giờ bị lạc hậu so với mã nguồn. Một số nhóm thêm kiểm tra CI khiến quá trình xây dựng thất bại nếu việc tạo lại tệp .pot tạo ra sự khác biệt, đảm bảo template đã cam kết luôn khớp với mã nguồn hiện tại.
Sau khi người dịch trả lại các tệp .po đã hoàn thành, những tệp đó vẫn cần được biên dịch thành tệp .mo nhị phân mà WordPress thực sự tải — và nếu bạn muốn bỏ qua toàn bộ vòng lặp tải xuống-dịch-biên dịch lại, một công cụ đám mây có thể xử lý nó từ đầu đến cuối. SimplePoTranslate chấp nhận tệp .pot của bạn trực tiếp, dịch nó bằng AI Nhận Biết Ngữ Cảnh hiểu ý nghĩa của từng chuỗi trong giao diện của bạn, và trả về một tệp ZIP duy nhất với .po, .mo, và nhiều hơn nữa đã được xây dựng và đặt tên. Tính năng Syntax Locking của nó giữ nguyên các placeholder như %s và %1$s để các biến của bạn không bao giờ bị hỏng trong quá trình dịch.
Tổng Kết
Để tạo một tệp POT đúng cách, trước tiên hãy làm cho mã của bạn có thể được phát hiện — gói mọi chuỗi hiển thị trong __(), _e(), _x(), hoặc một biến thể thoát, tất cả cùng chia sẻ một text domain, và khai báo domain đó cùng với Domain Path trong tiêu đề của bạn. Sau đó, tạo template bằng WP-CLI cho các dự án mới, Poedit nếu bạn thích giao diện đồ họa, hoặc makepot chỉ khi duy trì mã cũ.
Tạo sớm, tạo lại thường xuyên, và đừng bao giờ để template của bạn bị lạc hậu so với mã nguồn. Một tệp .pot hiện hành là sự khác biệt giữa một plugin thực sự sẵn sàng cho thế giới và một plugin chỉ tuyên bố là như vậy.
Sẵn sàng biến template
.potcủa bạn thành các bản dịch hoàn chỉnh mà không cần thao tác biên dịch thủ công? Dùng thử SimplePoTranslate miễn phí — không yêu cầu thẻ tín dụng. Tải template của bạn lên gói miễn phí và tải xuống các tệp dịch sẵn sàng xuất bản chỉ trong vài phút.