在管理 WordPress 自訂文章類型（Custom Post Type）時，常會遇到需要批次替換文章內容或摘要中的特定字串的需求。手動逐篇修改不僅耗時，也容易出錯。這段程式碼示範如何在 WordPress 後台為名為 solution 的自訂文章類型新增一個子選單，提供一個簡單介面讓管理員輸入舊字串與新字串，並自動搜尋所有 solution 文章的內容與摘要進行批次替換。

這篇文章適合有基本 WordPress 開發經驗，想要了解如何擴充後台功能並操作自訂文章內容的工程師與自學者。

新增後台子選單

使用 add_action('admin_menu', ...) 來掛載函式，先判斷 solution 文章類型是否存在，避免錯誤。接著用 add_submenu_page 在 solution 文章列表下新增「內容關鍵字取代」的子選單，權限設定為可編輯文章的用戶。

add_action('admin_menu', function () {
    if (!post_type_exists('solution')) {
        return;
    }

    add_submenu_page(
        'edit.php?post_type=solution',
        '內容關鍵字取代',
        '內容關鍵字取代',
        'edit_posts',
        'solution-content-replace',
        'solution_content_replace_page'
    );
});

這段程式碼確保只有在 solution 文章類型存在時才新增選單，避免後台出現無效連結。

後台頁面與表單設計

solution_content_replace_page 函式負責渲染後台頁面。首先檢查使用者權限，防止未授權存取。頁面包含一個表單，讓使用者輸入「舊字串」與「新字串」，並使用 WordPress 的 nonce 機制防止 CSRF 攻擊。

if (!current_user_can('edit_posts')) {
    wp_die('沒有權限。');
}

// 表單中使用 wp_nonce_field 產生安全碼

表單送出後會執行字串替換邏輯。

批次搜尋與替換邏輯說明

當表單送出且 nonce 驗證通過後，程式會取得輸入的舊字串與新字串，並用 WP_Query 撈出所有 solution 文章的 ID。

$query = new WP_Query([
    'post_type'      => 'solution',
    'post_status'    => 'any',
    'posts_per_page' => -1,
    'fields'         => 'ids',
]);

接著逐篇文章讀取內容（post_content）與摘要（post_excerpt），利用 mb_strpos（若可用）或 strpos 檢查舊字串是否存在。若存在，則用 str_replace 替換。

if ($content_pos !== false) {
    $updated_content = str_replace($old, $new, $content);
    if ($updated_content !== $content) {
        $update_args['post_content'] = $updated_content;
        $status_parts[] = '內容';
    }
}

替換完成後，只有在內容或摘要確實有變動時才呼叫 wp_update_post 進行更新，避免不必要的資料庫寫入。

結果呈現與使用者體驗

執行完替換後，頁面會顯示替換結果列表，包括文章 ID、標題、替換狀態（內容、摘要或兩者）以及快速編輯連結，方便管理者後續檢查與微調。

若未輸入舊字串，會顯示警告；若找不到符合條件的文章，則提示資訊，提升使用者體驗。

實務應用與優化建議

此工具適合用於需要大量文字修正的場景，例如品牌名稱變更、產品名稱更新或錯字修正。未來可擴充功能，如：

• 支援正規表達式替換
• 限制替換範圍（例如只替換內容或摘要）
• 增加替換前預覽功能
• 加入替換記錄與回滾機制

此外，批次更新大量文章時，建議搭配分批處理避免伺服器超時。

常見問題與注意事項

• 請確認使用者權限設定正確，避免無權限使用此工具。
• 替換字串為空白時，會將舊字串刪除，請謹慎操作。
• 使用 mb_strpos 可避免多字節字串判斷錯誤，若環境不支援會退回 strpos。

完整程式碼

<?php
// 在 solution post type 底下新增子選單：內容關鍵字取代
add_action('admin_menu', function () {
    if (!post_type_exists('solution')) {
        return;
    }

    add_submenu_page(
        'edit.php?post_type=solution',
        '內容關鍵字取代',
        '內容關鍵字取代',
        'edit_posts',
        'solution-content-replace',
        'solution_content_replace_page'
    );
});

