XUnity.AutoTranslator가 번역을 안 할 때

XUnity.AutoTranslator는 무료이고 MIT 라이선스이며 활발히 관리되는, Unity가 가진 최고의 런타임 번역 도구입니다. 게임이 텍스트 컴포넌트에 문자열을 건네는 순간에 후크를 걸어, 그려지기 전에 번역으로 바꿔치기하는 방식으로 작동합니다. 그 설계 덕분에 게임의 파일 형식을 전혀 몰라도 되고 — 동시에 그 때문에 실패할 때는 조용히 실패합니다. 아무것도 죽지 않습니다. 게임이 그냥 일본어로 돌아갑니다.

아래 다섯 가지가 "번역이 안 된다"는 제보의 거의 전부를 설명합니다. 순서대로 짚어 보세요. 각각 해결책이 다르고, 그 사이에서 찍어 맞추다 보면 저녁 시간이 통째로 날아갑니다.

먼저: 화면이 아니라 로그를 읽으세요

플러그인은 자기가 무엇을 하는지 시끄럽게 알리고, 그 말을 하는 곳은 로그뿐입니다. BepInEx로 설치했다면 BepInEx/LogOutput.log를 보세요. Unity 자체 로그는 그 옆에 있습니다 — 구버전 빌드는 <Game>_Data/output_log.txt, 최신 빌드는 %APPDATA%/../LocalLow/<Company>/<Game>/Player.log.

• 로그에 XUnity.AutoTranslator가 로드되었다는 말이 아예 없나요? 그렇다면 문제는 번역기가 아니라 로더이고, 실패 유형 1번입니다.
• 엔드포인트가 초기화되었다고 나오고, 나중에 반복된 오류 뒤에 하나가 종료되었다고 이름이 나오나요? 그건 실패 유형 5번입니다.
• 번역이 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를 파싱해 배치를 재구성하는 것뿐입니다. 그건 설정이 아니라 완전히 다른 로더입니다.

• 5초 만에 확인하는 법: 게임 실행 파일 옆에 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는 게터가 게임에 원본 문자열을 돌려주게 하면서, 플레이어에게는 번역된 쪽을 보여 줍니다. 읽을 때마다 비용이 들기 때문에 기본값이 꺼짐이며, 텍스트가 깜빡이거나 원래대로 돌아가거나 붙어 있지 않을 때 가장 먼저 켜 볼 스위치입니다.

이 범주의 나머지 절반은 애초에 후크된 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 텍스트 컴포넌트를 거치지 않는 것입니다 — 실패 유형 2번으로 돌아가세요.

4. 긴 줄은 번역되는 게 아니라 건너뛰어진다

MaxCharactersPerTranslation의 기본값은 200입니다. 그보다 긴 것은 건너뜁니다. 잘리지도, 재시도되지도, 플레이하면서 눈치챌 만한 방식으로 기록되지도 않습니다 — 그냥 건너뛰므로 그 줄은 원래 언어로 그려지고 아무것도 고장 나 보이지 않습니다.

사람들이 가장 오래 헤매는 실패 유형입니다. 증거가 너무 약하기 때문이죠. 게임 대부분은 번역되는데 문단 하나만 안 됩니다. 보통 희생되는 건 비주얼 노벨입니다 — 긴 서술 블록이나 줄바꿈 없는 독백은 200자를 쉽게 넘기고, 하필 가장 번역되기를 바랐던 텍스트가 그것입니다.

AutoTranslatorConfig.ini에서 값을 올리고 다시 시작하세요. 다만 요청 하나의 비용도 함께 올린다는 점을 기억하세요. 무료 엔드포인트에는 각자 요청당 길이 상한이 있어서, 그것을 넘는 요청부터 거절하기 시작합니다. 값을 아주 크게 잡으면 조용한 건너뜀을 눈에 보이는 엔드포인트 오류와 맞바꾸는 셈입니다. 보통의 비주얼 노벨 산문은 500~1000 사이면 덮입니다.

5. 엔드포인트가 실패했거나 속도 제한에 걸렸다

XUnity의 기본 엔드포인트는 브라우저가 접근하는 방식으로 접근하는 무료 공개 번역 서비스입니다. 계약된 것이 아니고, 바뀝니다. 요청이 연달아 실패하면 플러그인은 그것을 계속 두드리는 대신 남은 세션 동안 그 엔드포인트를 내려 버립니다 — 의도적이고 좋은 판단이지만, 동시에 그 시점 이후의 모든 것이 게임을 다시 시작할 때까지 조용히 번역되지 않은 채로 남는다는 뜻이기도 합니다.

