WP 标签批量翻译脚本准确性问题排查与修复
问题背景
在使用 Polylang 插件进行中英文标签同步时，发现批量翻译脚本存在间歇性的计数不准确问题。脚本显示处理了 8324 个标签，但后台实际有 8328 个中文标签，每次执行结果都不一致。
问题现象
源语言标签总数: 8328 准确
已处理新标签: 0 不准确（理论应为 4）
已跳过已有翻译: 9000 不准确（应为 8324）
处理率: 108.07%
排查过程
第一次排查：分页方式问题
最初使用 offset 参数进行分页：
$terms = get_terms([
'taxonomy' => 'post_tag',
'lang' => $source_lang,
'number' => $per_page,
'offset' => $offset,
]);
问题分析：使用 offset 分页时，在处理过程中创建新的目标语言标签会改变数据库中的记录数，导致后续分页偏移量不准确。
修复尝试：改用 paged 参数替代 offset：
$terms = get_terms([
'taxonomy' => 'post_tag',
'lang' => $source_lang,
'number' => $per_page,
'paged' => $page,
]);
第二次排查：数据库表不存在
修改后出现新错误：
WordPress database error Table 'wp_polylang_terms' doesn't exist
问题分析：直接查询了不存在的 Polylang 数据库表，应该使用 Polylang 提供的 API 函数。
修复尝试：参考项目中已有的 merge-tags.php 文件，改用 get_terms() 配合 lang 参数获取标签列表。
第三次排查：计数仍不准确
即使使用了 paged 参数，计数仍然不准确：
已跳过已有翻译: 9000
问题分析：使用 get_terms() 分页查询时，新创建的英文标签被后续查询获取到，导致 skipped 计数错误。
问题根源：在循环处理过程中创建的英文标签，被后续的 get_terms() 查询捕获到，因为查询条件只限制了语言，但新创建的英文标签可能被缓存或重新索引。
最终解决方案
核心思路：先一次性获取所有源语言标签的 ID 列表，然后基于这个静态列表进行处理，避免后续查询被新创建的数据影响。
// 先一次性获取所有源语言标签的ID列表
$source_term_ids = get_terms([
'taxonomy' => 'post_tag',
'lang' => $source_lang,
'hide_empty' => false,
'fields' => 'ids',
]);
// 使用 array_chunk 分批处理
foreach (array_chunk($source_term_ids, $per_page) as $batch) {
foreach ($batch as $term_id) {
// 处理每个标签...
}
}
关键改进点：
- 静态列表：提前获取完整的源语言标签 ID 列表，避免后续查询被新数据污染
- 数组分片：使用
array_chunk()进行内存友好的分批处理 - 准确计数：基于静态列表进行计数，确保统计准确
优化后的完整代码
<?php
if (php_sapi_name() !== 'cli') {
die("❌ 请在命令行运行\n");
}
require __DIR__ . '/wp-config.php';
global $wpdb, $polylang;
$per_page = 1000;
$source_lang = 'zh';
$target_lang = 'en';
$processed = 0;
$skipped = 0;
// 先一次性获取所有源语言标签的ID列表
$source_term_ids = get_terms([
'taxonomy' => 'post_tag',
'lang' => $source_lang,
'hide_empty' => false,
'fields' => 'ids',
]);
$total_terms = count($source_term_ids);
// 分批处理
foreach (array_chunk($source_term_ids, $per_page) as $batch) {
foreach ($batch as $term_id) {
$term = get_term($term_id, 'post_tag');
// 检查是否已有翻译
$target_id = pll_get_term($term_id, $target_lang);
if ($target_id) {
$skipped++;
continue;
}
// 创建翻译标签...
$processed++;
}
}
// 验证阶段
$untranslated_count = 0;
foreach ($source_term_ids as $term_id) {
if (!pll_get_term($term_id, $target_lang)) {
$untranslated_count++;
}
}
修复效果
修复后执行结果：
源语言标签总数: 8328 ✅
已处理新标签: 4 ✅
已跳过已有翻译: 8324 ✅
处理率: 100.00% ✅
经验总结
- 避免动态分页陷阱：在处理过程中会修改数据的场景，应避免使用动态分页查询
- 使用静态数据集：提前获取完整的 ID 列表，确保处理过程的稳定性
- 依赖官方 API：优先使用插件提供的 API 函数，避免直接操作数据库表
- 添加验证环节：在处理完成后进行验证，确保所有数据都被正确处理
参考资料
本文记录了标签批量翻译脚本的排查过程，从问题发现到最终解决，希望能帮助遇到类似问题的开发者。
