게임 Localization 텍스트 누락과 가로 깨짐을 자동 탐지하는 QA 파이프라인

핵심 요약

Localization 품질 문제는 번역 완료 여부만으로 막기 어렵다. 빌드 전에는 문자열 테이블 키 누락을 정적으로 검사하고 빌드 후에는 언어별 해상도에서 주요 UI를 렌더링해 TextMeshPro 오버플로와 화면 경계 초과를 수집해야 한다.

핵심은 누락 키와 가로 깨짐을 서로 다른 실패 유형으로 기록하고 오류 등급에 따라 CI 빌드를 차단하는 것이다. Unity 2022 LTS, Unity Localization 패키지, TextMeshPro 기준으로 설명한다.

Localization 언어 키 텍스트 누락은 왜 발생하는가?

언어 키 누락은 코드나 프리팹이 참조하는 키와 실제 String Table의 항목이 어긋날 때 발생한다. 대표적인 원인은 다음과 같다.

원인	런타임 증상	자동 탐지 위치
키 이름 변경 후 참조 미갱신	빈 문자열 또는 대체 문구 표시	에디터 정적 검사
새 테이블 항목의 일부 언어 미번역	특정 언어에서만 원문 또는 빈 값 표시	테이블 완전성 검사
Addressables 번들 누락	빌드 환경에서만 문자열 로드 실패	플레이 모드 스모크 테스트
동적 키 조합 오류	일부 아이템·퀘스트 이름만 누락	실행 중 키 로그 검사

정적 검사는 “키가 존재하는가”를 확인한다. 반면 실제 화면 검사는 폰트 폴백, 동적 데이터, 비동기 로딩처럼 정적 검사만으로 놓치는 문제를 보완한다.

자동 탐지 파이프라인은 어떻게 구성할까?

아래처럼 검증을 세 단계로 분리하면 실패 원인과 수정 담당자를 빠르게 연결할 수 있다.

flowchart LR
  A[소스·번역 테이블 변경] --> B[정적 키·번역 완전성 검사]
  B -->|통과| C[언어별 테스트 빌드]
  C --> D[UI 시나리오 렌더링·캡처]
  D --> E[누락 키·오버플로 판정]
  E -->|오류 없음| F[배포 후보 생성]
  E -->|오류 발견| G[CI 실패 및 리포트]

1. String Table 키와 번역 완전성을 검사한다

각 로캘의 엔트리 수만 비교하면 기준 언어에서 삭제된 키나 중복 키를 놓칠 수 있다. 기준 로캘인 en의 키 집합을 K_en, 대상 로캘의 키 집합을 K_locale로 두고 차집합을 계산한다.

M_{locale}=K_{en}\setminus K_{locale}

M_locale에 포함된 키는 대상 언어에 없는 항목이다. 반대로 대상 로캘에만 남아 있는 키도 정리 후보로 보고한다.

using System.Linq;
using UnityEditor;
using UnityEngine.Localization.Tables;

public static class LocalizationTableValidator
{
    public static string[] FindMissingKeys(StringTable english, StringTable target)
    {
        var sourceKeys = english.Values.Select(entry => entry.Key).ToHashSet();
        var targetKeys = target.Values.Select(entry => entry.Key).ToHashSet();
        return sourceKeys.Except(targetKeys).OrderBy(key => key).ToArray();
    }
}

빈 문자열 정책도 명확히 정해야 한다. 공백만 있는 번역을 오류로 취급하려면 string.IsNullOrWhiteSpace(entry.LocalizedValue)를 검사한다. 단, 의도적으로 비워 두는 UI가 있다면 예외 키 목록을 코드가 아니라 버전 관리되는 설정 파일로 분리한다.

2. 실제 플레이 화면에서 텍스트 오버플로를 수집한다

긴 독일어 문장, 러시아어 단어, 아랍어 RTL 문자열은 영어 기준 레이아웃에서는 정상처럼 보이기 쉽다. 테스트 시나리오에서 설정 화면, 상점, 퀘스트 보상, 팝업처럼 텍스트 밀도가 높은 화면을 열고 각 언어로 전환한다.

언어별 UI 테스트 화면에서 버튼 라벨과 설명문이 영역을 넘는 사례

TextMeshPro 컴포넌트는 렌더링 뒤 isTextOverflowing으로 오버플로 여부를 확인할 수 있다. 테스트 전용 컴포넌트를 붙여 활성화된 텍스트의 경고를 JSON Lines 형식으로 남기면 CI가 쉽게 파싱할 수 있다.

using TMPro;
using UnityEngine;

public sealed class TmpOverflowProbe : MonoBehaviour
{
    [SerializeField] private TMP_Text target;

    public void ReportIfOverflowing()
    {
        target.ForceMeshUpdate();
        if (!target.isTextOverflowing) return;

        Debug.LogError($"LOCALIZATION_UI_OVERFLOW|{target.name}|{target.text}");
    }
}

