Cách dịch một plugin WordPress (Từng bước một)

Bạn đã tìm thấy plugin WordPress hoàn hảo cho dự án của mình. Nó hoạt động chính xác như bạn cần, các đánh giá đều rất tốt, và sau đó bạn kích hoạt nó và nhận ra mọi nút, nhãn và thông báo lỗi đều bằng tiếng Anh. Khách truy cập người Đức, Pháp hoặc Nhật của bạn sắp phải đối mặt với một bức tường văn bản mà họ không thể đọc được.

Tin tốt là hầu hết các plugin được xây dựng tốt đều sẵn sàng để dịch, nghĩa là nhà phát triển đã gói các chuỗi của họ trong các hàm Gettext đặc biệt để những người như bạn có thể dịch chúng. Thử thách là biết các tệp nằm ở đâu, đặt tên bản dịch của bạn là gì và đặt nó ở đâu để bản cập nhật plugin tiếp theo không xóa mất công việc của bạn.

Hướng dẫn này sẽ chỉ cho bạn cách dịch một plugin WordPress từ đầu đến cuối: tìm text domain và thư mục ngôn ngữ, lấy hoặc tạo mẫu .pot, xây dựng các tệp .po và .mo được đặt tên đúng cách và đặt chúng ở nơi WordPress sẽ tải chúng một cách đáng tin cậy. Chúng tôi cũng sẽ đề cập đến một loại plugin mà phương pháp này không thể dịch hoàn toàn, để bạn không lãng phí hàng giờ để chiến đấu với một trường hợp bất khả thi.

Làm thế nào để bạn tìm các tệp dịch của một Plugin?

Trước khi dịch bất cứ thứ gì, bạn cần hai thông tin từ plugin: text domain và thư mục ngôn ngữ của nó. Text domain là chuỗi duy nhất mà plugin sử dụng để xác định các bản dịch của riêng nó, và thư mục ngôn ngữ là nơi chứa mẫu nguồn.

Xác định vị trí thư mục ngôn ngữ và Text Domain

Mở thư mục plugin tại wp-content/plugins/your-plugin/ và tìm thư mục con /languages. Bên trong, bạn thường sẽ tìm thấy một tệp .pot, là mẫu trống chứa mọi chuỗi có thể dịch.

Để xác nhận text domain, mở tệp PHP chính của plugin và xem khối tiêu đề của nó:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Ở đây text domain là awesome-plugin. Giá trị này rất quan trọng, vì các tệp dịch của bạn phải bao gồm nó trong tên của chúng nếu không WordPress sẽ không bao giờ khớp chúng với plugin. Bạn cũng sẽ thấy nó trong mọi lời gọi chuỗi trong suốt mã:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Đối số thứ hai, awesome-plugin, lại là text domain. Mọi chuỗi sử dụng nó đều có thể được dịch bởi danh mục của bạn. Nếu một chuỗi trong giao diện của plugin thiếu trình bao bọc này, ví dụ một nhà phát triển đã mã hóa cứng echo 'Save' mà không có __(), thì chuỗi đó hoàn toàn không thể dịch được, và không có tệp .po nào có thể truy cập nó. Hầu hết các plugin uy tín đều bao bọc mọi thứ một cách chính xác, nhưng nếu bạn nhận thấy một hoặc hai chuỗi cứng đầu từ chối dịch, thì việc thiếu trình bao bọc Gettext trong nguồn là một nguyên nhân có khả năng xảy ra.

Một cách nhanh chóng để đánh giá xem một plugin có thực sự sẵn sàng để dịch hay không là kiểm tra danh sách của nó trên thư mục WordPress.org, nơi hiển thị tỷ lệ dịch và liên kết đến một mẫu /languages. Một plugin có dự án dịch hoạt động có nhiều khả năng có các chuỗi sạch, được bao bọc hoàn chỉnh hơn một plugin bị bỏ rơi.

Điều gì sẽ xảy ra nếu Plugin không có tệp POT?

Một số plugin được phân phối mà không có mẫu .pot. Nếu thư mục /languages trống hoặc bị thiếu, bạn cần tự tạo mẫu bằng cách quét mã nguồn để tìm các chuỗi có thể dịch.

Công cụ tiêu chuẩn cho việc này là WP-CLI, nó trích xuất mọi lời gọi Gettext vào một tệp .pot mới.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Lệnh này duyệt qua các tệp PHP và JavaScript của plugin, tìm mọi lời gọi __(), _e(), _n() và các lời gọi liên quan, sau đó viết một mẫu hoàn chỉnh. Nếu bạn thích một lộ trình đồ họa hơn, Poedit Pro có thể quét mã nguồn theo cách tương tự. Dù bằng cách nào, kết quả là một tệp .pot chứa tất cả các chuỗi nguồn với các bản dịch trống, sẵn sàng được biến thành một tệp ngôn ngữ thực sự.

