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

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

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

번역 키 누락은 보통 UI 프리팹에 새 키를 추가한 뒤 로컬라이제이션 테이블 반영이 늦거나 대상 언어 행이 비어 있을 때 발생합니다. 런타임에서는 키 이름이 그대로 표시되거나 빈 문자열이 출력될 수 있습니다.

텍스트 가로 깨짐은 문자열 길이만의 문제가 아닙니다. 독일어·러시아어처럼 단어가 길어지는 언어, 줄바꿈이 적은 일본어·중국어, 숫자와 변수 치환이 섞인 문장은 같은 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 오버플로 검사 결과를 보여주는 QA 대시보드

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

CSV 또는 JSON을 빌드 산출물로 고정하고 기준 언어의 키를 계약으로 취급합니다. 아래 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))

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

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

{playerName}, {0}, %s 같은 토큰이 번역 과정에서 사라지면 키는 존재해도 런타임 오류나 잘못된 문장이 생깁니다. 키 비교 뒤에 원문과 번역문의 토큰 집합을 비교하는 검사를 추가합니다.

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

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

Unity 2022.3 LTS와 TextMeshPro 기준으로는 TMP_Text.GetPreferredValues() 결과가 컨테이너 폭을 넘는지 먼저 검사할 수 있습니다. 단, 자동 줄바꿈과 실제 프리팹 설정에 따라 결과가 달라지므로 편집기 배치 검사의 보조 신호로 사용해야 합니다.

using TMPro;
using UnityEngine;

public static class TextOverflowCheck
{
    public static bool IsHorizontallyOverflowing(TMP_Text text)
    {
        var width = text.rectTransform.rect.width;
        var preferred = text.GetPreferredValues(text.text, width, 0f);
        return preferred.x > width && !text.enableWordWrapping;
    }
}

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

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

고정 폭 버튼에서 독일어 번역이 넘치고 줄바꿈 정책에 따라 수정된 비교 화면

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

AI에는 다음과 같은 구조화된 입력을 제공합니다. 입력에는 키, 기준 문장, 대상 문장, 화면 이름, 컨테이너 폭, 확장 비율을 포함하고 출력은 JSON으로 제한합니다.

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

AI의 출력 항목은 risk를 low, medium, high로 제한하고 이유와 확인할 UI를 받으면 충분합니다. AI가 번역 키를 새로 만들거나 렌더링 성공 여부를 추측하게 두면 결과가 흔들립니다. 실제 실패 판정은 CSV 비교와 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 자동화를 붙여 긴 문장과 문맥상 위험한 변경을 먼저 검토하면 전체 화면을 매번 수동 점검하지 않고도 번역 키 누락과 텍스트 가로 깨짐을 빌드 전에 발견할 수 있습니다.