วิธีสร้างไฟล์ .pot สำหรับธีมหรือปลั๊กอิน

คุณเพิ่งสร้างปลั๊กอิน WordPress เสร็จสิ้นและต้องการเผยแพร่ให้คนทั่วโลกใช้งาน โค้ดทำงานได้ดี ฟีเจอร์ครบครัน แล้วมีคนจากเยอรมนีส่งอีเมลมาถามว่าจะแปลเป็นภาษาเยอรมันได้อย่างไร คุณชี้ไปที่โฟลเดอร์ languages และตระหนักว่าไม่มีอะไรอยู่ในนั้นเลย ไม่มีเทมเพลต ไม่มีสตริง ไม่มีช่องทางให้นักแปลรู้ด้วยซ้ำว่าต้องแปลอะไร ปลั๊กอินของคุณ “พร้อมสำหรับการแปล” แค่ชื่อเท่านั้นเอง

ทุกโปรเจกต์ WordPress ที่สามารถแปลได้เริ่มต้นด้วยไฟล์เดียวคือ เทมเพลต .pot ก่อนที่ใครจะสร้างเวอร์ชันภาษาเยอรมัน ฝรั่งเศส หรือญี่ปุ่นได้ คุณต้อง สร้างไฟล์ POT ที่แสดงรายการสตริงทั้งหมดที่ผู้ใช้เห็นในโค้ดของคุณ หากข้ามขั้นตอนนี้ นักแปลจะต้องอ่านซอร์สโค้ดทีละบรรทัด และเดาว่าสตริงใดบ้างที่ควรปรากฏให้เห็น

คู่มือนี้จะอธิบายขั้นตอนสองส่วนของงาน: การเตรียมซอร์สโค้ดของคุณเพื่อให้สามารถค้นหาสตริงได้ และการสร้างไฟล์ .pot ด้วยเครื่องมือสามอย่าง เราจะใช้ WP-CLI, Poedit และแนวทางแบบดั้งเดิม makepot/grunt พร้อมคำสั่งจริงที่คุณสามารถคัดลอกไปใช้ได้ เมื่ออ่านจบคคุณจะได้เทมเพลตที่สะอาดพร้อมส่งให้นักแปล

ขั้นตอนที่หนึ่ง: ทำเครื่องหมายสตริงของคุณว่าสามารถแปลได้

ก่อนที่คุณจะสร้างไฟล์ POT ได้ สตริงทุกคำที่ผู้ใช้อาจเห็นจำเป็นต้องถูกห่อหุ้มด้วยฟังก์ชัน Gettext ตัวสแกนจะสามารถดึงสตริงที่มันรู้จักได้เท่านั้น และมันจะรู้จักสตริงเหล่านั้นผ่านการเรียกฟังก์ชันเหล่านี้ — สตริงที่เป็นตัวอักษรธรรมดาจะไม่ปรากฏแก่ตัวสแกน

WordPress มีตระกูลฟังก์ชันสำหรับการแปลภาษา (localization) แต่ละฟังก์ชันสำหรับบริบทที่แตกต่างกันเล็กน้อย:

// 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' );

อาร์กิวเมนต์ที่สองในการเรียกใช้แต่ละครั้ง — 'my-plugin' — คือ text domain มันจัดกลุ่มสตริงทั้งหมดของปลั๊กอินหรือธีมไว้ภายใต้เนมสเปซเดียวกัน เพื่อให้ WordPress รู้ว่าต้องโหลดไฟล์ .mo ใดสำหรับสตริงเหล่านั้น สตริงที่แปลได้ทุกรายการในโปรเจกต์ของคุณต้องมี text domain ที่เหมือนกัน มิฉะนั้นบางสตริงจะไม่มีทางถูกแปลเลย

ใช้ _x() เมื่อคำนั้นมีความกำกวม คำว่า “Post” ในภาษาอังกฤษสามารถเป็นคำนามหรือคำกริยาก็ได้ และหลายภาษาจะแปลแตกต่างกัน สตริงบริบทช่วยให้นักแปลแยกแยะความแตกต่างได้ และใช้ตัวแปร esc_html__() และ esc_attr__() เมื่อใดก็ตามที่สตริงที่แปลแล้วถูกพิมพ์ลงใน HTML เพื่อให้คุณปลอดภัยและแปลเป็นภาษาท้องถิ่นได้ในเวลาเดียวกัน

