XUnity.AutoTranslator không dịch được

XUnity.AutoTranslator miễn phí, dùng giấy phép MIT, được bảo trì tích cực, và là công cụ dịch lúc chạy tốt nhất mà Unity có. Nó hoạt động bằng cách hook vào đúng lúc game đưa một chuỗi cho thành phần văn bản, rồi thay bằng bản dịch trước khi vẽ. Thiết kế đó giải thích vì sao nó không cần biết gì về định dạng file của game, và cũng là lý do khi nó hỏng thì hỏng trong im lặng. Không có gì sập. Game chỉ chạy bằng tiếng Nhật.

Năm điều dưới đây gói gần như mọi báo cáo kiểu “nó không dịch”. Hãy đi lần lượt theo thứ tự; mỗi điều có cách sửa khác nhau, và đoán mò giữa chúng tốn rất nhiều buổi tối.

Trước tiên: đọc log, đừng nhìn màn hình

Plugin nói khá nhiều về việc nó đang làm, và log là nơi duy nhất nó nói ra. Với bản cài BepInEx, hãy xem BepInEx/LogOutput.log. Log của chính Unity nằm cạnh đó ở <Game>_Data/output_log.txt trên các bản dựng cũ, hoặc %APPDATA%/../LocalLow/<Company>/<Game>/Player.log trên các bản mới hơn.

• Log có nhắc XUnity.AutoTranslator được nạp không? Nếu không, vấn đề nằm ở trình nạp chứ không phải trình dịch: bạn đang ở nguyên nhân số một.
• Nó có liệt kê một endpoint được khởi tạo, rồi sau đó nêu tên một endpoint bị tắt sau nhiều lỗi liên tiếp không? Đó là nguyên nhân số năm.
• Bản dịch có đang được ghi vào BepInEx/Translation/<lang>/Text/_AutoGeneratedTranslations.txt không? Nếu file đó đầy dần những bản dịch đúng mà không bao giờ hiện lên màn hình, phía mạng vẫn ổn còn phía hiển thị thì không.
• Nhấn ALT+1 trong game để mở cửa sổ Translation Aggregator. Nếu nó hiện các dòng bạn đang nhìn, hook có thấy chúng. Nếu nó vẫn trống, hook không bao giờ thấy.

Sự phân tách cuối cùng đó, “đã dịch nhưng không hiện” so với “không bao giờ thấy”, là ngã ba đường. Mọi thứ bên dưới đều rẽ ra từ đó.

1. Game là bản dựng IL2CPP

Unity phát hành game bằng hai runtime rất khác nhau. Mono giữ C# của game dưới dạng assembly .NET thông thường trong <Game>_Data/Managed/, trong đó có Assembly-CSharp.dll, với đầy đủ tên kiểu và tên phương thức. IL2CPP chuyển C# đó sang C++ từ trước và biên dịch thành một GameAssembly.dll gốc; phần còn lại của hệ thống kiểu được đóng gói trong <Game>_Data/il2cpp_data/Metadata/global-metadata.dat.

Một hook lúc chạy cần tìm một phương thức và thay thế nó. Trên Mono, đó là bài toán reflection bình thường. Trên IL2CPP không có phương thức managed nào để reflect: mã là mã gốc, và cách duy nhất để quay lại tên, trường và địa chỉ phương thức là phân tích global-metadata.dat rồi dựng lại bố cục. Đó là một trình nạp hoàn toàn khác, không phải một tùy chọn.

• Cách phân biệt trong năm giây: có GameAssembly.dll cạnh file exe của game, cùng thư mục il2cpp_data, nghĩa là IL2CPP. Thư mục Managed/ đầy DLL nghĩa là Mono.
• IL2CPP cần bản BepInEx dành cho IL2CPP, và bản phát hành XUnity.AutoTranslator tương ứng được dựng theo nó. Bản Mono sẽ không nạp được, nó đơn giản là không xuất hiện trong log, nhìn y như “plugin bị hỏng”.
• Độ rộng bit cũng quan trọng. Game 64-bit cần trình nạp 64-bit. Một cặp không khớp hỏng theo cùng kiểu im lặng.
• Một số game phát hành file metadata không phân tích được. Một số bản dựng cấu trúc lại global-metadata.dat, và mọi công cụ phụ thuộc vào việc đọc nó, kể cả hook, đều dừng ở đó.

2. Plugin đã nạp nhưng văn bản không bao giờ hiện