// 後台頁面
function solution_content_replace_page() {
    if (!current_user_can('edit_posts')) {
        wp_die('沒有權限。');
    }

    $old = '';
    $new = '';
    $results = [];
    $executed = false;

    if (isset($_POST['solution_replace_submit'])) {
        check_admin_referer('solution_replace_action', 'solution_replace_nonce');

        $old = isset($_POST['old_keyword']) ? sanitize_text_field($_POST['old_keyword']) : '';
        $new = isset($_POST['new_keyword']) ? sanitize_text_field($_POST['new_keyword']) : '';

        $executed = true;

        if ($old !== '') {
            $query = new WP_Query([
                'post_type'      => 'solution',
                'post_status'    => 'any',
                'posts_per_page' => -1,
                'fields'         => 'ids',
            ]);

            foreach ($query->posts as $post_id) {
                $post = get_post($post_id);
                if (!$post) {
                    continue;
                }

                $content = $post->post_content;
                $excerpt = $post->post_excerpt;

                // 檢查舊字串是否存在（內容＋摘要）
                if (function_exists('mb_strpos')) {
                    $content_pos = ($content !== '') ? mb_strpos($content, $old) : false;
                    $excerpt_pos = ($excerpt !== '') ? mb_strpos($excerpt, $old) : false;
                } else {
                    $content_pos = ($content !== '') ? strpos($content, $old) : false;
                    $excerpt_pos = ($excerpt !== '') ? strpos($excerpt, $old) : false;
                }

                if ($content_pos !== false || $excerpt_pos !== false) {
                    $update_args = [
                        'ID' => $post_id,
                    ];
                    $status_parts = [];

                    // 內容替換
                    if ($content_pos !== false) {
                        $updated_content = str_replace($old, $new, $content);
                        if ($updated_content !== $content) {
                            $update_args['post_content'] = $updated_content;
                            $status_parts[] = '內容';
                        }
                    }

                    // 摘要替換
                    if ($excerpt_pos !== false) {
                        $updated_excerpt = str_replace($old, $new, $excerpt);
                        if ($updated_excerpt !== $excerpt) {
                            $update_args['post_excerpt'] = $updated_excerpt;
                            $status_parts[] = '摘要';
                        }
                    }

                    // 真的有需要更新才存
                    if (!empty($status_parts)) {
                        wp_update_post($update_args);

                        $results[] = [
                            'id'     => $post_id,
                            'title'  => $post->post_title,
                            'status' => '已替換：' . implode('、', $status_parts),
                        ];
                    }
                }
            }
            wp_reset_postdata();
        }
    }
    ?>

<h1>Solution – 內容關鍵字取代</h1>

<p>此工具會掃描所有 <code>solution 文章的內容與摘要，將符合的字串批次替換。


        
            

            




要搜尋的字（舊字串）


                        <input type="text" id="old_keyword" name="old_keyword" class="regular-text"
                               value=""
                               placeholder="例如：舊字串">
                    
                



替換成（新字串）


                        <input type="text" id="new_keyword" name="new_keyword" class="regular-text"
                               value=""
                               placeholder="例如：新字串（可空白）">
                    
                
            

            
        

        

取代結果

            
                
請輸入要搜尋的舊字串。

            
                
沒有任何文章的內容或摘要包含「」。

            
                






ID

標題

狀態

編輯連結
                    
                    


                    









<a href="" class="button button-small">編輯
                        
                    
                    
                
            

        

    <?php
}

在 WordPress 後台管理自訂文章類型（此處為 solution）時，若想快速搜尋文章內容中是否包含特定關鍵字，系統預設的搜尋功能可能無法精準或方便達成此需求。這段程式碼示範如何為 solution 文章類型新增一個後台子選單，提供內容關鍵字搜尋功能，適合需要管理大量文章並快速定位內容的開發者與網站管理員。

新增後台子選單

使用 admin_menu action，先檢查 solution 文章類型是否存在，避免錯誤。接著透過 add_submenu_page 在 solution 列表底下新增「內容關鍵字搜尋」子選單，設定權限為 edit_posts，確保只有具備編輯權限的使用者能操作。

add_action( 'admin_menu', function () {
    if ( ! post_type_exists( 'solution' ) ) {
        return;
    }

    add_submenu_page(
        'edit.php?post_type=solution',
        '內容關鍵字搜尋',
        '內容關鍵字搜尋',
        'edit_posts',
        'solution-content-search',
        'solution_content_search_page_render'
    );
} );

搜尋頁面渲染與表單處理

solution_content_search_page_render 函式負責渲染搜尋表單與結果頁面。首先檢查使用者權限，避免未授權存取。接著判斷是否有表單送出，並使用 WordPress 的 nonce 機制驗證安全性。

關鍵字透過 sanitize_text_field 與 wp_unslash 清理，避免 XSS 與注入風險。

if ( isset( $_POST['solution_content_search_submit'] ) ) {
    check_admin_referer( 'solution_content_search_action', 'solution_content_search_nonce' );

    $keyword  = isset( $_POST['solution_keyword'] ) ? sanitize_text_field( wp_unslash( $_POST['solution_keyword'] ) ) : '';
    $searched = true;

    if ( $keyword !== '' ) {
        // ...
    }
}

透過 WP_Query 及字串比對精確搜尋

WordPress 內建搜尋（s 參數）會搜尋標題、內容等欄位，但可能不夠精準。此處先用 WP_Query 以關鍵字搜尋取得可能相關文章 ID，然後逐篇讀取內容，使用 mb_stripos（若有）或 stripos 做不區分大小寫的字串比對，確保內容確實包含關鍵字。

$query = new WP_Query( array(
    'post_type'      => 'solution',
    'post_status'    => 'any',
    'posts_per_page' => -1,
    's'              => $keyword,
    'fields'         => 'ids',
) );

foreach ( $query->posts as $post_id ) {
    $post = get_post( $post_id );
    if ( ! $post ) {
        continue;
    }

    $content = wp_strip_all_tags( $post->post_content );

    if ( function_exists( 'mb_stripos' ) ) {
        $pos = mb_stripos( $content, $keyword );
    } else {
        $pos = stripos( $content, $keyword );
    }

    if ( $pos !== false ) {
        $results[] = $post_id;
    }
}
wp_reset_postdata();

搜尋結果呈現與操作介面

搜尋結果會以表格形式呈現，包含文章 ID、標題（連結至編輯頁面）、前台連結與編輯按鈕，方便快速查看與編輯。若無輸入關鍵字或找不到結果，會顯示相應提示訊息。

表單使用 WordPress 內建的 wp_nonce_field 與 submit_button，確保安全與一致性。

實務應用與優化方向

此搜尋功能適合用於自訂文章類型管理，尤其是內容量大且需要精準定位文本的場景。未來可考慮加入分頁功能避免一次載入過多文章，或結合全文索引外掛提升搜尋效能。也可擴充搜尋範圍至自訂欄位或分類。

完整程式碼

<?php
// 在「solution」這個 post type 底下新增一個後台子選單：內容關鍵字搜尋
add_action( 'admin_menu', function () {
    // 確保有這個 post type
    if ( ! post_type_exists( 'solution' ) ) {
        return;
    }

    add_submenu_page(
        'edit.php?post_type=solution',          // 父層 (solution 列表底下)
        '內容關鍵字搜尋',                        // 頁面標題
        '內容關鍵字搜尋',                        // 左側選單名稱
        'edit_posts',                           // 權限
        'solution-content-search',              // slug
        'solution_content_search_page_render'   // callback
    );
} );