isTextOverflowing은 줄 바꿈 설정과 오버플로 모드의 영향을 받는다. 따라서 Overflow 모드로 잘린 글자가 보이지 않는 경우만 찾으려 하지 말고 버튼·패널의 RectTransform이 부모 영역을 벗어나는지도 함께 확인해야 한다.

3. 경계 초과와 누락 문자열을 같은 리포트로 묶는다

UI 요소의 월드 코너를 상위 RectTransform 좌표계로 변환한 뒤 자식 사각형이 부모 사각형에 포함되는지 판정한다. 허용 오차 p를 두면 반올림 오차로 인한 오탐을 줄일 수 있다.

x_{min}^{child}\geq x_{min}^{parent}-p\quad\land\quad x_{max}^{child}\leq x_{max}^{parent}+p

권장 시작값은 Canvas 스케일 기준 2px이다. 해상도별 UI 스케일이 크다면 고정 픽셀 값 대신 Canvas 단위 기준으로 보정한다.

검사 유형	실패 조건	CI 권장 정책
필수 키 누락	기준 로캘에는 있으나 대상 로캘에 없음	즉시 실패
필수 번역 공백	필수 키의 값이 비어 있음	즉시 실패
TMP 오버플로	`isTextOverflowing == true`	신규 발생 시 실패
사각형 경계 초과	자식 UI가 부모 클리핑 영역 밖에 있음	신규 발생 시 실패
스크린샷 픽셀 차이	승인된 기준 이미지와 임계값 초과	검토 필요 경고

UI 가로 깨짐 자동화의 오탐을 어떻게 줄일까?

자동화가 신뢰를 잃는 가장 빠른 길은 이미 알려진 경고를 매 빌드마다 반복하는 것이다. 다음 기준을 적용한다.

검사 대상을 모든 프리팹이 아니라 실제 유저 플로우의 화면 목록으로 시작한다.
언어, 해상도, UI 배율, 폰트 에셋 버전을 리포트에 함께 기록한다.
기존 결함은 기준 파일에 등록하고 새로운 실패만 PR을 차단한다.
의도된 말줄임표는 컴포넌트에 AllowOverflowWarning 같은 명시적 예외 플래그를 둔다.

이미지 비교는 마지막 방어선으로 사용한다. 픽셀 차이는 안티앨리어싱과 플랫폼별 폰트 래스터화에 민감하므로 키 누락·TMP 오버플로·레이아웃 경계 검사를 먼저 통과한 화면만 비교하는 편이 안정적이다.

CI에서 어떤 기준으로 빌드를 실패시켜야 할까?

초기에는 기준을 너무 넓게 잡지 않는 편이 좋다. ko, ja, de, ru, ar처럼 문자 체계와 문자열 길이 특성이 다른 대표 언어부터 운영한다. PR에서는 빠른 정적 검사와 핵심 화면 스모크 테스트를 실행하고 야간 빌드에서 전체 언어·전체 해상도를 순회한다.

CI 리포트에서 언어, 화면, 누락 키, 텍스트 오버플로 위치를 함께 표시한 예시

리포트에는 최소한 다음 필드를 남긴다.

{
  "locale": "de",
  "scene": "Shop",
  "screen": "PurchasePopup",
  "issueType": "tmp_overflow",
  "objectPath": "Canvas/Popup/ConfirmButton/Label",
  "textKey": "shop.purchase.confirm",
  "build": "1.8.0-ci.342"
}

이 구조라면 QA는 재현 화면을 바로 찾을 수 있고 번역 담당자는 키를, 클라이언트 담당자는 레이아웃 경계를 확인할 수 있다.

자주 묻는 질문 (FAQ)

누락 키는 런타임 로그만으로 찾아도 충분한가?

아니다. 런타임 로그는 실제로 실행한 경로만 검증한다. String Table 비교로 전체 키 집합을 먼저 검사하고 런타임 로그는 동적 키와 번들 로딩 오류를 찾는 보조 수단으로 사용한다.

모든 언어와 모든 해상도를 PR마다 검사해야 하는가?

처음부터 그럴 필요는 없다. PR에서는 대표 언어와 핵심 화면만 검사하고 전체 조합은 야간 빌드로 분리하면 피드백 속도와 커버리지를 함께 확보할 수 있다.

텍스트를 자동 축소하면 가로 깨짐 검사가 필요 없는가?

필요하다. 자동 축소는 버튼 간격, 읽기성, 최소 글자 크기 문제를 숨길 수 있다. 최소 폰트 크기 이하로 축소되었는지도 별도 품질 기준으로 기록해야 한다.

정리

Localization 자동 QA는 번역 파일 검사 하나로 끝나지 않는다. 키 집합 비교로 콘텐츠 누락을 막고, 실제 렌더링과 레이아웃 검사로 화면 깨짐을 찾고, 새로 발생한 문제만 CI에서 차단해야 지속적으로 운영할 수 있다. 이 세 단계를 분리하면 오류의 원인과 담당 영역도 명확해져 패치 전 검증 시간이 짧아진다.