Plugin có trong log, endpoint đã khởi tạo, _AutoGeneratedTranslations.txt đang dài thêm, mà màn hình vẫn y nguyên. Hook đang dịch một chuỗi mà game sau đó vứt đi, hoặc game đang đặt văn bản qua một đường mà hook không chặn được.

TextGetterCompatibilityMode

Rất nhiều game đọc lại văn bản vừa đặt, để đo nó, nối thêm vào nó, hoặc so sánh với thứ khác. Khi thành phần đã giữ một chuỗi đã dịch, lần đọc lại đó trả về bản dịch, logic của chính game hoạt động trên văn bản mà nó không viết, và kết quả dao động từ một dòng bị trả về như cũ đến bố cục sụp đổ. TextGetterCompatibilityMode trong AutoTranslatorConfig.ini làm cho getter trả cho game chuỗi gốc của nó trong khi người chơi vẫn thấy bản dịch. Nó tắt theo mặc định vì tốn công ở mỗi lần đọc, và là công tắc đầu tiên nên thử khi chữ nhấp nháy, trả về như cũ, hoặc không chịu giữ.

Nửa còn lại của nhóm này là văn bản vốn không bao giờ được đặt qua API được hook: game vẽ bằng engine văn bản riêng, truyền ký tự thẳng vào mesh, hoặc nướng hội thoại vào sprite. Không có cấu hình nào cho trường hợp đó vì điểm chặn không tồn tại. Chữ nướng vào hình là một vấn đề hoàn toàn khác, cần dịch chữ trong ảnh chứ không phải hook nào.

3. Chỉ một phần văn bản được dịch

Menu dịch được, hội thoại thì không. Hoặc hội thoại dịch được còn mọi nút bấm vẫn là tiếng Nhật. Hầu như luôn là do một khung UI chưa được bật, vì plugin hook từng khung riêng và không phải khung nào cũng bật theo mặc định.

• Bật theo mặc định: UGUI (UI tích hợp sẵn của Unity), NGUI, TextMeshPro và UIElements (EnableUGUI, EnableNGUI, EnableTextMeshPro, EnableUIElements). Gộp lại, chúng bao phủ hầu hết game hiện đại, kể cả các khung visual novel như Utage, vốn vẽ qua chúng chứ không có công tắc riêng.
• Tắt theo mặc định: IMGUI và thành phần TextMesh cũ. IMGUI là GUI chế độ tức thời của Unity: nó vẽ lại mỗi khung hình, nên hook nó nghĩa là dịch ở mỗi khung hình, và nó bị tắt vì hiệu năng chứ không phải vì không chạy được.
• Các cờ nằm trong `AutoTranslatorConfig.ini` dưới dạng EnableIMGUI, EnableTextMesh và các mục tương tự. Đặt cái game của bạn dùng thành True rồi khởi động lại.
• Game Unity indie cũ và nhỏ hơn thường là trường hợp IMGUI. Game có menu trông như những hộp xám trơn với kiểu mặc định là một gợi ý mạnh.

Nếu bật hết mà không có gì thay đổi, văn bản hoàn toàn không đi qua một thành phần văn bản Unity nào: quay lại nguyên nhân số hai.

4. Dòng dài bị bỏ qua, không được dịch

MaxCharactersPerTranslation mặc định là 200. Bất cứ gì dài hơn đều bị bỏ qua. Không cắt ngắn, không thử lại, không ghi log theo cách bạn để ý khi đang chơi: chỉ bỏ qua, nên dòng hiện bằng ngôn ngữ gốc và không có gì trông như hỏng.

Đây là nguyên nhân người ta săn lùng lâu nhất, vì bằng chứng rất yếu: phần lớn game dịch được, rồi bỗng một đoạn thì không. Visual novel là nạn nhân thường gặp: một khối dẫn truyện dài hay một đoạn độc thoại không xuống dòng dễ dàng vượt 200 ký tự, và đó chính xác là văn bản bạn muốn dịch nhất.

Tăng giá trị này trong AutoTranslatorConfig.ini rồi khởi động lại. Lưu ý bạn cũng đang tăng cái giá của mỗi yêu cầu: các endpoint miễn phí có trần độ dài riêng cho mỗi yêu cầu và sẽ bắt đầu từ chối những yêu cầu vượt trần, nên giá trị quá lớn đổi một lần bỏ qua âm thầm lấy một lỗi endpoint hiện rõ. Khoảng 500-1000 là đủ cho văn xuôi VN thông thường.