• 로그에서 종료 줄을 확인하세요. 그 줄이 있다면 해법은 다시 시작 + 무언가를 바꾸는 것이지, 더 기다리는 게 아닙니다.
• 큐 속도를 늦추세요. MaxTranslationsQueuedPerSecond와 지연 설정이 존재하는 이유는 속도 제한을 건드리는 것이 바로 몰아치기이기 때문입니다. 비주얼 노벨을 빨리 감기로 넘기면 몇 초 만에 수백 건의 요청이 나갑니다.
• 엔드포인트를 바꾸세요. 무료 서비스 하나가 상태가 나쁜 날이어도, 보통 다른 하나는 멀쩡합니다.
• 키를 쓰는 엔드포인트를 쓰세요. 정식 DeepL이나 유료 API 키는 이 문제 범주를 통째로 없앱니다. 유료 API 키라는 대가를 치르고요.
• 플러그인을 업데이트하세요. 무료 엔드포인트의 프로토콜이 바뀌면 수정은 릴리스로 옵니다. 이미 옮겨 간 서비스에 2년 된 빌드를 물리는 것이 "예전엔 됐는데"의 흔한 원인입니다.

보너스: 번역은 되는데 네모로 그려진다

이건 번역 실패가 아예 아닙니다. 게임은 원래 언어에 필요한 글자만 정확히 담은 폰트 아틀라스를 함께 내보냈고, 여러분의 대상 언어에는 거기 없는 글자가 필요해서, 빠진 글자마다 네모나 빈칸으로 그려지는 것입니다. XUnity에는 바로 이걸 위한 OverrideFont와 OverrideFontTextMeshPro가 있습니다. 지문을 기억하세요: 네모는 글자가 없다는 뜻이고, 진짜 `?` 문자는 그 앞 어딘가의 인코딩 문제라는 뜻입니다. 서로 다른 버그이고, 폰트 설정은 앞의 것만 고칩니다.

짚어 나갈 순서

1. GameAssembly.dll이 있는지 보고 Mono인지 IL2CPP인지 확인한 다음, 거기에 맞는 로더를 설치했는지 확인하세요.
2. BepInEx/LogOutput.log를 열어 플러그인이 로드되었고 엔드포인트가 초기화되었는지 확인하세요.
3. 게임에서 ALT+0을 눌러 플러그인 자체 창을 여세요 — 아무것도 나타나지 않으면 플러그인이 로드되지 않은 것입니다. ALT+1은 Translation Aggregator를 엽니다. 비어 있으면 후크가 텍스트를 본 적이 없는 것이고, 채워져 있으면 보고 있는 것입니다.
4. 후크는 보고 있는데 화면이 바뀌지 않는다면 TextGetterCompatibilityMode를 켜세요.
5. 게임의 일부만 번역된다면 IMGUI와 레거시 TextMesh를 켜세요.
6. 특정 긴 줄만 번역되지 않는다면 MaxCharactersPerTranslation을 기본값 200에서 올리세요.
7. 세션 도중에 전부 멈췄다면 엔드포인트 종료 줄을 찾고, 큐를 늦추거나 다른 엔드포인트로 바꿔 다시 시작하세요.

후크가 그 일에 맞지 않는 모양일 때

위의 실패는 전부 같은 뿌리로 돌아갑니다. 런타임 후크는 자기가 가로챌 자리에 있는 텍스트만 번역할 수 있습니다. 게임이 플러그인이 아는 API로 문자열을 설정하지 않거나, 플러그인이 로드되기 전에 텍스트가 그려졌거나, 런타임이 후크할 메서드를 노출하지 않는다면 설정할 것이 없습니다. 도구는 제 일을 정확히 하고 있고, 텍스트가 그냥 손에 닿지 않는 곳에 있을 뿐입니다.

구조적인 대안은 프레임이 아니라 파일을 다루는 것입니다. 파일 수준 도구는 게임 자체의 에셋을 열어 문자열을 꺼내고, 번역하고, 번역된 게임 사본을 씁니다 — 그래서 엔진이 불러오기도 전에 텍스트가 이미 대상 언어로 되어 있습니다. 후크도, 가로챌 지점도, 프레임워크별 플래그도 없고, 글자 수 상한은 형식이 담을 수 있는 만큼입니다. RuneTranslate가 Unity와 그 외 16개 엔진·형식에서 하는 일이 그것입니다.