// 後台頁面：渲染搜尋表單與結果
function solution_content_search_page_render() {
    if ( ! current_user_can( 'edit_posts' ) ) {
        wp_die( '沒有權限檢視此頁面。' );
    }

    $keyword  = '';
    $results  = array();
    $searched = false;

    // 處理表單送出
    if ( isset( $_POST['solution_content_search_submit'] ) ) {
        check_admin_referer( 'solution_content_search_action', 'solution_content_search_nonce' );

        $keyword  = isset( $_POST['solution_keyword'] ) ? sanitize_text_field( wp_unslash( $_POST['solution_keyword'] ) ) : '';
        $searched = true;

        if ( $keyword !== '' ) {
            // 先用 WP_Query 找出可能包含關鍵字的文章 (全文搜尋)
            $query = new WP_Query( array(
                'post_type'      => 'solution',
                'post_status'    => 'any',
                'posts_per_page' => -1,
                's'              => $keyword,
                'fields'         => 'ids',
            ) );

            if ( $query->have_posts() ) {
                foreach ( $query->posts as $post_id ) {
                    $post = get_post( $post_id );
                    if ( ! $post ) {
                        continue;
                    }

                    // 從內容中做字串檢查（確保 content 真的有包含關鍵字）
                    $content = wp_strip_all_tags( $post->post_content );

                    if ( function_exists( 'mb_stripos' ) ) {
                        $pos = mb_stripos( $content, $keyword );
                    } else {
                        $pos = stripos( $content, $keyword );
                    }

                    if ( $pos !== false ) {
                        $results[] = $post_id;
                    }
                }
            }
            wp_reset_postdata();
        }
    }

    ?>
    <div class="wrap">

<h1>Solution 內容關鍵字搜尋</h1>

<p>輸入一個關鍵字，系統會掃描 &lt;code&gt;solution&lt;/code&gt;
 文章類型的內容（content），只要有包含該字串，就列出標題與編輯連結。</p>

        <form method="post" style="margin-top: 1em; margin-bottom: 2em;">
            <?php wp_nonce_field( 'solution_content_search_action', 'solution_content_search_nonce' ); ?>

            <table class="form-table" role="presentation">

<tr>
                    <th scope="row">
                        <label for="solution_keyword">關鍵字字串</label>
                    </th>

<td>
                        <input
                            type="text"
                            id="solution_keyword"
                            name="solution_keyword"
                            class="regular-text"
                            value="<?php echo esc_attr( $keyword ); ?>"
                            placeholder="例如：API、某段程式碼、特定中文句子"
                        />
                    </td>
                </tr>
            </table>

            <?php submit_button( '開始搜尋', 'primary', 'solution_content_search_submit' ); ?>
        </form>

        <?php if ( $searched ) : ?>

<h2>搜尋結果</h2>

            <?php if ( $keyword === '' ) : ?>
                <div class="notice notice-warning"><p>請輸入關鍵字。</p></div>
            <?php elseif ( empty( $results ) ) : ?>
                <div class="notice notice-info"><p>沒有找到內容包含「<?php echo esc_html( $keyword ); ?>」的 solution 文章。</p></div>
            <?php else : ?>

<p>找到 <?php echo esc_html( count( $results ) ); ?> 篇文章，內容中包含「<?php echo esc_html( $keyword ); ?>」。</p>

                <table class="widefat fixed striped">

<thead>

<tr>
                            <th scope="col" style="width: 50px;">ID</th>
                            <th scope="col">標題</th>
                            <th scope="col" style="width: 200px;">前台連結</th>
                            <th scope="col" style="width: 150px;">編輯</th>
                        </tr>
                    </thead>

<tbody>
                    <?php foreach ( $results as $post_id ) :
                        $title     = get_the_title( $post_id );
                        $view_link = get_permalink( $post_id );
                        $edit_link = get_edit_post_link( $post_id, '' );
                    ?>

<tr>

<td><?php echo esc_html( $post_id ); ?></td>

<td>
                                <?php if ( $edit_link ) : ?>
                                    <a href="<?php echo esc_url( $edit_link ); ?>">
                                        <?php echo esc_html( $title ); ?>
                                    </a>
                                <?php else : ?>
                                    <?php echo esc_html( $title ); ?>
                                <?php endif; ?>
                            </td>

<td>
                                <?php if ( $view_link ) : ?>
                                    <a href="<?php echo esc_url( $view_link ); ?>" target="_blank" rel="noopener noreferrer">
                                        檢視
                                    </a>
                                <?php else : ?>
                                    -
                                <?php endif; ?>
                            </td>

<td>
                                <?php if ( $edit_link ) : ?>
                                    <a href="<?php echo esc_url( $edit_link ); ?>" class="button button-small">
                                        編輯文章
                                    </a>
                                <?php else : ?>
                                    -
                                <?php endif; ?>
                            </td>
                        </tr>
                    <?php endforeach; ?>
                    </tbody>
                </table>
            <?php endif; ?>
        <?php endif; ?>
    </div>
    <?php
}

在 WordPress 後台管理自訂文章類型（Custom Post Type）時，有時需要快速批次更新文章內容中的特定字串。這段程式碼示範如何在名為 solution 的自訂文章類型新增一個子選單，提供後台管理者輸入舊字串與新字串，並批次替換所有相關文章內容中的文字。適合有基本 WordPress 開發經驗，想要自訂後台功能以提升內容維護效率的工程師或自學者。

新增子選單介面