มีนิสัยบางอย่างที่ช่วยให้สตริงของคุณสามารถดึงออกมาได้ ควรส่งสตริงที่เป็นตัวอักษรธรรมดาเป็นอาร์กิวเมนต์แรกเสมอ — ห้ามใช้ตัวแปรหรือการเชื่อมสตริง เช่น __( 'Hello ' . $name, 'my-plugin' ) เนื่องจากตัวสแกนจะอ่านข้อความต้นฉบับแบบคงที่และไม่สามารถแก้ไขค่า ณ รันไทม์ได้ สำหรับประโยคที่มีตัวเลข ให้ใช้ _n() เพื่อให้รูปแบบพหูพจน์ถูกจับภาพได้อย่างถูกต้อง และสำหรับประโยคที่มีค่าไดนามิก ให้ใช้ sprintf() รอบๆ ตัวยึดตำแหน่ง เช่น %s แทนการเชื่อมสตริงเข้าด้วยกัน ความสอดคล้องตรงนี้คือสิ่งที่ทำให้ขั้นตอนต่อไป — การสร้างเทมเพลต — ให้ผลลัพธ์ที่สมบูรณ์และใช้งานได้

ขั้นตอนที่สอง: ประกาศ Text Domain ในส่วน Header ของคุณ

WordPress ต้องการฟิลด์ header สองฟิลด์เพื่อทราบว่าไฟล์แปลภาษาของคุณอยู่ที่ไหน: Text Domain และ Domain Path ตั้งค่าฟิลด์เหล่านี้ในไฟล์หลักของปลั๊กอินหรือไฟล์ style.css ของธีมของคุณ แล้ว WordPress จะโหลดไฟล์ .mo ที่ถูกต้องโดยอัตโนมัติเมื่อรันไทม์

<?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 ต้องตรงกับสตริงที่คุณส่งไปยังการเรียก __() และ _e() ทุกครั้ง — ในที่นี้คือ my-plugin ส่วน Domain Path จะบอก WordPress ว่าโฟลเดอร์ย่อยใดที่เก็บไฟล์แปลภาษา โดยสัมพันธ์กับรากของปลั๊กอินหรือธีม หลักปฏิบัติคือ /languages และนั่นคือที่ที่ไฟล์ .pot ที่สร้างขึ้นของคุณควรอยู่พอดี

เมื่อสตริงถูกห่อหุ้มและ header ถูกประกาศ โค้ดของคุณก็พร้อมที่จะสแกน ภาพรวมที่กว้างขึ้นของการเตรียมโปรเจกต์สำหรับการแปล — รวมถึงธีมที่ไม่ใช่ของคุณเอง — มีอยู่ใน วิธีแปลภาษาธีม WordPress ใดๆ แม้ว่าคุณจะไม่ใช่นักพัฒนา

คุณจะสร้างไฟล์ .pot ได้อย่างไร? สามวิธี

คุณสามารถสร้างไฟล์ .pot ได้โดยการรันตัวสแกนบนซอร์สโค้ดของคุณ ซึ่งจะค้นหาการเรียก Gettext ทุกรายการและเขียนสตริงลงในเทมเพลต นี่คือสามวิธีที่เชื่อถือได้ในการทำเช่นนั้น ตั้งแต่วิธีมาตรฐานสมัยใหม่ไปจนถึงแนวทางแบบดั้งเดิม

วิธีที่ 1: WP-CLI (แนะนำ)

วิธีที่เป็นทางการและทันสมัยในการสร้างไฟล์ POT คือ WP-CLI ด้วยคำสั่ง i18n มันมาพร้อมกับเครื่องมือหลักของ WordPress เข้าใจสตริง PHP และ JavaScript และสร้างเทมเพลตที่ได้มาตรฐานในบรรทัดเดียว

# 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

อาร์กิวเมนต์แรกคือไดเรกทอรีต้นฉบับ (. สำหรับโฟลเดอร์ปัจจุบัน) และอาร์กิวเมนต์ที่สองคือพาธเอาต์พุต WP-CLI จะไล่ดูไฟล์ของคุณ ดึงสตริงที่ถูกห่อหุ้มทุกรายการ บันทึกไฟล์ต้นฉบับและหมายเลขบรรทัดเป็นคอมเมนต์ และเขียนไฟล์ .pot มันรวดเร็ว สามารถเขียนสคริปต์ได้ และเป็นตัวเลือกที่เหมาะสมสำหรับทุกโปรเจกต์ที่จริงจัง

