我們的部落格「隨意記錄」最近偷偷推出了英文版。這次要分享的是背後的做法,特別是我們如何解決「SSR 網站做多語言化時,API 成本會不會失控?」這個問題。
前提:我們使用的是 EmDash CMS
這個部落格是以基於 Astro 的 CMS「EmDash」運作。在管理後台撰寫文章,前端則使用 Astro 進行伺服器端渲染(SSR)的架構。
直覺式的操作方式與 WordPress 相似,也有人稱它為「WordPress 的精神續作」。
EmDash 原本就內建「多語言內容」功能,可以針對每個語言,分別儲存文章、頁面、選單以及分類法(分類與標籤)等記錄。只要在 translationOf 欄位中指定「這篇英文文章是此篇日文文章的翻譯」,系統就會將兩者視為同一篇文章的不同語言版本。
從 microCMS 遷移至 EmDash + Cloudflare 的紀錄
說到多語言化,如果是 SSG 的話其實很簡單
一般來說,若要「以 API 自動化多語言翻譯」,採用 SSG(靜態網站生成)的話,事情就會變得簡單許多。
- 於建置時只呼叫一次翻譯 API
- 將結果快取為靜態檔案
- 之後只需提供該 HTML 即可
因此,無論文章數量增加多少,API 費用都只會在「每次建置」時產生。頻率也容易控制,快取機制也很單純。
但 ゆるろぐ 是 SSR,那每次請求都要呼叫 API 嗎?
問題就在這裡。依照規格,EmDash 的 CMS 頁面全部都以 SSR(output: "server")進行渲染。這並非在靜態建置時產生頁面的方式,而是每次收到請求時,都從 CMS 的 API 與資料庫取得最新內容再進行描繪的機制。
那麼,如果採用「顯示英文頁面時,當場請 Gemini 翻譯後輸出」這種單純的實作,會發生什麼事呢?
- 每次請求都會產生翻譯 API 費用
- 延遲也會增加(必須等待 LLM 的回應)
- 同一篇文章每次翻譯結果都可能略有不同(缺乏可重現性)
這種做法完全行不通。即使是 SSR,若每次請求都呼叫 API 進行翻譯,成本和使用者體驗都會崩壞。
解決方案:將翻譯時機從「請求時」移到「內容建立時」
答案很簡單:不在請求時進行翻譯。
具體來說,我們建立了以下的流程。
- 在 EmDash 的管理後台撰寫並發布日文文章
- 僅執行一次翻譯腳本(
scripts/translate.mjs)- 從 EmDash 的 API 取得日文文章的 Portable Text(結構化的富文本內容)
- 僅擷取需要翻譯的文字部分,並傳送至 Gemini API(
gemini-3.6-flash) - 圖片與 Amazon 商品卡片等區塊不進行翻譯,直接保留原樣輸出
- 將翻譯結果以新的英文文章形式儲存至 EmDash 的資料庫
- 指定原始日文文章的 ID 作為
translationOf,將其與同一文章群組的英文版本建立連結 - 內容會以草稿形式儲存,可在審閱後再發布
- 指定原始日文文章的 ID 作為
也就是說,翻譯結果並非「即時生成的內容」,而是視為「已儲存於 CMS 中的另一種語言內容」來處理。
如此一來,SSR 的請求處理本身與平時的文章顯示並無不同。只需透過 EmDash 一般的多語系查詢(getEmDashEntry(..., { locale: "en" })),即可從資料庫取出已儲存的英文內容。呼叫 Gemini API 的通信只會在翻譯文章的那一次進行,瀏覽時完全不會發生。
整體架構如下
翻譯執行時機 | 請求時的 API 成本 | |
|---|---|---|
SSG + 即時翻譯 | 建置時 | 零(靜態檔案發布) |
SSR + 每次翻譯(反面案例) | 每次請求 | 文章數 × 造訪數的次數都會發生 😱 |
SSR + 將預先翻譯結果儲存於 DB(本次採用的方式) | 建立內容時(1 次) | 零 |
若要把 SSG「在建置時一併快取」的概念帶進 SSR 的世界,替代方案就是「將翻譯完成的內容持久化保存在 DB 中」,這是本次的心得。即使是 SSR,內容本身也不是持續動態生成,只要事先完成翻譯這項「沉重的處理」,實際提供服務的部分就與一般 CMS 頁面一樣輕量。
本機與正式環境的 DB 不同,多次遇到「咦,東西不見了!?」的情況
這次實作中,最消耗心力的其實就是這件事。EmDash 在本機開發環境與正式環境各自擁有獨立的 DB。這話說來理所當然,但也因此,我多次遇到「剛才明明還在的功能不見了!」的狀況。
症狀大致如下
- 頁首的 nav 突然變成空的
- footer 的 Categories 清單消失了
- 文章頁面的側邊欄小工具消失了
- 明明剛設定好的本機選單項目和小工具又回到原本的狀態
而且所有狀況都是在「剛才還正常運作」的時間點發生,因此一開始我懷疑是「是不是我自己弄壞了什麼?」,一邊懷疑一邊找原因。
原因 1:將正式環境資料庫匯入本機的處理(pull.sh)
開發期間,為了「想在本機也看到正式環境的最新資料」,我曾多次執行將正式環境資料庫整個匯入本機的腳本。執行後,本機資料庫會被完全覆寫為正式環境的狀態(也就是英文文章仍是草稿,或選單結構尚未完成發布前的版本)。
也就是說,即使想在本機確認「正式環境尚未公開的功能」,只要剛執行完 pull,本機就會恢復成與正式環境相同的狀態,導致原本只在本機推進的作業暫時看不見,這種情況就這樣發生了。
原因 2:每次重新登入本機管理後台都會執行的「種子資料」處理
另一個原因是,為了重新登入本機管理後台而使用的機制(開發用的略過登入功能),會順便每次重新讀取 seed.json(初始資料定義檔)。
這點很麻煩,
- 選單項目與小工具 → 會被種子端的內容「完全覆寫、保持一致」(也就是說,在本機手動新增的部分會被刪除)
- 分類、標籤等分類法(taxonomy) → 「已存在的項目會略過」,因此不會被刪除
也就是說,這個功能會依項目而有不同的行為。因此會出現「分類還保留著,但選單和小工具每次都被刪除」這種乍看之下難以理解的現象。
我採取的因應做法
要從根本上消除這種雙重覆寫結構(pull 造成的覆寫,以及種子造成的覆寫)並不容易,因此作為務實的折衷方案,
- 將
seed.json中的示範用虛擬內容(選單項目、小工具、分類等)全部清空 - 每次重新進入本機環境時,都改為透過 API 重新建立所需的選單與小工具
。這並非根治,而是緩解措施,但至少能避免「被非預期的示範資料覆寫」這類意外發生。
總結
- EmDash 原本就是支援多語系的 CMS,能依語系分別管理內容
- 若是 SSG,只要「建置時翻譯→快取」即可,但若是 SSR,「每次都翻譯」就會讓費用失控。
- 解決方法是在內容建立時,而非請求時,只執行一次翻譯,並將結果以一般 CMS 內容的形式儲存到資料庫中。
- 本次使用的翻譯引擎是 Gemini API(
gemini-3.6-flash)。 - 不過,將 CMS 多語系化時,光是整理翻譯流程還不夠,也別忘了「本機與正式環境的資料庫分開」本身就會產生新的陷阱。
- 尤其是那種「在本機預先處理正式環境尚未存在的狀態」的開發方式,很容易受到環境同步機制(pull、seed、快取等)副作用的影響。
這次的教訓是:只要事先掌握「何時進行翻譯」以及「環境同步何時、會覆寫哪些內容」這兩項時機設計,即使是 SSR,也能在不受營運成本與意外事故困擾的情況下完成多語系支援。
您的網站也來試試多語系化吧!
主要以標記(markup)為核心,並使用 JavaScript、React 與 Next.js 進行前端開發。若我參與的網站能順利上線,我會非常開心!興趣是彈吉他。喜歡貓咪和烤地瓜🐱🍠
Hirattch
前端工程師 / 2022 年入職