Việc tự tạo mẫu của riêng bạn có một lợi ích tiềm ẩn: nó ghi lại các chuỗi mà nhà phát triển ban đầu có thể đã quên không bao gồm trong tệp .pot đã được phát hành. Các plugin phát triển nhanh chóng, và một mẫu đi kèm với phiên bản 2.1 có thể thiếu các chuỗi được thêm vào trong 2.4. Việc tạo lại từ nguồn hiện tại đảm bảo rằng danh mục của bạn phản ánh những gì plugin thực sự hiển thị hôm nay, chứ không phải những gì nó đã hiển thị hai bản phát hành trước. Nếu bạn duy trì các bản dịch cho một plugin theo thời gian, việc chạy lại make-pot sau mỗi bản cập nhật lớn là một thói quen đáng tin cậy.

Tạo các tệp PO và MO với tên chính xác

Lỗi phổ biến nhất khi dịch một plugin là tên tệp. WordPress tìm các bản dịch plugin bằng cách khớp một mẫu rất cụ thể, và một ký tự sai có nghĩa là bản dịch của bạn sẽ bị bỏ qua hoàn toàn.

Công thức đặt tên tệp

Đối với các bản dịch plugin, mẫu là text-domain-locale. Vì vậy, đối với text domain awesome-plugin được dịch sang tiếng Đức, các tệp phải được đặt tên:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

Mã ngôn ngữ (locale code) là mã ngôn ngữ của trang WordPress: de_DE cho tiếng Đức, fr_FR cho tiếng Pháp, es_ES cho tiếng Tây Ban Nha, pt_BR cho tiếng Bồ Đào Nha Brazil. Nếu mã ngôn ngữ không đúng, WordPress sẽ bỏ qua tệp của bạn một cách im lặng. Bạn tạo các tệp này từ mẫu .pot trong một trình chỉnh sửa như Poedit, chương trình sẽ tự động biên dịch tệp .mo nhị phân khi bạn lưu. Nếu bạn mới sử dụng trình chỉnh sửa đó, hướng dẫn Poedit đầy đủ sẽ hướng dẫn bạn tạo bản dịch từ một mẫu từng bước một.

Nơi đặt các tệp để các bản cập nhật không xóa chúng

Có hai vị trí có thể, và việc chọn đúng vị trí là rất quan trọng.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Luôn sử dụng wp-content/languages/plugins/. WordPress kiểm tra thư mục ghi đè này trước, và vì nó nằm ngoài thư mục plugin, việc cập nhật plugin không bao giờ chạm vào các bản dịch của bạn. Các tệp được đặt bên trong thư mục riêng của plugin sẽ bị ghi đè ngay khi một phiên bản mới được cài đặt.

Hành vi ghi đè này là một trong những tính năng hữu ích nhất và ít được biết đến nhất của quá trình bản địa hóa WordPress. Điều đó có nghĩa là bạn có thể cung cấp các bản dịch tùy chỉnh hoặc đã sửa cho bất kỳ plugin của bên thứ ba nào mà không cần phân nhánh nó, và các thay đổi của bạn hoàn toàn an toàn khi cập nhật. Nếu bạn quản lý một số trang web của khách hàng đang chạy cùng một plugin, bạn thậm chí có thể giữ một bộ tệp .mo ghi đè duy nhất và triển khai chúng trên tất cả các trang web đó, biết rằng mỗi trang web sẽ tự động nhận chúng miễn là mã ngôn ngữ khớp.

Cách WordPress tải bản dịch của bạn

Một plugin sẵn sàng dịch sẽ yêu cầu WordPress tải danh mục của nó bằng cách gọi load_plugin_textdomain() trong quá trình khởi tạo:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Đối với hầu hết các plugin hiện đại trên WordPress 4.6 trở lên, bạn không cần chạm vào điều này. WordPress tự động tải các bản dịch từ wp-content/languages/plugins/ miễn là tên tệp và ngôn ngữ trang web của bạn khớp. Nếu bản dịch hoàn chỉnh của bạn vẫn không xuất hiện, nguyên nhân hầu như luôn là do tên tệp không khớp, tệp .mo cũ hoặc ngôn ngữ trang web được đặt thành mã ngôn ngữ sai. Hướng dẫn khắc phục sự cố bản dịch không hiển thị của chúng tôi sẽ hướng dẫn bạn qua từng điểm lỗi này.

