AI Context Translate Dev

作者： admin

  • 控制 AI 翻什么、怎么翻

    整站交给 AI 不等于撒手不管。插件给了四个抓手：控制范围、标记例外、改指令、译后替换。

    一、哪些位置会被翻译

    • 可视文本：页面上所有文字节点，但 <script> 与 <style> 里的内容不碰。
    • <title>：浏览器标签页与搜索结果里的标题。
    • meta 的 content：仅限 name/property 中含 title、keywords、description、name 的那些，含 og:title、og:description。
    • placeholder：输入框与文本域的占位提示。
    • alt / title：图片的替代文字与悬停提示。
    • Microdata：itemprop 挂在 content 上的取值照样翻译——这类标签页面上看不见，但搜索引擎读的就是它。
    • 站内链接路径：取决于「翻译 URL 路径」开关。

    结构化数据里有大量机器读的值，译了等于把数据写坏。插件对这些做了两道判断：一是看字段名，sku、price、datePublished、telephone、image 这类一律跳过；二是看值的形态，网址、邮箱、纯数字、ISO 日期（2026-12-31）、ISO 时长（PT30M）、三位货币代码（CNY）一概跳过。所以就算用了没被列举的字段名，机器值也不会被翻译；而 name、description、addressLocality 这类文本字段会正常参与翻译。

    二、标记不需要翻译的内容

    品牌名、型号、代码片段、第三方组件的界面文字——这些译了反而是错的。给元素加上下面任意一个标记，插件在提取阶段就跳过它，既不入库也不消耗额度：

    • class="not-translate"：插件自己的标记，整个元素及其子节点都不翻。
    • class="notranslate"：Google 翻译的通用约定，插件也认，写一次两边都生效。
    • translate="no"：HTML 标准属性，语义最正，推荐新写的模板用它。
    • translate="yes"：在不翻译的区块里开一个口子，让某个子元素照常翻译。
    • class="not-translate-url"：只挡地址改写，链接文字照常翻译，但路径不动、也不加语言前缀。

    三、两条翻译指令

    正文一条、URL 路径一条，后者在打开「翻译 URL 路径」时才显示。两条都可以改，都必须保留三个变量：

    • {{language_from}}：源语言
    • {{language_to}}：目标语言
    • {{translate_data}}：待翻译的 JSON

    缺变量会被拦下不保存（其余设置照常保存），因为少了它们 AI 收不到语言或待译数据，翻译结果必然是错的。指令全部清空保存则自动恢复默认；想直接换回插件当前的默认版本，用编辑框上方的「恢复默认指令」按钮。

    改指令是调质量最直接的手段。行业术语要求、语气偏好、某类内容不要扩写，写进指令比事后一条条改译文省力得多。

    四、字符串替换规则

    在语言管理里按语言配置，AI 译完之后再做一轮定向替换，支持模糊替换、完全匹配、正则替换。它只作用于正文译文，不会套到 URL 路径上（套上去会把地址改坏）。

    典型用法：品牌名被译成了普通名词、某个产品术语每次翻得不一样、想统一把某个说法换成行业惯用词。规则是保存时校验的，正则写错会在界面上直接提示，不会等到翻译时才发现。

    关于额度

    省额度的关键是别重复翻。插件在这几处做了保护：全站按原文 md5 去重，同一段文字只翻一次；「AI 翻译时跳过已有译文」默认勾选；人工改过的译文标记为人工来源，不会被 AI 覆盖；单条文本超长（65000 字符以上）直接跳过，不会拿去撞模型上限。

  • URL 路径翻译与多语言 SEO

    译文页面能不能被搜索引擎正确收录，取决于地址结构和几个头部标记。这篇把插件在这一侧做的事说清楚。

    语言目录：译文页的地址长什么样

    每种目标语言对应一个 URL 前缀，译文页挂在这个目录下，例如 /ja/about/。页面里的站内链接会自动挂到同一个目录下——这一步和「翻译 URL 路径」开关无关，哪怕路径保持原样，链接也会带上语言前缀，否则访客一点链接就跳回原文站点了。

    图片、脚本、样式表这些资源地址不动，改了只会 404。只有导航类地址会处理：<a href>、canonical/shortlink、<form action>、og:url，以及结构化数据里的 itemprop="url" 和 sameAs。

    翻译 URL 路径开关

    打开后，路径本身也会译过去：/ja/关于我们/ 变成 /ja/about-us/ 那种效果。访客打开译文地址时，插件会先把路径换回原文路径，WordPress 才找得到对应的文章，所以译过的地址照常可访问。

    路径的翻译要求和正文完全不同：要保住斜杠层级、不能有空格、扩展名和查询串得原样留着。所以插件为它准备了一条独立的 URL 路径翻译指令，开关打开时才在设置页显示，正文指令不必再写 URL 相关的要求。译文回来后还会再兜一道：剥掉域名、空格换成连字符、合并多余斜杠、查询串与锚点按原文还原、结尾斜杠跟随原文——这些地址要写进 href，错一个字符就是 404。

    路径作为独立数据入库（类型标记为 uri），在「译文数据」里可以按类型筛选、单独修改。开关是后开的话，需要重新翻一遍页面才会产生路径译文，已有的文本译文不受影响。

    hreflang

    插件会在译文页和原文页的 <head> 里输出各语言版本的对应关系，含 x-default，语言管理里配了地区变体的会按 语言-地区 的形式输出。这是搜索引擎判断「这几个地址是同一篇内容的不同语言版本」的依据，不输出的话多语言页面容易被判定成重复内容。

    sitemap 与 robots

    • sitemap：访问语言目录下的 sitemap 时，里面的地址会本地化成该语言的地址。
    • robots.txt：按语言把已有的 Sitemap: 行复制一份补上。这里没有写死地址，而是把站点已有的行按语言复制——所以无论 sitemap 是 WordPress 内置生成的，还是 Yoast、Google XML Sitemaps 之类插件生成的，都能自动跟上。

    语言切换菜单

    默认是浮动可拖动的，位置记在访客浏览器本地。想让它跟着主题版式走，就在设置里填主题某个元素的 id，菜单会挂进那个元素；找不到该 id 时自动回退成浮动显示，不会因为主题改版就没了入口。可选显示旗帜小图标，图标以 data URI 内嵌，不额外发请求。

    菜单里显示哪些语言，受语言管理里「展示对象」控制：所有访客、仅搜索引擎、仅普通用户。

  • 三种翻译方式：手动、后台自动、访客实时

    插件提供三个翻译入口，底层是同一套逻辑，区别只在由谁触发、什么时候触发。

    手动：页面翻译页的按钮

    最可控的方式。选定语言和页面，点「AI 翻译」，结果立刻回填到界面上，可以逐条看、逐条改。内容不多、或者想先看看译文质量再决定策略时，用这个。

    同一页上还有「全部翻译」，会把当前语言下所有待翻译页面排队处理，带进度和停止按钮。适合初次上线时批量预热。

    后台自动：管理员开着后台就在跑

    在翻译设置里打开「后台自动翻译」后，只要有管理员打开着任意一个后台页面，浏览器就会按设定的心跳间隔（最小 15 秒）来领一个待翻译页面交给服务端处理，不需要一直守在「页面翻译」界面。

    要理解它的边界：这依赖浏览器保持打开，关掉后台就停；站点没有常驻队列进程，也不依赖 WP-Cron。上一次还没处理完时不会重复发起。

    访客实时：谁来看就翻谁

    打开「实时翻译」后，访客打开译文页面时，插件会把这一页尚未入库的条目补翻出来，结果直接入库，下一位访客就不用再等。

    旁边的「译文占比达到 __% 才输出译文页面」是配套的保护：占比 = 该页已有译文条数 ÷ 提取到的条数。默认 100，意思是整页翻完才输出译文，达不到就照常显示原文，避免半中半外的页面被搜索引擎收录。

    代价是首个访客要等 AI 返回，页面会明显变慢。内容量大的站点建议先用「全部翻译」预热，再开这个开关兜住新增内容。

    三个入口共用一把锁

    不管从哪个入口进来，任务都要先抢同一把单进程锁。多个管理员同时在线、或者有人正在手动翻译时，其余请求直接空转返回，不会出现两个进程翻同一批内容、把额度烧两遍的情况。

    还有一个容易被忽略的行为：客户端断开不会中断翻译。PHP 默认在浏览器断开后就把脚本掐掉，而一次翻译往往要等 AI 几十秒。访客嫌慢关掉页面、管理员切走标签页都很常见，token 已经花出去了，结果却没入库就等于白烧。所以插件在进入长任务前会显式声明忽略客户端中断，断开归断开，这一轮照样跑完、照样入库。

  • 从零配置到第一篇译文

    装好插件后，后台会多出「AI 上下文翻译」菜单，下面五个页面：翻译设置、语言管理、页面翻译、译文数据、使用说明。配置顺序就按这个来。

    第一步：告诉插件原文是什么语言

    翻译设置页最上面的「默认语言（原文语言）」，指的是站点内容原本的语言，翻译以它为源。这一项不选，任何翻译都跑不起来。

    第二步：配 AI 服务

    同一页往下是 AI 服务，几个字段的实际作用：

    • 模型：下拉里是库内置的模型，也可以直接手填中转站给的模型名。
    • 协议格式：决定按哪套请求格式跟接口通信。gpt-、claude-、gemini-、deepseek- 开头的模型名能自动认出来；认不出的（中转站自定名、私有部署）在这里手选。
    • 接口地址：默认填的是所选模型或协议的官方地址，换模型、换协议会自动跟着变。接自建网关时改成对方的地址即可——填完整端点（…/v1/chat/completions）就原样请求，只填到 …/v1 这类根地址时会自动补上所选协议的对话路径。字段下方会显示实际请求地址，所见即所发。
    • API Key：对应平台的密钥。
    • 代理：留空直连。位于中国的服务器访问 OpenAI/Claude/Gemini 通常需要填，支持 http:// 与 socks5://。
    • 最大输出 token：限的是 AI 单次回复的长度，不是模型的上下文长度。模型支持 1M 上下文，不等于允许一次输出 1M——各模型的输出上限差很远，填超会被平台直接拒绝。填 0 表示不传这个参数、跟随所选模型的内置值，换模型也不用改，推荐这么填。
    • 请求超时：一次 AI 请求的等待上限，整页翻译时建议给足。

    第三步：添加目标语言

    「语言管理」里每加一种语言，就多一份可配置项：

    • URL 前缀：译文页面挂在哪个目录下，例如填 ja，译文地址就是 /ja/…。
    • hreflang 与地区变体：输出到页面 <head> 里告诉搜索引擎语言对应关系，需要区分地区时（如 zh-Hant 配 TW）在这里填。
    • 排序：语言切换菜单里的先后顺序。
    • 展示对象：所有访客、仅搜索引擎、仅普通用户三选一。做灰度或只想让搜索引擎先收录时用得上。
    • 字符串替换规则：AI 译完之后再做一轮定向替换，支持模糊替换、完全匹配、正则替换三种。品牌名被译错、某个术语要统一成行业叫法，用这个兜底最省事。

    第四步：翻第一页

    进「页面翻译」，选语言和页面，界面左右并排：左边是从这一页提取出来的原文 JSON，右边是对应的译文。点「AI 翻译」，插件抓取页面、提取、分批送 AI、结果入库并回填到右侧，过程中可以看到进度。

    几个容易忽略的细节：

    • 工具栏的「AI 翻译时跳过已有译文」默认勾着，已经有译文的条目不会重复消耗额度。想整页重译就取消勾选。
    • 右侧译文可以直接改，保存后这条会被标记为人工来源。
    • 「全部翻译」会依次处理当前语言下所有待翻译页面，带进度条和停止按钮，中途停下已完成的部分不会丢。

    翻完打开 /ja/（或你设的前缀）就能看到译文页。日常维护在「译文数据」页：全库检索、行内改译文、单条删除、按搜索条件批量删除都在那里。

  • AI 上下文翻译：整站翻译是怎么做到的

    做多语言站点，常见的两条路：一是给每种语言复制一套文章，二是在前端挂个机器翻译脚本。前者内容一多就失控，后者译文不入库、搜索引擎也读不到。AI 上下文翻译走的是第三条：原文一个字不动，翻译发生在页面渲染完成之后，译文单独存表，前台按语言目录输出。

    一次翻译经过哪些步骤

    不论是后台点按钮、后台自动任务还是访客触发，走的都是同一条链路：

    1. 抓取原文页：插件用站内请求把目标页面完整取回来，带上标记参数，让前台知道这次要输出原文、不要参与替换。
    2. 解析 DOM 提取文本：整页 HTML 解析成 DOM 后逐节点提取，只取可见文字、<title>、部分 meta、placeholder、图片的 alt/title、Microdata 字段，以及（开关打开时）站内链接的路径。脚本、样式、类名、data-* 一律不碰。
    3. 分批送给 AI：以页面为单位组织请求，页内文本按字符数拆成多批，每批带上源语言、目标语言和一段 JSON。
    4. 入库：译文按「原文 md5 + 语言对」写进独立数据表，同一段文字在多个页面出现只存一份。
    5. 前台输出：访客打开 /ja/ 这样的语言目录时，插件在页面渲染完成后接管输出，把每个文本节点换成对应译文，站内链接挂到语言目录下。

    为什么按页面组织请求

    逐条翻译准确度会明显下降——「关于」在导航里和在正文里可以是两个词，脱离上下文的短句最容易翻错。插件把同一页的文本凑成一批交给 AI，模型能看到这些文字彼此的关系，译文的用词和语气才统一。

    批次不是越大越好。单批总长度控制在 6000 字符、最多 50 条，因为译文长度与原文相当，这个值实际上是在约束模型的输出长度。万一还是撞上模型的输出上限被截断，插件会把切断点之前完整的译文抢救出来，剩下的缩小规模重发，最多再拆四层。

    译文存在哪里

    独立的数据表，与文章内容无关。每条记录包含原文、译文、语言对、来源页面、类型（普通文本还是 URL 路径）和来源标记（AI 翻译还是人工修改过）。这样带来几个直接好处：

    • 全站去重。导航、页脚、按钮文字这些每页都出现的内容，只翻一次。
    • 停用插件不会动原文，站点立刻回到单语状态，数据还在。
    • 译文可以逐条人工校对，改过的会被标成人工来源，后续 AI 翻译不会把它覆盖掉。

    接哪些 AI 服务

    插件通过 php-ai 库对接模型，内置 OpenAI、Claude、Gemini、DeepSeek 四套协议。模型名可以直接填库里内置的（如 deepseek-chat、gpt-4o），平台由模型名自动识别；也可以填中转站自定的模型名，再手选协议格式、填上对方给的接口地址。自建网关、第三方中转都能接。

    下一篇讲具体怎么配：从零配置到第一篇译文。