利用 admin_menu action 新增子選單，並限定該選單只在 solution 文章類型下顯示。權限設定為 edit_posts，確保只有有編輯文章權限的使用者能操作。

add_action('admin_menu', function () {
    if (!post_type_exists('solution')) {
        return;
    }

    add_submenu_page(
        'edit.php?post_type=solution',
        '內容關鍵字取代',
        '內容關鍵字取代',
        'edit_posts',
        'solution-content-replace',
        'solution_content_replace_page'
    );
});

這段程式碼確保子選單只會在 solution 文章類型的管理頁面出現，並且點擊後會呼叫 solution_content_replace_page 函式來渲染頁面。

後台頁面與表單處理

solution_content_replace_page 函式負責顯示輸入表單與處理替換邏輯。首先檢查使用者權限，避免未授權存取。接著使用 WordPress 的 Nonce 機制保障表單安全。

if (!current_user_can('edit_posts')) {
    wp_die('沒有權限。');
}

if (isset($_POST['solution_replace_submit'])) {
    check_admin_referer('solution_replace_action', 'solution_replace_nonce');

    $old = isset($_POST['old_keyword']) ? sanitize_text_field($_POST['old_keyword']) : '';
    $new = isset($_POST['new_keyword']) ? sanitize_text_field($_POST['new_keyword']) : '';

    // 進行批次替換
}

使用者輸入的舊字串與新字串會經過 sanitize_text_field 清理，避免 XSS 或其他安全問題。

批次搜尋與替換邏輯

當舊字串不為空時，使用 WP_Query 撈取所有 solution 文章的 ID，並逐篇讀取內容。若文章內容包含舊字串，則使用 str_replace 替換後，呼叫 wp_update_post 更新文章。

$query = new WP_Query([
    'post_type'      => 'solution',
    'post_status'    => 'any',
    'posts_per_page' => -1,
    'fields'         => 'ids',
]);

foreach ($query->posts as $post_id) {
    $post = get_post($post_id);
    if (!$post) {
        continue;
    }

    $content = $post->post_content;

    if (mb_strpos($content, $old) !== false) {
        $updated_content = str_replace($old, $new, $content);

        wp_update_post([
            'ID'           => $post_id,
            'post_content' => $updated_content
        ]);

        $results[] = [
            'id'     => $post_id,
            'title'  => $post->post_title,
            'status' => '已替換'
        ];
    }
}
wp_reset_postdata();

結果呈現與使用者體驗

頁面會根據執行狀態顯示不同訊息：

• 若未輸入舊字串，提醒使用者必須填寫。
• 若找不到包含舊字串的文章，顯示資訊提示。
• 若有替換成功的文章，列出文章 ID、標題、狀態與編輯連結，方便管理者後續檢視。

這樣的設計讓使用者能清楚知道批次操作的結果，並快速跳轉編輯。

實務應用與優化建議

此功能適合內容量大且需定期文字修正的網站，如產品說明、技術文件等。未來可擴充：

• 支援正則表達式替換，提高靈活度。
• 加入替換前後內容差異預覽，降低誤替換風險。
• 加入分頁或批次處理，避免大量文章一次更新造成伺服器負擔。

常見問題與注意事項

• 請確認使用者權限設定正確，避免誤用。
• 替換操作無法還原，建議先備份資料庫。
• 文字替換為純字串，不支援 HTML 或多語系複雜處理。

完整程式碼

<?php
// 在 solution post type 底下新增子選單：內容關鍵字取代
add_action('admin_menu', function () {
    if (!post_type_exists('solution')) {
        return;
    }

    add_submenu_page(
        'edit.php?post_type=solution',
        '內容關鍵字取代',
        '內容關鍵字取代',
        'edit_posts',
        'solution-content-replace',
        'solution_content_replace_page'
    );
});

// 後台頁面
function solution_content_replace_page() {
    if (!current_user_can('edit_posts')) {
        wp_die('沒有權限。');
    }

    $old = '';
    $new = '';
    $results = [];
    $executed = false;

    if (isset($_POST['solution_replace_submit'])) {
        check_admin_referer('solution_replace_action', 'solution_replace_nonce');

        $old = isset($_POST['old_keyword']) ? sanitize_text_field($_POST['old_keyword']) : '';
        $new = isset($_POST['new_keyword']) ? sanitize_text_field($_POST['new_keyword']) : '';

        $executed = true;

        if ($old !== '') {
            $query = new WP_Query([
                'post_type'      => 'solution',
                'post_status'    => 'any',
                'posts_per_page' => -1,
                'fields'         => 'ids',
            ]);

            foreach ($query->posts as $post_id) {
                $post = get_post($post_id);
                if (!$post) {
                    continue;
                }

                $content = $post->post_content;

                // 檢查舊字串是否存在
                if (mb_strpos($content, $old) !== false) {
                    // 替換
                    $updated_content = str_replace($old, $new, $content);

                    // 更新文章
                    wp_update_post([
                        'ID'           => $post_id,
                        'post_content' => $updated_content
                    ]);

                    $results[] = [
                        'id'     => $post_id,
                        'title'  => $post->post_title,
                        'status' => '已替換'
                    ];
                }
            }
            wp_reset_postdata();
        }
    }
    ?>

<div class="wrap">

<h2>Solution – 內容關鍵字取代</h2>

        <form method="post">
            <?php wp_nonce_field('solution_replace_action', 'solution_replace_nonce'); ?>

            <table class="form-table">

<tr>

<th><label for="old_keyword">要搜尋的字（舊字串）</label></th>

<td>
                        <input type="text" id="old_keyword" name="old_keyword" class="regular-text"
                               value="<?php echo esc_attr($old); ?>"
                               placeholder="例如：舊字串">
                    </td>
                </tr>

<tr>

<th><label for="new_keyword">替換成（新字串）</label></th>

<td>
                        <input type="text" id="new_keyword" name="new_keyword" class="regular-text"
                               value="<?php echo esc_attr($new); ?>"
                               placeholder="例如：新字串（可空白）">
                    </td>
                </tr>
            </table>

            <?php submit_button('開始批次取代', 'primary', 'solution_replace_submit'); ?>
        </form>

        <?php if ($executed): ?>

<h2>取代結果</h2>

            <?php if ($old === ''): ?>
                <div class="notice notice-warning"><p>請輸入要搜尋的舊字串。</p></div>

            <?php elseif (empty($results)): ?>
                <div class="notice notice-info"><p>沒有任何文章包含「<?php echo esc_html($old); ?>」。</p></div>

            <?php else: ?>
                <table class="widefat striped">

<thead>

<tr>

<th>ID</th>

<th>標題</th>

<th>狀態</th>

<th>編輯連結</th>
                    </tr>
                    </thead>

<tbody>
                    <?php foreach ($results as $r): ?>

<tr>

<td><?php echo esc_html($r['id']); ?></td>

<td><?php echo esc_html($r['title']); ?></td>

<td><?php echo esc_html($r['status']); ?></td>

<td><a href="<?php echo get_edit_post_link($r['id']); ?>" class="button button-small">編輯</a></td>
                        </tr>
                    <?php endforeach; ?>
                    </tbody>
                </table>
            <?php endif; ?>

        <?php endif; ?>
    </div>

    <?php
}