เทมเพลตที่สร้างขึ้นจะรวมข้อมูลเมตาที่เป็นประโยชน์ที่คุณสามารถปรับแต่งได้ด้วยแฟล็กเพิ่มเติม ส่ง --headers เพื่อตั้งชื่อโปรเจกต์ เวอร์ชัน และที่อยู่ติดต่อของนักแปล เพื่อให้บล็อก header ของ .pot ถูกเติมข้อมูลอย่างถูกต้อง แทนที่จะปล่อยเป็นตัวยึดตำแหน่ง WP-CLI ยังดึงสตริง JavaScript จากการเรียกใช้ wp_set_script_translations() โดยอัตโนมัติ ซึ่งสำคัญสำหรับธีมบล็อกสมัยใหม่และปลั๊กอิน Gutenberg ที่ครึ่งหนึ่งของข้อความที่ผู้ใช้เห็นอยู่ใน JavaScript แทนที่จะเป็น PHP คำสั่งเดียวครอบคลุมทั้งสองโลก

วิธีที่ 2: Poedit (แบบกราฟิก)

หากคุณชอบแอปพลิเคชันบนเดสก์ท็อป Poedit สามารถสแกนซอร์สโค้ดของคุณและสร้างเทมเพลตผ่านอินเทอร์เฟซของมันได้ เปิด Poedit เลือกที่จะสร้างการแปลใหม่จาก POT หรือสแกนแหล่งที่มาโดยตรง ชี้ไปที่โฟลเดอร์โปรเจกต์ของคุณ และกำหนดค่าคีย์เวิร์ดแหล่งที่มา (__, _e, _x, esc_html__) ภายใต้คุณสมบัติของแคตตาล็อก

คุณสมบัติการสแกนแหล่งที่มาและการสร้าง .pot ของ Poedit มีอยู่ในเวอร์ชัน Pro แต่วิธีการทำงานเป็นมิตรสำหรับนักพัฒนาที่ต้องการคลิกมากกว่าพิมพ์คำสั่ง นอกจากนี้ยังเป็นโปรแกรมแก้ไขที่แข็งแกร่งสำหรับขั้นตอนการแปลที่จะตามมา Poedit และตัวเลือกเดสก์ท็อปอื่นๆ อีกหลายรายการถูกเปรียบเทียบใน 5 เครื่องมือฟรีที่ดีที่สุดในการแก้ไขและแปลไฟล์ PO บน Mac และ Windows

วิธีที่ 3: makepot / grunt (แบบดั้งเดิม)

ก่อน WP-CLI เครื่องมือมาตรฐานคือสคริปต์ makepot.php จาก WordPress i18n-tools repository ซึ่งมักจะเชื่อมโยงเข้ากับงาน Grunt build ด้วย grunt-wp-i18n คุณจะยังคงพบเห็นได้ในปลั๊กอินและธีมรุ่นเก่า

# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot

มันทำงานได้ แต่ไม่มีการบำรุงรักษาเมื่อเทียบกับ WP-CLI และใช้เวลาในการตั้งค่าช้ากว่า ใช้งานเฉพาะเมื่อคุณกำลังดูแลโปรเจกต์รุ่นเก่าที่พึ่งพามันอยู่แล้วเท่านั้น สำหรับโปรเจกต์ใหม่ใดๆ ให้เลือกใช้ wp i18n make-pot ดีกว่า

ทำให้เทมเพลตอัปเดตอยู่เสมอเมื่อโค้ดของคุณเปลี่ยนแปลง

ไฟล์ .pot คือสแนปช็อตของสตริงของคุณ ณ ช่วงเวลาหนึ่ง ทุกครั้งที่คุณเพิ่มฟีเจอร์ เปลี่ยนข้อความ หรือแก้ไขข้อผิดพลาดในการพิมพ์ในสตริงที่มองเห็นได้ เทมเพลตจะล้าสมัย และนักแปลจะพลาดถ้อยคำใหม่ๆ

