AI 자동화로 다국어 번역 키 누락과 텍스트 가로 깨짐 검증하기

다국어 품질 문제는 번역 완료 여부만으로 끝나지 않습니다. 자동화 도구가 기준 언어와 대상 언어의 키 집합을 비교하면 누락 키와 빈 값을 찾을 수 있고, AI를 문맥상 위험한 긴 문장의 검토 우선순위 분류에 활용할 수도 있습니다. 키 집합 비교만으로 미사용 키를 찾을 수는 없습니다. 핵심은 정적 키 비교 → AI 위험도 분류 → 실제 해상도 렌더링 검사를 분리하는 것입니다.

다국어 번역 키 누락과 텍스트 깨짐은 왜 발생하는가?

번역 키 누락은 UI 프리팹이나 코드에 참조를 추가했지만 해당 String Table에 키가 없거나, 선택한 로케일의 번역 값이 비어 있을 때 생길 수 있습니다. Unity Localization의 로케일 폴백과 No Translation Found Format 설정에 따라 표시 결과가 달라지므로 키 이름이나 빈 문자열이 항상 표시된다고 가정하지 말고 프로젝트 설정과 실제 화면을 확인합니다.

텍스트 가로 깨짐은 문자열 길이만의 문제가 아닙니다. 독일어 복합어처럼 공백 없이 이어지는 긴 단어, 일본어·중국어의 줄바꿈 규칙, 숫자와 변수 치환이 섞인 문장은 같은 RectTransform 폭에서도 서로 다른 결과를 낼 수 있습니다. Unity UI TextMeshPro에서는 RectTransform.rect.width, 폰트 크기, 자동 크기 조절, 줄바꿈 규칙이 함께 영향을 줍니다.

문자열의 확장 비율은 기준 언어 대비 다음처럼 기록할 수 있습니다.

expansionRatio = \frac{targetTextLength}{sourceTextLength}

길이 단위는 기준·대상 문자열에서 동일하게 정해야 합니다. 이 비율은 검토 후보를 고르는 보조 지표일 뿐이며, 실제 판정은 대상 폰트와 UI 폭으로 렌더링한 결과를 사용해야 합니다.

AI 자동화 검증 파이프라인은 어떻게 구성할까?

AI는 누락 키의 최종 판정기가 아니라 검토 우선순위를 정하는 보조 도구로 두는 편이 안전합니다. 키 존재 여부와 오버플로는 결정적 규칙으로 검사하고 AI에는 문맥·변수·번역 길이 위험도를 맡깁니다.

flowchart LR
    A[기준 언어 CSV] --> B[키 집합 비교]
    C[대상 언어 CSV] --> B
    B --> D[누락·빈 값 리포트]
    C --> E[AI 위험도 분류]
    E --> F[고위험 문자열 목록]
    D --> G[Unity 배치 렌더링 검사]
    F --> G
    G --> H[CI 아티팩트와 실패 목록]

기준 언어와 대상 언어의 키를 정렬해 집합 차이를 계산합니다.
빈 번역, 변수 토큰 불일치, 확장 비율이 큰 문자열을 AI 검토 후보로 보냅니다.
후보를 실제 UI 프리팹과 목표 해상도에서 렌더링해 오버플로를 확정합니다.

기준 언어와 대상 언어의 키 차이 및 UI 오버플로 검사 화면을 표현한 개념 모형. 화면의 키, 검사 건수, CI 상태는 설명용 예시이며 실제 프로젝트의 결과가 아닙니다.

번역 키 누락은 어떻게 자동으로 찾을까?

CSV 또는 JSON을 빌드 산출물로 고정하고 기준 언어의 키를 계약으로 취급합니다. Unity Localization 1.4의 CSV 내보내기는 Key, Id, 로케일별 열을 사용하므로, 기본 CSV를 쓴다면 Key와 대상 로케일 열을 스크립트가 기대하는 key,text 열로 정규화하거나 CSV 열 매핑을 바꿉니다. 아래 Python 3.11 스크립트는 key,text 형식 CSV 두 개를 비교해 누락 키와 빈 번역을 실패 코드로 반환합니다.

from __future__ import annotations

import csv
import sys
from pathlib import Path


def load_rows(path: Path) -> dict[str, str]:
    with path.open(encoding="utf-8-sig", newline="") as file:
        return {row["key"]: row.get("text", "").strip() for row in csv.DictReader(file)}


source = load_rows(Path(sys.argv[1]))
target = load_rows(Path(sys.argv[2]))
missing = sorted(set(source) - set(target))
empty = sorted(key for key in source if key in target and not target[key])

for key in missing:
    print(f"MISSING_KEY: {key}")
for key in empty:
    print(f"EMPTY_TRANSLATION: {key}")

raise SystemExit(bool(missing or empty))

이 검사는 키 존재만 확인합니다. 기준 언어에 없는 대상 언어 전용 키는 즉시 오류로 단정하지 말고 플랫폼 전용 문구인지 별도 목록으로 관리해야 합니다.

변수 토큰도 함께 비교해야 하는 이유

프로젝트에서 사용하는 포맷터의 토큰(예: Unity Smart String의 {playerName}, .NET 복합 서식의 {0} 또는 printf 계열 서식의 %s)이 번역 과정에서 사라지면 키가 있어도 서식 오류나 잘못된 문장이 생길 수 있습니다. 이 표기법들은 서로 바꿔 쓸 수 없으므로 포맷터를 확인한 뒤 키 비교와 별도로 원문·번역문의 토큰 집합을 검사합니다.