這段 PHP 程式碼是為了解決 WordPress 使用 Polylang 多語系外掛時，如何批量將特定文章類型的內容從一種語言複製到另一種語言，並建立正確的翻譯關聯。適合需要管理大量多語系內容的網站管理員或開發者，尤其是想自動化翻譯文章複製流程的技術人員。

Polylang 官方 API 的使用背景

Polylang 提供了多個官方函式來管理文章語言與翻譯關聯，如 pll_set_post_language 設定文章語言，pll_save_post_translations 儲存翻譯群組，這是官方推薦的做法，能確保多語系資料完整且一致。

後台介面設計與操作流程

後台子選單與頁面

程式碼透過 add_submenu_page 在自訂文章類型「investor_relations」的管理頁面下新增子選單，提供單筆測試與批量複製兩種操作介面。使用者可選擇目標語言（目前限制為英文與日文），並執行對應動作。

權限與安全檢查

頁面載入時會檢查使用者是否有 manage_options 權限，並確認 Polylang API 函式存在，避免外掛未啟用或權限不足導致錯誤。

核心功能：複製文章並建立翻譯關聯

1. 確認來源文章及語言設定

函式 ir_clone_post_official 會先取得來源文章，並用 pll_set_post_language 強制設定來源文章語言，確保語言標記正確。

ir_set_lang_official( $source_id, $source_lang );

2. 檢查目標語言翻譯是否已存在

利用 pll_get_post_translations 取得該文章的所有語言版本，若目標語言已存在翻譯文章，則跳過建立，避免重複。

3. 建立新文章（翻譯版本）

使用 WordPress 官方函式 wp_insert_post 複製文章內容與屬性，並設定新文章的語言為目標語言。

$new_id = wp_insert_post([...]);
ir_set_lang_official( $new_id, $target_lang );

4. 儲存翻譯關聯

將來源文章與新文章的語言關聯資料更新至 Polylang，確保前台語言切換功能正常。

$translations[ $target_lang ] = $new_id;
pll_save_post_translations( $translations );

5. 複製分類法與特色圖片

排除語言分類法後，複製其他自訂分類法的關聯，並複製特色圖片，保持內容一致性。

6. 複製 ACF 自訂欄位資料

若有安裝 Advanced Custom Fields 外掛，會將所有欄位資料一併複製，包含上傳檔案，避免資料遺失。

實務應用與優化建議

• 備份資料庫：執行批量複製前務必備份，避免誤操作導致資料錯亂。
• 單筆測試：先用單筆測試功能確保流程正常，再進行批量操作。
• 擴充語言：可依需求新增允許的目標語言陣列。
• 錯誤處理：可加強錯誤回報與日誌紀錄，方便除錯與維護。

常見問題與注意事項

• Polylang API 函式不存在時，需確認外掛是否啟用。
• 複製文章時，若有其他外掛影響文章資料，可能需要額外處理。
• 語言分類法不應被複製，以免覆寫 Polylang 的語言設定。

完整程式碼

<?php
/**
 * Investor Relations 單語言批量翻譯複製工具（最終版）
 * - 完全走 Polylang 官方流程：
 *   wp_insert_post + pll_set_post_language + pll_save_post_translations
 * - 自動跳過「已經有目標語言翻譯」的文章
 */

define( 'IR_SOURCE_LANG', 'zh' );                  // 來源語言：中文
define( 'IR_POST_TYPE', 'investor_relations' );    // Post type：investor_relations

/* =========================
 * 共用：設定語言（官方 API）
 * ========================= */
function ir_set_lang_official( $post_id, $lang_code ) {
    if ( function_exists( 'pll_set_post_language' ) ) {
        pll_set_post_language( $post_id, $lang_code );
    }
}

/* =========================
 * 後台子選單
 * ========================= */
add_action( 'admin_menu', function () {
    add_submenu_page(
        'edit.php?post_type=' . IR_POST_TYPE,
        'Bulk Copy Translations (Official)',
        'Bulk Copy Translations (Official)',
        'manage_options',
        'ir-bulk-translations-official',
        'ir_bulk_translations_official_page'
    );
});

/* =========================
 * 後台頁面 + 控制流程
 * ========================= */