장단점은 실제로 존재하고 반대 방향으로 작용합니다. 파일 수준 도구는 파일 안에 있는 텍스트에만 닿습니다 — Unity라면 TextAsset, MonoBehaviour 문자열 필드, StreamingAssets 스크립트, 현지화 테이블, 그리고 AES로 암호화된 Addressable 번들을 포함한 에셋 번들입니다. 플레이하면서 번역하는 대신 플레이 전에 내보내기 단계가 필요합니다. 그리고 게임이 조각을 이어 붙여 런타임에 만들어 내는 텍스트에는 아무것도 할 수 없습니다. Unity가 최선 지원 엔진인 이유가 정확히 이것입니다. 어떤 게임이 무엇을 외부화하는지가 엄청나게 다르고, 어느 쪽인지는 프로젝트를 열어 봐야 알 수 있습니다.

• C# 코드에 컴파일된 텍스트가 딱딱한 경계선입니다. Mono 빌드에서는 RuneTranslate가 번들된 사이드카로 게임 어셈블리의 문자열 리터럴을 읽되, 호출 지점이 그 문자열로 무엇을 하는지에 따라 걸러 내므로 씬 이름이나 애니메이터 파라미터를 번역하는 일은 없습니다. IL2CPP 빌드에서는 컴파일된 코드가 범위 밖입니다.
• IL2CPP의 에셋 텍스트는 문제없습니다. 컴포넌트 문자열 필드는 게임 메타데이터에서 타입 정보를 재구성해 IL2CPP에서도 읽습니다 — 후크가 필요로 하는 바로 그 global-metadata.dat를, 다른 목적으로 쓰는 것입니다.
• XUnity 자신의 출력물을 읽습니다. 이미 채워진 _AutoGeneratedTranslations.txt가 있다면 RuneTranslate가 그 파일을 파싱해 값을 번역할 수 있고, 키는 건드리지 않습니다. 이미 해 둔 작업이 버려지지 않습니다.
• 폰트는 내보내기 때 처리됩니다. 게임에 폴백 폰트 에셋을 주입해, 원래 폰트가 한 번도 덮지 않았던 대상 언어도 렌더링되게 합니다.

제공자는 9종이고 그중 셋은 API 키가 전혀 필요 없습니다 — Google, 무료 DeepL, DeepL의 Classic / 차세대 모델 — 여기에 DeepL API, OpenAI, Anthropic, DeepSeek, 모든 OpenAI 호환 엔드포인트, 그리고 Ollama나 LM Studio를 통한 로컬 모델이 더해집니다. 무료 등급은 모든 엔진과 모든 제공자를 열어 주고, 처리량을 조절하며 한 번에 프로젝트 하나를 둡니다. Windows 10/11, 또는 Wine이나 Proton을 통한 Linux와 Steam Deck. 첫 실행 때 무료 Patreon 로그인이 필요합니다. 결과물은 여러분이 보관하는 플레이 가능한 번역 빌드입니다.

어느 접근도 언제나 옳지는 않습니다. 대본 전체가 번들된 JSON 테이블 하나에 들어 있는 게임은 처음부터 파일 수준의 일이었습니다. 대사를 런타임에 코드로 조립하는 게임은 앞으로도 후크의 일입니다. 지금 손에 든 것이 어느 쪽인지 아는 것이 일의 대부분입니다.

다음에 볼 것

• Unity 게임을 번역하는 방법 — Unity가 무엇을 외부화하고 무엇을 하지 않는지까지 담은 전체 안내.
• Unity 엔진 페이지 — 지원 형식과 현재의 한계를 한자리에.
• RuneTranslate vs XUnity.AutoTranslator — 두 접근을 나란히 놓고, 각각이 이기는 경우까지.
• 번역 제공자 고르기 — 어떤 번역 엔진이 일본어 산문을 잘 다루고, 어떤 것이 비용이 들지 않는지.
• 용어집 기본 — 대본 전체에 걸쳐 캐릭터 이름과 용어를 일관되게 유지하기.
• 지원되는 모든 엔진 — 알고 보니 Unity가 아니었을 때.