Các Plugin lưu trữ chuỗi trong cơ sở dữ liệu

Đây là hạn chế quan trọng. Phương pháp Gettext chỉ dịch các chuỗi nằm trong mã của plugin. Một số plugin, đặc biệt là các trình tạo biểu mẫu, trình tạo trang và tiện ích mở rộng thương mại điện tử, cho phép bạn tạo nội dung (nhãn biểu mẫu, thuộc tính sản phẩm, tin nhắn tùy chỉnh) được lưu trong cơ sở dữ liệu WordPress. Những chuỗi đó là dữ liệu do người dùng tạo, không phải là một phần của tệp .pot, vì vậy tệp .po không thể tiếp cận chúng. Đối với nội dung cơ sở dữ liệu, bạn cần một plugin đa ngôn ngữ như WPML hoặc Polylang, hoặc tính năng dịch chuỗi riêng của plugin. Luôn kiểm tra xem một chuỗi nhất định nằm trong mã hay trong cơ sở dữ liệu trước khi giả định rằng tệp .po có thể sửa nó.

Một thử nghiệm đơn giản cho bạn biết bạn đang xử lý loại chuỗi nào. Nếu văn bản là thứ bạn đã nhập vào trường cài đặt, nhãn biểu mẫu bạn đã tạo, tin nhắn cảm ơn tùy chỉnh, tên sản phẩm, đó là nội dung cơ sở dữ liệu và tệp .po không thể chạm vào nó. Nếu văn bản là một phần của giao diện tích hợp sẵn của plugin, nhãn nút, lỗi xác thực, thông báo quản trị đi kèm với chính plugin, nó nằm trong mã và tệp .po chính xác là công cụ phù hợp. Việc xác định ranh giới này sớm giúp tiết kiệm hàng giờ thất vọng, bởi vì không có chỉnh sửa .po hoàn hảo nào có thể dịch được một chuỗi mà plugin kéo từ cơ sở dữ liệu trong thời gian chạy.

Dịch ở quy mô lớn mà không cần làm thủ công

Dịch một plugin sang một ngôn ngữ bằng tay là có thể quản lý được. Dịch nó sang mười ngôn ngữ, hoặc dịch toàn bộ một chồng plugin cho một trang web khách hàng, biến thành nhiều ngày làm việc lặp đi lặp lại, và mọi chỉnh sửa thủ công đều có nguy cơ làm hỏng một placeholder như %s hoặc %1$s và làm hỏng đầu ra.

Đây là lúc quy trình làm việc trên nền tảng đám mây thay đổi mọi thứ. Tải tệp .po hoặc .pot của plugin lên SimplePoTranslate, chọn ngôn ngữ mục tiêu của bạn, và AI nhận biết ngữ cảnh sẽ dịch toàn bộ danh mục trong khi Khóa cú pháp (Syntax Locking) đóng băng mọi placeholder, thẻ HTML và mã thông báo để không có gì có thể bị hỏng. Gộp thông minh (Smart Batching) xử lý các danh mục lớn trong một lần duy nhất, và bạn tải xuống một tệp ZIP chứa .po, .mo, .json, .php và .xliff cùng nhau, được định dạng chính xác và sẵn sàng để thả vào wp-content/languages/plugins/. Nó chạy hoàn toàn trên nền tảng đám mây, vì vậy không cần cài đặt trên máy tính để bàn và không gây nặng nề cho trang web của bạn.

Lưu ý rằng việc dịch một plugin khác với việc dịch một theme, vốn sử dụng một quy ước thư mục và hàm tải hơi khác. Nếu theme là mục tiêu của bạn, hãy làm theo hướng dẫn chuyên biệt của chúng tôi về 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 thay vào đó.

Sử dụng phương pháp thủ công khi bạn có một plugin và một ngôn ngữ. Sử dụng đám mây khi bạn cần nhiều ngôn ngữ, nhanh chóng, mà không phải đánh đổi sự an toàn của các placeholder.

Sẵn sàng dịch plugin WordPress của bạn sang mọi ngôn ngữ mà khán giả của bạn nói mà không làm hỏng bất kỳ biến nào? Thử SimplePoTranslate miễn phí — không yêu cầu thẻ tín dụng. Gói miễn phí cho phép bạn dịch tệp .po plugin đầu tiên của mình trong vài phút, với Khóa cú pháp trên mọi chuỗi.