function ir_bulk_translations_official_page() {

    // 允許的目標語言（依照 Polylang 的 code）
    $allowed_target_langs = [ 'en', 'ja' ];

    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( '沒有權限。' );
    }

    if ( ! function_exists( 'pll_set_post_language' ) || ! function_exists( 'pll_save_post_translations' ) ) {
        echo '<div class="notice notice-error"><p>Polylang API 不存在，請確認外掛是否啟用。</p></div>';
        return;
    }

    // 目前選擇的目標語言（預設 en）
    $current_target = isset( $_POST['ir_target_lang'] )
        ? sanitize_text_field( $_POST['ir_target_lang'] )
        : 'en';

    if ( ! in_array( $current_target, $allowed_target_langs, true ) ) {
        $current_target = 'en';
    }

    echo '
<h1>Investor Relations 翻譯複製工具（官方流程版）</h1>';
    echo '
<p>來源語言固定為：<code>' . esc_html( IR_SOURCE_LANG ) . '
';
    echo '
⚠️ 執行前務必先備份資料庫！
';

    echo '
.ir-lang-select{margin-left:8px;}';

    /* ------------ 單筆測試表單 ------------- */
    echo '
單筆文章測試
';
    echo '';
    wp_nonce_field( 'ir_single_test_official' );
    echo '輸入文章 ID：';

    echo '目標語言：';
    echo '';
    foreach ( $allowed_target_langs as $code ) {
        printf(
            '%s',
            esc_attr( $code ),
            selected( $current_target, $code, false ),
            esc_html( strtoupper( $code ) )
        );
    }
    echo ' ';

    submit_button( '測試複製此文章', 'secondary', 'ir_single_test', false );
    echo '';

    /* ------------ 批次表單 ------------- */
    echo '
批量複製所有中文文章
';
    echo '';
    wp_nonce_field( 'ir_bulk_official' );

    echo '目標語言：';
    echo '';
    foreach ( $allowed_target_langs as $code ) {
        printf(
            '%s',
            esc_attr( $code ),
            selected( $current_target, $code, false ),
            esc_html( strtoupper( $code ) )
        );
    }
    echo ' ';

    submit_button( '執行批次複製（請先單筆測試）', 'primary', 'ir_bulk_run', false );
    echo '';

    /* ------------ 執行動作 ------------- */

    // 單筆
    if ( isset( $_POST['ir_single_test'] ) ) {
        check_admin_referer( 'ir_single_test_official' );
        $post_id = isset( $_POST['ir_test_id'] ) ? intval( $_POST['ir_test_id'] ) : 0;
        $target  = isset( $_POST['ir_target_lang'] ) ? sanitize_text_field( $_POST['ir_target_lang'] ) : 'en';
        ir_run_single_copy_official( $post_id, $target );
    }

    // 批次
    if ( isset( $_POST['ir_bulk_run'] ) ) {
        check_admin_referer( 'ir_bulk_official' );
        $target = isset( $_POST['ir_target_lang'] ) ? sanitize_text_field( $_POST['ir_target_lang'] ) : 'en';
        ir_run_bulk_copy_official( $target );
    }

}

function ir_run_single_copy_official( $post_id, $target_lang ) {
    echo '
<h3>單筆測試結果</h3>';

    if ( ! $post_id || ! get_post( $post_id ) ) {
        echo '<p style="color:red;">找不到文章 ID：' . esc_html( $post_id ) . '</p>';
        return;
    }

    $report = ir_clone_post_official( $post_id, $target_lang );

    echo '<pre style="background:white; padding:10px; border:1px solid #ccc;">';
    echo esc_html( implode( "\n", $report ) );
    echo '</pre>';
}

/* =========================
 * 批量處理所有中文文章（官方流程）
 * ========================= */
function ir_run_bulk_copy_official( $target_lang ) {
    $posts = get_posts( [
        'post_type'      => IR_POST_TYPE,
        'posts_per_page' => -1,
        'post_status'    => 'any',
        'lang'           => IR_SOURCE_LANG, // Polylang 的語言 query var
        'fields'         => 'ids',
    ] );

    echo '
<h2>批次執行結果（目標語言：' . esc_html( strtoupper( $target_lang ) ) . '）</h2>';

    if ( empty( $posts ) ) {
        echo '
<p>沒有找到來源語言（' . esc_html( IR_SOURCE_LANG ) . '）的文章。</p>';
        return;
    }

    $output = [];

    foreach ( $posts as $post_id ) {
        $report  = ir_clone_post_official( $post_id, $target_lang );
        $output  = array_merge( $output, $report );
    }

    echo '<pre style="background:white; max-height:450px; overflow:auto; padding:10px; border:1px solid #ccc;">';
    echo esc_html( implode( "\n", $output ) );
    echo '</pre>';
}

/* =========================
 * 核心：官方流程複製一篇文章 → 目標語言翻譯
 * ========================= */