5. Endpoint thất bại hoặc giới hạn tốc độ của bạn

Các endpoint mặc định của XUnity là dịch vụ dịch công cộng miễn phí, được truy cập theo cách một trình duyệt truy cập. Chúng không có cam kết và hay thay đổi. Khi một chuỗi yêu cầu thất bại liên tiếp, plugin tắt endpoint đó trong phần còn lại của phiên thay vì dội liên tục vào nó. Đó là quyết định đúng và có chủ ý, nhưng cũng có nghĩa mọi thứ sau thời điểm đó âm thầm không được dịch cho đến khi bạn khởi động lại game.

• Tìm dòng tắt endpoint trong log. Nếu có, cách sửa là khởi động lại cùng một thay đổi nào đó, không phải chờ thêm.
• Làm chậm hàng đợi. MaxTranslationsQueuedPerSecond và các cài đặt độ trễ tồn tại vì các đợt dồn dập là thứ kích hoạt giới hạn tốc độ. Tua nhanh một VN gửi hàng trăm yêu cầu trong vài giây.
• Đổi endpoint. Nếu một dịch vụ miễn phí đang có ngày tồi tệ, dịch vụ khác thường thì không.
• Dùng endpoint có khóa. Một khóa DeepL thật hoặc khóa API trả phí loại bỏ cả nhóm vấn đề này, đổi lại bạn phải có một khóa API trả phí.
• Cập nhật plugin. Khi giao thức của một endpoint miễn phí đổi, bản sửa đến dưới dạng một bản phát hành. Chạy bản dựng hai năm tuổi với dịch vụ đã đổi là nguyên nhân phổ biến của “trước đây nó chạy được”.

Thêm một điều: văn bản được dịch nhưng hiện thành ô vuông

Cái này hoàn toàn không phải lỗi dịch. Game phát hành một atlas phông chữ chứa đúng các glyph mà ngôn ngữ gốc cần, còn ngôn ngữ đích của bạn cần glyph không có trong đó, nên mỗi ký tự thiếu được vẽ thành ô vuông hoặc khoảng trống. XUnity có OverrideFont và OverrideFontTextMeshPro dành chính cho việc này. Hãy chú ý dấu hiệu: ô vuông nghĩa là thiếu glyph; ký tự `?` nguyên văn nghĩa là có vấn đề mã hóa ở đâu đó sớm hơn trong chuỗi xử lý. Chúng là hai lỗi khác nhau và cài đặt phông chữ chỉ sửa được lỗi đầu.

Thứ tự để xử lý

1. Xác nhận Mono hay IL2CPP bằng cách tìm GameAssembly.dll, và xác nhận bạn đã cài trình nạp tương ứng.
2. Mở BepInEx/LogOutput.log và xác nhận plugin đã nạp và một endpoint đã khởi tạo.
3. Nhấn ALT+0 trong game để mở cửa sổ riêng của plugin: nếu không có gì hiện ra thì plugin chưa được nạp. ALT+1 mở Translation Aggregator: trống nghĩa là hook không bao giờ thấy văn bản, có nội dung nghĩa là nó có thấy.
4. Nếu hook thấy nhưng màn hình không đổi, hãy bật TextGetterCompatibilityMode.
5. Nếu chỉ một phần game được dịch, hãy bật IMGUI và TextMesh cũ.
6. Nếu một số dòng dài cụ thể vẫn không được dịch, hãy tăng MaxCharactersPerTranslation từ mặc định 200.
7. Nếu mọi thứ dừng giữa phiên, hãy tìm dòng endpoint bị tắt, rồi khởi động lại với hàng đợi chậm hơn hoặc endpoint khác.

Khi hook sai hình dạng cho công việc

Mọi lỗi ở trên đều quy về cùng một gốc: hook lúc chạy chỉ dịch được văn bản mà nó có mặt để chặn. Nếu game không đặt chuỗi qua một API mà plugin biết, hoặc văn bản được vẽ trước khi plugin nạp, hoặc runtime không để lộ phương thức để hook, thì không có gì để cấu hình. Công cụ đang làm đúng việc của nó và văn bản đơn giản nằm ngoài tầm với.