검사 항목	결정적 검사	AI가 보조할 부분
키 존재	기준 키 집합과 대상 키 집합 비교	불필요
빈 번역	공백 제거 후 빈 문자열 판정	불필요
변수 토큰	정규식으로 토큰 집합 비교	문장 자연스러움 검토
긴 문자열	길이와 확장 비율 계산	UI 위험도와 문맥 분류
가로 깨짐	실제 렌더링 폭 측정	수정 우선순위 제안

텍스트 가로 깨짐은 어떻게 검증할까?

Unity 2022.3 LTS에서 제공되는 TextMeshPro 3.0.6의 TMP_Text.GetPreferredValues(string)은 제약 없는 텍스트의 자연 폭을 후보 선별에 사용할 수 있습니다. 아래 코드는 레이아웃 계산이 끝난 뒤 호출해야 합니다. 반환값은 자동 줄바꿈이 적용된 실제 프리팹의 가로 오버플로 판정과 같지 않으므로, 한 줄 폭이 컨테이너를 넘는 문자열을 렌더링 검사 후보로 표시하는 보조 신호입니다. 최종 판정은 프리팹을 실제 설정과 해상도로 렌더링해 확인합니다.

using TMPro;
using UnityEngine;

public static class TextWidthRiskCheck
{
    public static bool NeedsWidthReview(TMP_Text text)
    {
        var width = text.rectTransform.rect.width;
        var naturalSize = text.GetPreferredValues(text.text);
        return naturalSize.x > width;
    }
}

검사 대상은 모든 문자열이 아니라 플레이어가 즉시 읽는 화면부터 잡는 것이 효율적입니다.

버튼, 탭, 토스트, 상점 가격처럼 폭이 고정된 UI
동적 변수로 길이가 달라지는 퀘스트·보상 문구
모바일 가로·세로 해상도에서 레이아웃이 달라지는 화면
CJK 폰트 폴백이 적용되는 언어

독일어 버튼 문구의 오버플로 전후를 표현한 개념 모형. 화면에 보이는 Unity 편집기 UI와 선호 폭 수치는 설명용이며 실제 Unity 측정 결과가 아닙니다.

AI 자동화 도구는 어디까지 맡겨야 할까?

AI에는 다음과 같은 구조화된 입력을 제공합니다. 입력에는 키, 기준 문장, 대상 문장, 화면 이름, 컨테이너 폭, 확장 비율을 포함하고 출력은 JSON으로 제한합니다. 아래 값은 형식을 설명하는 예입니다. 두 문자열의 영문자·공백·기호 길이를 세고 {itemName} 토큰을 포함하면 27/20=1.35입니다.

{
  "key": "shop.purchase.confirm",
  "screen": "ShopConfirmDialog",
  "source": "Purchase {itemName}?",
  "target": "{itemName} wirklich kaufen?",
  "containerWidth": 280,
  "expansionRatio": 1.35
}

AI의 출력 항목은 risk를 low, medium, high로 제한하고 이유와 확인할 UI를 받으면 충분합니다. AI가 번역 키를 새로 만들거나 렌더링 성공 여부를 추측하게 두면 결과가 흔들립니다. 실제 실패 판정은 CSV 비교와 Unity 렌더링 검사에 남기고, Unity·폰트·해상도 등 렌더링 입력을 고정해야 같은 CI 환경에서 결과를 비교하기 쉽습니다.

CI에서 다국어 QA 실패를 운영 가능한 신호로 만드는 방법

GitHub Actions, Jenkins, TeamCity 등 어떤 CI를 쓰더라도 단계는 같습니다.

로컬라이제이션 CSV를 내보내고 키·빈 값·토큰 검사를 실행합니다.
변경된 문자열과 고위험 문자열만 AI 분류 대상으로 보냅니다.
Unity 배치 모드에서 주요 프리팹을 로드해 오버플로 결과와 스크린샷을 아티팩트로 저장합니다.

실패 메시지에는 언어, 키, 화면 이름, 예상 폭, 실제 측정 폭을 함께 남깁니다. de-DE / shop.purchase.confirm / ShopConfirmDialog / 280px / 318px처럼 한 줄에 재현 정보를 담으면 번역가와 클라이언트 개발자가 같은 원인을 빠르게 확인할 수 있습니다. 이 숫자는 실패 로그 형식을 보여 주는 가정 예시입니다.

자주 묻는 질문 (FAQ)

번역 키가 있는데도 빈 문구가 보이면 무엇을 확인해야 하나요?

대상 언어 값의 공백 여부, 로드한 테이블 이름, 키의 대소문자와 폴백 설정을 확인합니다. 테이블을 Addressables 원격 콘텐츠로 배포한다면 카탈로그와 테이블 콘텐츠가 갱신되었는지도 확인합니다.

문자열 길이 비율만으로 UI 깨짐을 막을 수 있나요?

아닙니다. 비율은 후보 선별용입니다. 폰트 글리프 폭, 줄바꿈, 폰트 크기, 컨테이너 폭이 달라 실제 렌더링 검사가 필요합니다.

AI가 번역 품질과 UI 품질을 모두 판정해도 되나요?

권장하지 않습니다. AI는 문맥상 위험도를 분류하고 키·토큰·오버플로의 최종 판정은 결정적 자동 검사로 처리해야 합니다.

정리

다국어 QA는 기준 키 비교, 변수 토큰 검사, 실제 UI 폭 검사를 각각 자동화하는 데서 시작할 수 있습니다. AI는 긴 문장과 문맥상 위험한 변경을 우선 검토하는 데 보조로 활용합니다. AI 분류가 모든 오버플로를 빠짐없이 찾는다고 볼 수는 없으므로, 같은 Unity·폰트·해상도 조건에서 주요 화면을 계속 렌더링 검사해야 합니다.