unity · xunity-autotranslator · troubleshooting
XUnity.AutoTranslator 不翻譯怎麼辦
XUnity.AutoTranslator 是 Unity 上最好的執行階段翻譯工具,而當它安靜下來時,原因幾乎總是這五件具體的事之一:遊戲是 IL2CPP 建置版本、文字是透過掛鉤攔不到的路徑設定的、負責繪製它的 UI 框架沒有啟用、這一行超過了字元上限,或者端點把自己關掉了。下面講怎麼判斷你碰上的是哪一種。
XUnity.AutoTranslator 是免費的、MIT 授權的、持續維護的,也是 Unity 上最好的執行階段翻譯工具。它的運作方式,是掛鉤遊戲把一條字串交給文字元件的那一刻,在它被畫出來之前換成譯文。這個設計正是它完全不需要了解遊戲檔案格式的原因,同樣也是它失敗時會悄悄地失敗的原因。什麼都不會當機。遊戲就是照舊跑日文。
下面這五件事幾乎解釋了每一份「它不翻譯」的回報。依序逐條排查;每一條的修法都不一樣,在它們之間亂猜只會白白耗掉很多個晚上。
第一步:看紀錄檔,不要看畫面
外掛對自己在做什麼很坦白,而紀錄檔是它唯一開口說話的地方。以 BepInEx 安裝時,看 BepInEx/LogOutput.log。Unity 自己的紀錄檔就在旁邊:較舊的建置版本在 <Game>_Data/output_log.txt,較新的在 %APPDATA%/../LocalLow/<Company>/<Game>/Player.log。
- 紀錄檔裡到底有沒有提到 XUnity.AutoTranslator 被載入?如果沒有,問題出在載入器,而不是翻譯器,你碰上的是失敗模式一。
- 它有沒有列出某個端點已初始化,而後又提到某個端點在反覆出錯之後被關閉?那是失敗模式五。
- 譯文有沒有被寫進
BepInEx/Translation/<lang>/Text/_AutoGeneratedTranslations.txt?如果那個檔案正被正確的譯文填滿,畫面上卻從來看不到,那麼網路那一側是好的,顯示那一側不是。 - 在遊戲裡按 ALT+1 開啟翻譯彙總視窗。如果它顯示出你正盯著的那些行,表示掛鉤看得見它們。如果它一直是空的,表示掛鉤從來沒看見過它們。
最後那個分岔,也就是「翻譯了但沒顯示」對比「從來沒被看見」,就是路口。下面的一切都取決於它。
1. 遊戲是 IL2CPP 建置版本
Unity 以兩種非常不同的執行階段發行遊戲。Mono 把遊戲的 C# 保留成 <Game>_Data/Managed/ 裡普通的 .NET 組件,Assembly-CSharp.dll 也在其中,型別名稱和方法名稱都完整保留。IL2CPP 則提前把那些 C# 轉成 C++ 並編譯進一個原生的 GameAssembly.dll;型別系統裡存活下來的部分被封裝進 <Game>_Data/il2cpp_data/Metadata/global-metadata.dat。
執行階段掛鉤需要找到一個方法並把它替換掉。在 Mono 上這是普通的反射問題。在 IL2CPP 上根本沒有受管理的方法可供反射,程式碼是原生的,要回到名稱、欄位和方法位址,唯一的辦法是解析 global-metadata.dat 並重建配置。那是一個完全不同的載入器,不是一個設定項目。
- 五秒鐘判斷法:遊戲 exe 旁邊有
GameAssembly.dll,外加一個il2cpp_data資料夾,就是 IL2CPP。一個裝滿 DLL 的Managed/資料夾就是 Mono。 - IL2CPP 需要 IL2CPP 版的 BepInEx,以及針對它建置的那一版 XUnity.AutoTranslator。Mono 版根本不會載入,它只是不出現在紀錄檔裡,而這看起來和「外掛壞了」一模一樣。
- 位元數也要對。 64 位元遊戲需要 64 位元載入器。配錯的一對會以同樣安靜的方式失敗。
- 有些遊戲發行的中繼資料檔案無法解析。 有些建置版本會重新排列
global-metadata.dat,而每一個依賴讀取它的工具,包括這個掛鉤,都會卡在這裡。
2. 外掛載入了,文字卻從來不出現
外掛在紀錄檔裡,端點初始化了,_AutoGeneratedTranslations.txt 也在變長,畫面卻沒變。要嘛是掛鉤翻譯的是一條遊戲隨後丟掉的字串,要嘛是遊戲透過掛鉤攔截不到的路徑來設定文字。
TextGetterCompatibilityMode
有不少遊戲會回讀自己剛設定的文字,為了測量它、往後追加,或是拿它跟別的東西比較。一旦元件裡裝的是譯文,這次回讀回傳的就是譯文,遊戲自己的邏輯於是在一段它沒寫過的文字上運作,結果從一行文字被還原,到整個版面崩壞都有可能。AutoTranslatorConfig.ini 裡的 TextGetterCompatibilityMode 會讓 getter 把原始字串還給遊戲,而玩家看到的仍然是譯文。它預設關閉,因為每一次讀取都要為它付出代價;當文字閃爍、被還原,或怎麼都留不住時,它是第一個該試的開關。
這一類的另一半,是文字壓根就不經過任何被掛鉤的 API:遊戲用自己的文字引擎繪製、直接把字元串流進一個網格,或是把對話烘焙進圖片。那種情況沒有設定可言,因為攔截點根本不存在。畫進美術圖裡的文字則完全是另一個問題,需要的是圖片文字翻譯,而不是任何掛鉤。
3. 只有一部分文字被翻譯
選單翻了,對話沒翻。或者對話翻了,每一個按鈕還是日文。這幾乎總是某個 UI 框架沒被啟用,因為外掛對每一個框架分別掛鉤,而它們並非全都預設開啟。
- 預設開啟: UGUI(Unity 內建 UI)、NGUI、TextMeshPro 和 UIElements(
EnableUGUI、EnableNGUI、EnableTextMeshPro、EnableUIElements)。它們加起來涵蓋了大多數新式遊戲,也包括 Utage 這類視覺小說框架,它們本身沒有自己的開關,而是透過上面這些框架來繪製。 - 預設關閉: IMGUI 和舊版
TextMesh元件。IMGUI 是 Unity 的立即模式 GUI,它每一幀都重繪,所以掛鉤它代表每一幀都要翻譯,它被停用是出於效能考量,而不是因為它不管用。 - 這些開關位於 `AutoTranslatorConfig.ini` 裡,名稱是
EnableIMGUI、EnableTextMesh等等。把你的遊戲用到的那一個設成True,然後重新啟動。 - 較舊的遊戲和較小的獨立 Unity 作品是 IMGUI 的常客。 如果一款遊戲的選單看起來就是一堆預設樣式的灰色方框,那是很強的線索。
如果全部啟用之後什麼都沒變,那麼這些文字根本不是經由 Unity 文字元件出來的,回到失敗模式二。
4. 長行是被略過,不是被翻譯
MaxCharactersPerTranslation 預設是 200。任何更長的都會被略過。不是截斷,不是重試,也不是以你玩著玩著能注意到的方式記進紀錄檔,就是略過,於是那一行以原本的語言繪製,而且看不出哪裡壞了。
這是人們找得最久的一種失敗模式,因為證據太薄弱:遊戲大部分都翻了,然後有那麼一段沒翻。視覺小說是常見的受害者,一大段旁白,或是中間沒有換行的一段獨白,輕輕鬆鬆就超過 200 字元,而那恰恰是你最想讀到譯文的地方。
在 AutoTranslatorConfig.ini 裡把這個值調高,然後重新啟動。要記得你同時也在抬高每一次請求的成本:免費端點各自有每次請求的長度上限,會開始拒絕單條超出上限的請求,所以一個非常大的值,等於用一次安靜的略過換來一個明顯的端點錯誤。500-1000 之間的某個值,足以涵蓋一般 VN 的文風。
5. 端點失敗了,或是對你限速了
XUnity 的預設端點是一些免費的公開翻譯服務,存取方式和瀏覽器存取它們的方式一樣。它們沒有任何契約保障,而且會變動。當一連串請求接連失敗時,外掛會在本次工作階段剩下的時間裡把那個端點關掉,而不是繼續猛敲,這是個有意為之的好決定,但也代表從那一刻起,一切都會安靜地維持未翻譯狀態,直到你重新啟動遊戲。
- 在紀錄檔裡找那行關閉記錄。 如果它在,那麼修法是重新啟動外加改點什麼,而不是繼續等。
- 把佇列放慢。
MaxTranslationsQueuedPerSecond和那些延遲設定之所以存在,是因為觸發限速的正是突發流量。在 VN 裡快轉,幾秒鐘就能送出幾百條請求。 - 換個端點。 如果某個免費服務今天狀態不好,另一個通常沒事。
- 使用帶金鑰的端點。 一把真正的 DeepL 或付費 API 金鑰能消除這一整類問題,代價是它是一把付費的 API 金鑰。
- 更新外掛。 當某個免費端點的通訊協定改變時,修正是以新版本的形式到來的。拿一個兩年前的建置版本去連一個已經改過的服務,是「以前明明能用」的常見原因。
附加:文字翻譯了,卻繪製成方塊
這一條根本不是翻譯失敗。遊戲發行時帶的字型圖集,只包含它原本語言需要的那些字形,而你的目標語言需要的字形不在裡面,於是每一個缺少的字元都畫成一個方塊或空白。XUnity 正是為此提供了 OverrideFont 和 OverrideFontTextMeshPro。請注意這個指紋:方塊代表缺字形;字面的 `?` 字元代表鏈條更早處的編碼問題。它們是不同的 bug,而字型設定只修得了前一個。
該依什麼順序排查
- 找
GameAssembly.dll來確認是 Mono 還是 IL2CPP,並確認你裝的是對應的載入器。 - 打開
BepInEx/LogOutput.log,確認外掛載入了、端點初始化了。 - 在遊戲裡按 ALT+0 開啟外掛自己的視窗,什麼都沒出現,表示外掛沒載入。ALT+1 開啟 Translation Aggregator:空的表示掛鉤從沒看見那些文字,有內容表示它看見了。
- 如果掛鉤看得見、畫面卻不變,開啟
TextGetterCompatibilityMode。 - 如果只有一部分遊戲內容被翻譯,啟用 IMGUI 和舊版 TextMesh。
- 如果是特定的長行一直沒翻,把
MaxCharactersPerTranslation從預設的 200 調高。 - 如果是玩到一半全都停了,找那行端點關閉記錄,然後用較慢的佇列或另一個端點重新啟動。
什麼時候掛鉤這條路本身就不對
上面每一種失敗都能追溯到同一個根源:執行階段掛鉤只能翻譯它在場攔截得到的文字。如果遊戲不是透過外掛認得的 API 來設定字串,或者文字在外掛載入之前就畫出來了,或者執行階段根本沒有暴露可掛鉤的方法,那就沒有什麼可以設定的。工具正在正確地做它該做的事,文字只是碰不到。
結構上的另一條路,是去處理檔案,而不是處理畫面。檔案層級的工具會打開遊戲自己的素材,把字串拉出來、翻譯掉,再寫出一份翻譯好的遊戲副本,於是在引擎載入之前,文字已經是目標語言了。沒有掛鉤,沒有攔截點,沒有逐框架的開關,字元上限就是格式本身能裝下的量。這正是 RuneTranslate 在 Unity 以及另外 17 種引擎和格式上所做的事。
取捨是真實存在的,而且方向相反。檔案層級的工具只碰得到在檔案裡的文字,對 Unity 而言,這代表 TextAsset、MonoBehaviour 字串欄位、StreamingAssets 腳本、在地化表和素材包,包括已封裝的 Addressable 素材包。它需要在你開玩之前先做一步匯出,而不是邊玩邊翻。而且對於遊戲在執行階段用碎片拼出來的文字,它無能為力。這一點在 Unity 上尤其重要:不同遊戲放在檔案裡的內容多寡差別極大,而開啟專案這一步,會告訴你手上是哪一種。
- 編譯進 C# 程式碼裡的文字是那條硬邊界。在 Mono 建置版本上,RuneTranslate 用隨附的附屬程式從遊戲組件裡讀出字串常值,並依呼叫處拿它做什麼來把關,所以它絕不會去翻譯場景名稱或動畫參數。在 IL2CPP 建置版本上,編譯過的程式碼不在範圍內。
- 不過 IL2CPP 的素材文字沒問題。 元件字串欄位在 IL2CPP 上是透過從遊戲中繼資料重建型別資訊來讀取的,用的正是掛鉤需要的那個
global-metadata.dat,只是用途不同。 - 它讀得懂 XUnity 自己的輸出。 如果你已經有一個填好的
_AutoGeneratedTranslations.txt,RuneTranslate 會解析那個檔案,並可以翻譯裡面的值,鍵原封不動。你已經做過的工作不會被丟掉。 - 字型在匯出時處理,辦法是往遊戲裡注入一個備用字型素材,讓原字型從未涵蓋過的目標語言也能繪製出來。
十二個翻譯服務,其中五個完全不需要 API 金鑰(Google、免費 DeepL、DeepL 的 Classic / Next-gen 模型、Yandex Translate,以及透過 Chrome 在你自己的 PC 上執行的 Gemini Nano),另外還有 DeepL 的 API、OpenAI、Anthropic、DeepSeek、任何與 OpenAI 相容的端點、透過 Ollama 或 LM Studio 執行的本機模型,以及付費方案裡我們自己的翻譯服務 RuneLingua。免費方案解鎖每一種引擎和除了 RuneLingua 以外的每一個翻譯服務;它限制的是處理量,並且同時只持有一個專案。支援 Windows 10/11,或在 Linux 和 Steam Deck 上原生執行。第一次啟動需要一次免費登入(Patreon、Google 或電子郵件)。產出是一份歸你保留、可直接遊玩的翻譯建置版本。
兩種做法都不是普遍正確的。一款整個劇本都放在一張已封裝 JSON 表裡的遊戲,本來就是檔案層級的工作。一款在執行階段用程式碼拼出對話的遊戲,本來也永遠是掛鉤的工作。分清楚你手上是哪一種,就是這件事的大半。
接下來看什麼
- 如何翻譯 Unity 遊戲:完整走一遍,包括 Unity 會外部化什麼、不會外部化什麼。
- Unity 引擎頁面:支援的格式和目前的限制,都在一處。
- RuneTranslate 對比 XUnity.AutoTranslator:兩種做法並排放,以及各自勝出的場景。
- 怎麼挑翻譯服務:哪些翻譯服務擅長處理日文文風,哪些一毛錢都不用花。
- 詞彙表入門:讓角色名稱和術語在整個劇本裡保持一致。
- 全部支援的引擎:萬一這款遊戲最後根本不是 Unity。
準備好試用 RuneTranslate 了嗎?
免費方案即可解鎖全部引擎 + 除 RuneLingua 外的全部翻譯供應商。Supporter($3.99/mo)解鎖全速翻譯。
下載 Windows、Mac 和 Linux 版