กำหนดให้การสร้างใหม่เป็นส่วนหนึ่งของขั้นตอนการเผยแพร่ของคุณ รัน wp i18n make-pot ซ้ำก่อนการอัปเดตเวอร์ชันทุกครั้ง จากนั้นรวมเทมเพลตที่อัปเดตเข้ากับการแปลที่มีอยู่ด้วย wp i18n update-po หรือ msgmerge เพื่อให้นักแปลยังคงรักษาผลงานที่เสร็จสิ้นไว้ได้และเห็นเฉพาะส่วนที่ขาดหายไปใหม่ๆ ปฏิบัติต่อไฟล์ .pot เหมือนเป็นผลลัพธ์จากการบิลด์ที่คุณสร้างขึ้นใหม่ ไม่ใช่ไฟล์ที่คุณแก้ไขด้วยมือ

เทมเพลตที่ล้าสมัยทำให้เกิดข้อผิดพลาดที่ละเอียดอ่อนและน่าหงุดหงิด: สตริงใหม่ปรากฏเป็นภาษาอังกฤษแม้ในเว็บไซต์ที่ “แปลครบถ้วนแล้ว” เพราะไม่เคยมีอยู่ในไฟล์ .pot ที่นักแปลใช้ทำงาน การแก้ปัญหานี้ทำได้ง่ายๆ โดยการเขียนสคริปต์การสร้างใหม่เข้าไปในขั้นตอนการบิลด์ของคุณ เพื่อให้เทมเพลตไม่มีวันล้าหลังโค้ด ทีมงานบางทีมเพิ่มการตรวจสอบ CI ที่จะทำให้การบิลด์ล้มเหลวหากการสร้างไฟล์ .pot ใหม่ทำให้เกิดความแตกต่าง เพื่อรับประกันว่าเทมเพลตที่คอมมิตจะตรงกับแหล่งที่มาปัจจุบันเสมอ

เมื่อนักแปลส่งไฟล์ .po ที่แปลเสร็จแล้ว กลับคืนมา ไฟล์เหล่านั้นยังคงต้องถูกคอมไพล์เป็นไฟล์ไบนารี .mo ที่ WordPress ใช้โหลดจริง — และหากคุณต้องการข้ามขั้นตอนการดาวน์โหลด-แปล-คอมไพล์ทั้งหมด เครื่องมือคลาวด์สามารถจัดการให้เสร็จสิ้นได้ตั้งแต่ต้นจนจบ SimplePoTranslate รับไฟล์ .pot ของคุณโดยตรง แปลด้วย Context-Aware AI ที่เข้าใจความหมายของแต่ละสตริงในอินเทอร์เฟซของคุณ และส่งคืนไฟล์ ZIP เดียวที่มี .po, .mo และอื่นๆ ที่สร้างและตั้งชื่อไว้เรียบร้อยแล้ว Syntax Locking ของมันจะล็อคตัวยึดตำแหน่ง เช่น %s และ %1$s เพื่อให้ตัวแปรของคุณไม่เสียหายในการแปล

สรุป

หากต้องการ สร้างไฟล์ POT อย่างถูกวิธี ขั้นแรกให้โค้ดของคุณสามารถค้นหาได้ — ห่อหุ้มสตริงที่มองเห็นได้ทุกรายการด้วย __(), _e(), _x() หรือรูปแบบการหลีกเลี่ยง (escaping variant) โดยทั้งหมดใช้ text domain เดียวกัน และประกาศ domain นั้นรวมถึง Domain Path ใน header ของคุณ จากนั้นสร้างเทมเพลตด้วย WP-CLI สำหรับโปรเจกต์ใหม่ Poedit หากคุณชอบ GUI หรือ makepot เฉพาะเมื่อดูแลโค้ดรุ่นเก่าเท่านั้น

สร้างแต่เนิ่นๆ สร้างใหม่บ่อยๆ และอย่าปล่อยให้เทมเพลตของคุณล้าหลังโค้ดของคุณ ไฟล์ .pot ที่เป็นปัจจุบันคือความแตกต่างระหว่างปลั๊กอินที่พร้อมสำหรับคนทั่วโลกอย่างแท้จริงกับปลั๊กอินที่แค่แอบอ้างเท่านั้น

พร้อมที่จะเปลี่ยนเทมเพลต .pot ของคุณให้เป็นการแปลที่เสร็จสมบูรณ์โดยไม่ต้องผ่านขั้นตอนการคอมไพล์ด้วยมือแล้วหรือยัง? ลองใช้ SimplePoTranslate ฟรี — ไม่ต้องใช้บัตรเครดิต อัปโหลดเทมเพลตของคุณบนแพ็กเกจฟรีและดาวน์โหลดไฟล์แปลภาษาพร้อมใช้งานได้ภายในไม่กี่นาที