function ir_clone_post_official( $source_id, $target_lang ) {
    $report = [];

    $source_post = get_post( $source_id );
    if ( ! $source_post ) {
        $report[] = "❌ 原文 {$source_id} 不存在";
        return $report;
    }

    $source_lang = IR_SOURCE_LANG;

    // Step 1) 先確保原文語言正確
    ir_set_lang_official( $source_id, $source_lang );
    $report[] = "Step 1) 設定原文語言：{$source_id} → {$source_lang}";

    // 取得現有翻譯 group
    $translations = function_exists( 'pll_get_post_translations' )
        ? pll_get_post_translations( $source_id )
        : [];

    if ( empty( $translations[ $source_lang ] ) ) {
        $translations[ $source_lang ] = $source_id;
    }

    // ✅ 若已存在該語言翻譯 → 自動跳過
    if ( ! empty( $translations[ $target_lang ] ) ) {
        $existing = $translations[ $target_lang ];
        $report[] = "⚠️ 原文 {$source_id} 已有 {$target_lang} 翻譯（ID {$existing}），跳過建立新文章。";

        // 做個語言 debug
        $lang_debug = [];
        foreach ( $translations as $code => $pid ) {
            $lang_debug[] = $code . ':' . $pid . '(' . pll_get_post_language( $pid ) . ')';
        }
        $report[] = '🧪 目前語言狀態：' . implode( ', ', $lang_debug );

        return $report;
    }

    // Step 2) 使用 wp_insert_post 建立新文章（官方建議做法）
    $new_id = wp_insert_post( [
        'post_type'      => $source_post->post_type,
        'post_status'    => $source_post->post_status,
        'post_title'     => $source_post->post_title,
        'post_content'   => $source_post->post_content,
        'post_excerpt'   => $source_post->post_excerpt,
        'post_author'    => $source_post->post_author,
        'post_date'      => $source_post->post_date,
        'post_date_gmt'  => $source_post->post_date_gmt,
        'menu_order'     => $source_post->menu_order,
    ], true );

    if ( is_wp_error( $new_id ) ) {
        $report[] = "❌ wp_insert_post 錯誤：" . $new_id->get_error_message();
        return $report;
    }
    $report[] = "Step 2) 建立新文章：{$new_id}";

    // Step 3) 官方建議：先設定新文章語言
    ir_set_lang_official( $new_id, $target_lang );
    $report[] = "Step 3) 設定新文章語言：{$new_id} → {$target_lang}";

    // Step 4) 官方建議：建立翻譯關聯（保留既有語言）
    $translations[ $target_lang ] = $new_id;
    pll_save_post_translations( $translations );
    $report[] = "Step 4) 儲存翻譯關聯：" . json_encode( $translations );

    // Step 5) 複製 taxonomy（排除語言 taxonomy，避免覆寫語言）
    $taxes = get_object_taxonomies( IR_POST_TYPE );
    $taxes = array_diff( $taxes, [ 'language', 'pll_language' ] );

    foreach ( $taxes as $tax ) {
        $terms = wp_get_object_terms( $source_id, $tax, [ 'fields' => 'ids' ] );
        if ( ! is_wp_error( $terms ) ) {
            wp_set_object_terms( $new_id, $terms, $tax, false );
        }
    }

    // Step 6) 複製特色圖片
    $thumb = get_post_thumbnail_id( $source_id );
    if ( $thumb ) {
        set_post_thumbnail( $new_id, $thumb );
    }

    // Step 7) 複製 ACF 欄位（包含上傳檔案）
    if ( function_exists( 'get_field_objects' ) && function_exists( 'update_field' ) ) {
        $fields = get_field_objects( $source_id );
        if ( $fields ) {
            foreach ( $fields as $field ) {
                update_field( $field['key'], $field['value'], $new_id );
            }
        }
    }

    // 最後：實際語言檢查
    $src_lang_real = pll_get_post_language( $source_id );
    $new_lang_real = pll_get_post_language( $new_id );

    $report[] = "🧪 實際語言檢查：原文 {$source_id} 語言：{$src_lang_real}；新文 {$new_id} 語言：{$new_lang_real}";
    $report[] = "✅ 完成：原文 {$source_id} → {$target_lang} 翻譯 {$new_id}";

    return $report;
}

在 WordPress 網站中，常見需求是當新會員註冊時，自動建立一篇專屬於該會員的自訂文章類型（Custom Post Type, CPT），例如會員介紹頁面。本文適合具備基本 WordPress 開發經驗的工程師或自學者，說明如何利用 user_register Hook 自動建立 member_info 文章，並設定內容與 ACF 欄位。

註冊 member_info 自訂文章類型

首先，必須在主題的 functions.php 中註冊 member_info 這個自訂文章類型。以下程式碼會在 WordPress 初始化時執行：

function register_member_info_post_type() {
  $args = array(
    'labels' => array(
      'name' => '會員資訊',
      'singular_name' => '會員資訊'
    ),
    'public' => true,
    'has_archive' => true,
    'supports' => array('title', 'editor', 'author'),
    'rewrite' => array('slug' => 'member-info'),
  );
  register_post_type('member_info', $args);
}
add_action('init', 'register_member_info_post_type');

此段程式碼會建立一個公開且有存檔頁的 CPT，並支援標題、內容編輯器與作者欄位。

自動建立會員資訊文章

接著，利用 user_register Hook 監聽新會員註冊事件，當會員註冊時自動建立一篇 member_info 文章，並填入預設內容與 ACF 欄位：

function ks_create_member_info_post($user_id) {
  $user = get_userdata($user_id);
  $display_name = $user->display_name;
  $post_title = $display_name;

  $post_content = '

  <h3 class="wp-block-heading"><strong>經歷</strong>（公開資訊）</h3>

<p>公開資訊</p>

  <h3 class="wp-block-heading"><strong>專長</strong>（公開資訊）</h3>

<p>公開資訊</p>
  ';

  $post_data = array(
    'post_title' => $post_title,
    'post_content' => $post_content,
    'post_status' => 'publish',
    'post_author' => $user_id,
    'post_type' => 'member_info',
  );

  $post_id = wp_insert_post($post_data);

  if ($post_id) {
    update_field('member_content', '登入會員限定內容', $post_id);
    update_field('member_current_position', '目前任職', $post_id);
    update_field('member_experience', '（公開資訊區）<br>信箱、網站、學歷、學號？', $post_id);
  }
}
add_action('user_register', 'ks_create_member_info_post');

此函式會取得新會員的顯示名稱作為文章標題，並用 Gutenberg 格式設定文章內容。若有安裝 Advanced Custom Fields，則會填入指定欄位的預設值。

程式碼說明

