Topics

用 EmDash 建立多語言部落格的經驗 ~即使使用 SSR,也能降低翻譯 API 成本的方法~

  • column

我們的部落格「隨意記錄」最近偷偷推出了英文版。這次要分享的是背後的做法,特別是我們如何解決「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 進行翻譯,成本和使用者體驗都會崩壞。

解決方案:將翻譯時機從「請求時」移到「內容建立時」

答案很簡單:不在請求時進行翻譯。

具體來說,我們建立了以下的流程。

  1. 在 EmDash 的管理後台撰寫並發布日文文章
  2. 僅執行一次翻譯腳本(scripts/translate.mjs)
    • 從 EmDash 的 API 取得日文文章的 Portable Text(結構化的富文本內容)
    • 僅擷取需要翻譯的文字部分,並傳送至 Gemini API(gemini-3.6-flash)
    • 圖片與 Amazon 商品卡片等區塊不進行翻譯,直接保留原樣輸出
  3. 將翻譯結果以新的英文文章形式儲存至 EmDash 的資料庫
    • 指定原始日文文章的 ID 作為 translationOf,將其與同一文章群組的英文版本建立連結
    • 內容會以草稿形式儲存,可在審閱後再發布

也就是說,翻譯結果並非「即時生成的內容」,而是視為「已儲存於 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 年入職

查看此員工的文章

我們的優勢在於穩健的團隊體制與快速的應對能力

Liberogic 由經驗豐富的資深人員積極推動專案,因此獲得客戶的高度評價。
我們會妥善指派專案經理與總監,致力於順利推進整體專案。 我們採取依據專案需求適才適所分配資源的方式,避免因全程投入而增加不必要的成本,並且在掌握業務內容、製作與提交估價方面的速度也廣受好評。

注: 本公司不積極承接類似 SES 的駐點業務等,敬請事先諒解。

可搭配 Slack、Teams、Redmine、Backlog、Asana、Jira、Notion、Google Workspace、Zoom、Webex 等幾乎所有主要的專案管理工具與聊天工具使用。

歡迎諮詢您的 Web 相關問題。

案例分析