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 缓存，之後访問頁面會重新產生翻译请求。