Phương án mang tính cấu trúc là làm việc trên file thay vì trên khung hình. Công cụ cấp file mở các asset của chính game, lấy chuỗi ra, dịch, và ghi một bản sao đã dịch của game, nên văn bản đã ở ngôn ngữ đích trước khi engine nạp nó. Không hook, không điểm chặn, không cờ theo từng khung, và giới hạn ký tự là bất cứ thứ gì định dạng cho phép. Đó là việc RuneTranslate làm, trên Unity và 17 engine cùng định dạng khác.

Các đánh đổi là có thật và đi theo hướng ngược lại. Công cụ cấp file chỉ với tới văn bản nằm trong các file: với Unity, đó là TextAsset, trường chuỗi MonoBehaviour, kịch bản StreamingAssets, bảng bản địa hóa và asset bundle, kể cả các bundle Addressable đóng gói. Nó cần một bước xuất trước khi chơi, thay vì dịch ngay khi chơi. Và nó không làm gì được với văn bản mà game của bạn tạo ra lúc chạy từ các mảnh ghép. Điều này đặc biệt đáng nói với Unity: thứ mà một game cụ thể giữ trong file khác nhau rất nhiều, và việc mở dự án mới cho bạn biết mình có cái nào.

• Văn bản biên dịch vào mã C# là ranh giới cứng. Trên bản dựng Mono, RuneTranslate đọc các chuỗi literal từ assembly của game bằng một sidecar kèm sẵn, có điều kiện dựa trên cách vị trí gọi dùng chúng, để không bao giờ dịch tên cảnh hay tham số animator. Trên bản dựng IL2CPP, mã đã biên dịch nằm ngoài phạm vi.
• Văn bản asset IL2CPP thì ổn. Các trường chuỗi của thành phần được đọc trên IL2CPP bằng cách dựng lại thông tin kiểu từ metadata của game, chính global-metadata.dat mà hook cần, dùng cho mục đích khác.
• Nó đọc được đầu ra của chính XUnity. Nếu bạn đã có sẵn _AutoGeneratedTranslations.txt đầy nội dung, RuneTranslate phân tích file đó và dịch được các giá trị trong đó, khóa giữ nguyên. Công sức bạn đã bỏ ra không bị vứt đi.
• Phông chữ được xử lý khi xuất, bằng cách chèn một asset phông chữ dự phòng vào game để ngôn ngữ đích mà phông chữ gốc chưa từng bao phủ vẫn hiển thị được.

Mười một nhà cung cấp, trong đó bốn nhà hoàn toàn không cần khóa API (Google, DeepL miễn phí, các mô hình Classic/Next-gen của DeepL và Gemini Nano chạy ngay trên PC của bạn qua Chrome), cùng DeepL API, OpenAI, Anthropic, DeepSeek, bất kỳ endpoint tương thích OpenAI nào, một mô hình cục bộ qua Ollama hoặc LM Studio, và RuneLingua, dịch AI do chúng tôi làm, ở các gói trả phí. Gói Miễn phí mở khóa mọi engine và mọi nhà cung cấp trừ RuneLingua; nó giới hạn tốc độ xử lý và cho giữ một dự án mỗi lần. Chạy trên Windows 10/11, hoặc chạy gốc trên Linux và Steam Deck. Lần mở đầu tiên cần đăng nhập miễn phí (Patreon, Google hoặc email). Đầu ra là một bản dựng đã dịch chơi được mà bạn giữ.

Không cách nào đúng cho mọi trường hợp. Một game có toàn bộ kịch bản nằm trong một bảng JSON đóng gói là việc của công cụ cấp file, và luôn là vậy. Một game ghép hội thoại bằng mã lúc chạy là việc của hook, và luôn sẽ là vậy. Biết mình đang cầm cái nào là phần lớn công việc.

Đi tiếp đâu

• Cách dịch game Unity: hướng dẫn đầy đủ, gồm những gì Unity đưa ra ngoài file và những gì không.
• Trang engine Unity: các định dạng được hỗ trợ và giới hạn hiện tại ở một chỗ.
• RuneTranslate so với XUnity.AutoTranslator: hai cách tiếp cận cạnh nhau, kèm các trường hợp mỗi bên thắng.
• Chọn nhà cung cấp dịch: nhà nào xử lý văn xuôi tiếng Nhật tốt, và nhà nào không tốn đồng nào.
• Kiến thức cơ bản về bảng thuật ngữ: giữ tên nhân vật và thuật ngữ nhất quán trên cả một kịch bản.
• Tất cả engine được hỗ trợ: nếu rốt cuộc game không phải Unity.