FinchUI 多语言网站翻译插件-如何检查翻译缓存是否生效

FinchUI 多语言网站插件会把正文翻译结果保存到本地文件。再次遇到相同的源文本和目标语言时，插件会直接读取缓存，不再请求第三方翻译接口。

正文翻译缓存目录：zb_users/cache/fui_multilang/汇率缓存目录：zb_users/cache/fui_multilang_currency/

一、查看缓存文件是否生成

访问一个启用了非默认语言、且含有待翻译文本的页面后，查看 zb_users/cache/fui_multilang/。目录会按目标语言和哈希前缀分层，例如：

fui_multilang/
└── en/
    └── ab/
        └── cd/
            └── abcdef...json

其中每个 .json 文件通常对应一段已成功翻译的文本，文件内容会包含翻译结果：

{
  "time": 1780000000,
  "text": "Translated text"
}

首次打开页面后出现新的 JSON 文件，说明翻译结果已经成功写入缓存。

二、用同一页面访问两次验证

1. 在插件后台清理翻译缓存。
2. 记录翻译服务商后台的请求次数或字符消耗。
3. 访问一个有中文正文的非默认语言页面，例如英文页面。
4. 确认缓存目录新增 JSON 文件，并再次记录翻译服务商的用量。
5. 再次访问完全相同的页面。

预期结果：第二次访问应直接命中本地缓存；在页面内容、目标语言和缓存有效期均未变化的前提下，翻译服务商的请求量或字符消耗不应继续增长。

三、如何理解空白哈希目录

当前版本只会在成功取得译文，或需要记录短期翻译失败状态时创建两级哈希目录，因此新产生的哈希目录应包含对应的 JSON 文件。

• 缓存读取、缓存未命中检查和首页待翻译片段预扫描只计算文件路径，不会创建语言或哈希目录。
• 翻译接口返回非空译文后，插件会写入正文翻译 JSON 文件。
• 翻译接口实际请求失败时，插件会写入短期 .fail.json 失败缓存，暂时避免重复请求；该文件到期后会自动重试。
• 旧版本遗留的空目录不会影响缓存命中，也不表示已成功缓存。

升级前已经存在的空目录可以保留或在确认没有缓存写入请求时清理；升级后，正常访问不应继续因为缓存未命中或片段上限而新增空哈希目录。接口实际失败时会写入短期失败缓存文件，而非留下空目录。

四、哪些情况需要进一步排查

若空目录持续快速增加，但对应语言页面始终没有生成 JSON 文件，或同一页面每次访问都持续增加翻译服务商用量，应检查：

• 翻译接口密钥、区域和签名配置是否正确。
• 插件后台的翻译接口测试是否成功。
• 服务器是否可以访问翻译服务商接口。
• 页面待翻译文本是否超过后台设置的单页翻译片段上限。
• 缓存目录及其上级目录是否具有 PHP 进程可写权限。
• 缓存有效期是否设得过短，或是否被频繁手动清理。

五、缓存有效期与文件时间

缓存有效期由后台的“翻译缓存天数”控制，默认值为 30 天。超过有效期的缓存文件会在后续读取或随机清理时失效并删除；下一次需要该文本时，才会重新调用翻译接口。

缓存命中时，插件最多每 6 小时刷新一次文件修改时间。因此短时间内连续访问同一页面，JSON 文件的修改时间不变也属于正常情况。

提示：若仅需要清理空目录，可在确认无正在写入缓存的请求后处理；但通过插件后台“清理翻译缓存”会同时清理有效 JSON 缓存，之后访问页面会重新产生翻译请求。