• user_register Hook：會員註冊時觸發，執行自動建立文章函式。
• get_userdata($user_id)：取得會員資料。
• wp_insert_post()：建立自訂文章並回傳文章 ID。
• Gutenberg 內容格式：使用區塊編輯器標記語法，方便未來編輯。
• ACF 欄位設定：透過 update_field() 填入預設值，需先安裝並啟用 ACF 外掛。

確保程式運作正確

• 確認 member_info CPT 已成功註冊並可在後台管理。
• 確認 Advanced Custom Fields 外掛已啟用，且欄位名稱正確。
• 測試新會員註冊流程，並檢查「會員資訊」文章是否自動產生。

延伸應用與常見坑

• 若需更多欄位，可在 ACF 中擴充並同步更新 update_field()。
• 若會員資料需同步更新文章，可監聽 profile_update Hook。
• 注意文章內容格式需符合 Gutenberg 區塊語法，避免前端顯示異常。

完整程式碼

function register_member_info_post_type() {
  $args = array(
    'labels' => array(
      'name' => '會員資訊',
      'singular_name' => '會員資訊'
    ),
    'public' => true,
    'has_archive' => true,
    'supports' => array('title', 'editor', 'author'),
    'rewrite' => array('slug' => 'member-info'),
  );
  register_post_type('member_info', $args);
}
add_action('init', 'register_member_info_post_type');

function ks_create_member_info_post($user_id) {
  $user = get_userdata($user_id);
  $display_name = $user->display_name;
  $post_title = $display_name;

  $post_content = '

  <h3 class="wp-block-heading"><strong>經歷</strong>（公開資訊）</h3>

<p>公開資訊</p>

  <h3 class="wp-block-heading"><strong>專長</strong>（公開資訊）</h3>

<p>公開資訊</p>
  ';

  $post_data = array(
    'post_title' => $post_title,
    'post_content' => $post_content,
    'post_status' => 'publish',
    'post_author' => $user_id,
    'post_type' => 'member_info',
  );

  $post_id = wp_insert_post($post_data);

  if ($post_id) {
    update_field('member_content', '登入會員限定內容', $post_id);
    update_field('member_current_position', '目前任職', $post_id);
    update_field('member_experience', '（公開資訊區）<br>信箱、網站、學歷、學號？', $post_id);
  }
}
add_action('user_register', 'ks_create_member_info_post');

在使用 WordPress 建置網站時，若頁面內容多以 shortcode 方式組合，想要在頁面中靈活顯示特定文章類型（Post Type）的文章，就需要將查詢文章的功能包裝成 shortcode。這樣可以方便在任何頁面或文章中插入，提升內容管理彈性。本文適合有基礎 PHP 與 WordPress 開發經驗的工程師或自學者。

建立自訂 Shortcode 函式

我們可以在主題的 functions.php 檔案中，撰寫一個函式來查詢指定的文章類型，並輸出 HTML 結構。以下為範例關鍵程式碼說明：

function home_post_listing_shortcode( $atts ) {
    ob_start();
    // 建立 WP_Query 物件，查詢 post_type 為 'post' 的文章，限制顯示 3 篇，依標題排序（降冪）
    $query = new WP_Query( array(
        'post_type'      => 'post', // 可替換成想抓取的自訂文章類型
        'posts_per_page' => 3,      // 取出文章數量
        'order'          => 'DESC', // 排序方式 ASC(小->大), DESC(大->小)
        'orderby'        => 'title' // 依標題排序
    ) );

    if ( $query->have_posts() ) {
        echo '<ul class="info-listing">';
        while ( $query->have_posts() ) {
            $query->the_post();
            ?>
            <li id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
                <div class="category_name"><?php the_category(); ?></div>
                <?php the_date('Y-m-d at g:ia', '<div class="news_date">', '</div>'); ?>
                <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
            </li>
            <?php
        }
        echo '</ul>';
        wp_reset_postdata();
    }

    return ob_get_clean();
}

註冊 Shortcode

將上述函式註冊為 shortcode，讓 WordPress 辨識並可在頁面中使用：

add_shortcode( 'list-posts-home', 'home_post_listing_shortcode' );

註冊後，只要在 WordPress 後台的頁面編輯器中插入 [list-posts-home]，就會顯示該 shortcode 所輸出的文章列表。

實際應用與延伸

• 可修改 post_type 參數為自訂文章類型，如 product、event 等。
• 可加入 category_name 或 tax_query 參數，篩選特定分類文章。
• 調整 posts_per_page 與排序條件，符合不同需求。
• 搭配頁面建構器（如 Visual Composer）使用，提升內容排版彈性。

常見坑點

• order 參數應為 DESC（大到小），原範例中寫成 DSC 會無效。
• 使用 the_date() 時，若多篇文章同一天只會顯示一次日期，改用 the_time() 可避免此問題。
• 記得使用 wp_reset_postdata() 恢復全域文章資料，避免影響其他查詢。

完整程式碼

function home_post_listing_shortcode( $atts ) {
    ob_start();
    $query = new WP_Query( array(
        'post_type'      => 'post',
        'posts_per_page' => 3,
        'order'          => 'DESC',
        'orderby'        => 'title',
    ) );

    if ( $query->have_posts() ) {
        echo '<ul class="info-listing">';
        while ( $query->have_posts() ) {
            $query->the_post();
            ?>
            <li id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
                <div class="category_name"><?php the_category(); ?></div>
                <?php the_date('Y-m-d at g:ia', '<div class="news_date">', '</div>'); ?>
                <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
            </li>
            <?php
        }
        echo '</ul>';
        wp_reset_postdata();
    }

    return ob_get_clean();
}

add_shortcode( 'list-posts-home', 'home_post_listing_shortcode' );