클라우드 Mac에서 Xcode XLIFF 가져오기 검증하기

릴리스 마감이 다가오면 번역 업체는 보통 여러 개의 .xcloc 또는 .xliff 파일을 전달합니다. 이를 개발자가 평소 사용하는 작업 공간에서 곧바로 더블 클릭해 가져오면 당장은 빠르게 보이지만, 오래된 번역 키나 잘못된 대상 언어, 손상된 자리표시자가 프로젝트에 함께 반영되기 쉽습니다. 더 안전한 방법은 클라우드 Mac에 일회성 검증 디렉터리를 만드는 것입니다. 현재 커밋에서 기준본을 내보내고, 전달 파일을 사전 검사한 다음, 가져오기와 차이 검토를 거쳐 빌드를 실행합니다.

검증 환경 고정하기

검증 노드는 깨끗한 커밋에서 시작해야 합니다. 이미 현지화 파일을 가져온 작업 공간을 재사용하거나, 커밋하지 않은 변경 사항이 있는 디렉터리에서 테스트하지 마세요. 전달 배치마다 임시 브랜치나 별도의 worktree를 만들 수 있습니다.

git fetch origin
git worktree add ../localization-review origin/main
cd ../localization-review
git switch -c review/localization-batch
xcodebuild -version
git status --short

xcodebuild -version, 커밋 SHA, 대상 Scheme, 전달 배치를 로그에 기록합니다. 팀에서 여러 Xcode 버전을 사용한다면 대화형 터미널과 자동화 작업이 서로 다른 도구 체인을 호출하지 않도록 DEVELOPER_DIR도 명시적으로 설정해야 합니다.

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcode-select -p
git rev-parse HEAD

현지화 검증의 기준은 “파일이 열린다”가 아니라, 동일한 커밋과 동일한 Xcode 도구 체인, 동일한 내보내기 매개변수로 설명 가능한 결과를 얻을 수 있느냐입니다.

GPUMini의 클라우드 Mac에서 작업할 때는 먼저 콘솔에서 현재 선택 가능한 구성을 확인한 뒤 검증에 사용할 노드를 선택합니다. 이 작업은 일반적으로 높은 동시 처리 성능을 요구하지 않지만, 가져오기 후 대규모 프로젝트를 전체 빌드해야 한다면 메모리와 디스크 여유 공간도 계획에 포함해야 합니다.

현재 프로젝트에서 기준본 내보내기

.xcodeproj 프로젝트는 프로젝트 매개변수로 내보낼 수 있습니다. Workspace를 사용하는 프로젝트라면 -workspace로 바꾸고 공유 가능한 Scheme을 지정합니다. 다음 예시는 중국어 간체, 일본어, 프랑스어를 내보냅니다. 언어를 추가하려면 -exportLanguage를 반복해서 지정하면 됩니다.

mkdir -p Artifacts/Baseline
xcodebuild \
  -project ExampleApp.xcodeproj \
  -scheme ExampleApp \
  -exportLocalizations \
  -localizationPath Artifacts/Baseline \
  -exportLanguage zh-Hans \
  -exportLanguage ja \
  -exportLanguage fr

내보내기가 끝나면 전달받은 번역을 즉시 덮어쓰지 말고 먼저 파일 목록을 저장합니다.

find Artifacts/Baseline -type f -print0 \
  | sort -z \
  | xargs -0 shasum -a 256 > Artifacts/baseline.sha256

기준본을 통해 세 가지를 확인할 수 있습니다. 현재 프로젝트에 어떤 번역 단위가 있는지, 원문 내용이 무엇인지, Xcode가 어떤 대상 언어를 인식하는지입니다. 전달 파일에 기준본에 없는 키가 포함되어 있다면 번역이 이전 커밋을 기준으로 진행되었을 가능성이 큽니다. 반대로 기준본에 번역되지 않은 단위가 대량으로 추가되었다면 최근 기능이 전달 범위에서 누락되었을 수 있습니다.

가져오기 전에 구조와 자리표시자 검사하기

XLIFF는 기본적으로 XML입니다. 먼저 시스템 도구로 형식을 검사한 다음 언어 속성과 번역 단위 수를 추출합니다. 정규식으로 XML을 수정하지 마세요. 사전 검사 단계에서는 읽기만 수행하고, 수정은 현지화 도구나 검토를 거친 스크립트에서 처리해야 합니다.

find Incoming -name "*.xliff" -print0 |
while IFS= read -r -d '' file; do
  echo "Checking $file"
  xmllint --noout "$file"
  xmllint --xpath \
    'string(/*[local-name()="xliff"]/*[local-name()="file"][1]/@target-language)' \
    "$file"
  echo
done

자리표시자 문제는 가장 엄격하게 차단해야 합니다. %@, %d, 위치 지정 매개변수와 String Catalog가 생성한 변수는 원문과 번역문에서 의미상 대응해야 합니다. 단순히 퍼센트 기호 개수만 세어서는 충분하지 않습니다. %%, 형식 너비, 위치 지정 매개변수는 각각 의미가 다르기 때문입니다. XML 파서로 각 trans-unit의 source와 target을 개별적으로 읽고, 자리표시자를 정규화한 뒤 다중 집합으로 비교하는 방식을 권장합니다.

사용자에게 표시되는 형식 문자열은 줄바꿈 문자, 이스케이프 문자, 복수형 분기도 표본 검사해야 합니다. 언어에 따라 자리표시자 순서는 달라질 수 있지만, 위치 지정 매개변수를 사용한다면 인덱스는 계속 유효해야 합니다.

격리된 디렉터리에서 가져오고 차이 검토하기

사전 검사를 통과한 뒤 .xcloc 패키지를 하나씩 가져옵니다. 각 패키지를 가져온 직후 상태를 기록하면 어떤 전달 파일에서 이상이 발생했는지 쉽게 추적할 수 있습니다.

mkdir -p Artifacts/Logs
for package in Incoming/*.xcloc; do
  name="$(basename "$package" .xcloc)"
  xcodebuild \
    -project ExampleApp.xcodeproj \
    -importLocalizations \
    -localizationPath "$package" \
    2>&1 | tee "Artifacts/Logs/import-${name}.log"
  test "${PIPESTATUS[0]}" -eq 0 || exit 1
  git status --short
done

가져오기가 성공했다고 해서 검증이 끝난 것은 아닙니다. 먼저 git diff --stat으로 영향 범위를 파악한 다음 파일별 차이를 검토합니다. 정상적인 변경은 String Catalog, 문자열 리소스 또는 해당 언어 디렉터리에 집중되어야 합니다. Scheme, 빌드 설정, 서명 구성이나 관련 없는 프로젝트 파일까지 변경되었다면 작업을 중단하고 원인을 확인해야 합니다.

git diff --stat
git diff --check
git diff -- '*.xcstrings' '*.strings' '*.stringsdict' 'project.pbxproj'

git diff --check는 일부 후행 공백과 충돌 흔적을 찾아낼 수 있지만 번역의 의미까지 판단하지는 못합니다. “추가, 삭제, 수정된 번역 단위”를 요약한 보고서를 만들고 가져오기 로그와 함께 파이프라인 산출물로 보관하는 것이 좋습니다.

빌드와 재내보내기로 검증 절차 완성하기

마지막으로 대상 Scheme을 깨끗하게 빌드합니다. 프로젝트에 여러 앱 대상이나 확장 기능이 포함되어 있다면 최소 라이브러리 대상만 빌드하지 말고 실제 릴리스 경로 전체를 검증해야 합니다.

set -o pipefail
xcodebuild \
  -project ExampleApp.xcodeproj \
  -scheme ExampleApp \
  -configuration Release \
  -destination 'generic/platform=iOS Simulator' \
  clean build |
  tee Artifacts/Logs/localization-build.log

빌드가 통과하면 가져오기 후의 프로젝트에서 XLIFF를 다시 내보내 기준본과 비교합니다. 재내보내기를 통해 일부 번역이 프로젝트에 실제로 반영되지 않은 문제, 잘못된 언어 코드 매핑, 가져오기 후에도 남아 있는 미번역 단위를 발견할 수 있습니다. 비교할 때는 단순 정렬 차이와 도구가 생성한 메타데이터를 제외하고 번역 단위의 원문, 대상 텍스트, 상태, 메모에 집중해야 합니다.

유지 관리 가능한 검증 파이프라인은 네 가지 증거를 명확히 보관해야 합니다. 도구 체인 및 커밋 정보, 사전 검사 보고서, 가져오기 차이 요약, 빌드 로그입니다. 실패하면 작업 디렉터리를 자동으로 정리하지 말고 먼저 현장을 보존하세요. 성공한 뒤에는 다음 전달 배치가 이전 상태를 물려받지 않도록 임시 worktree를 삭제합니다.

최종 게이트 조건은 다음과 같이 정리할 수 있습니다. XML을 파싱할 수 있고, 대상 언어가 정확하며, 자리표시자 집합이 일치하고, 알 수 없는 번역 단위가 없으며, 차이 범위가 예상과 일치하고, 대상 Scheme 빌드가 성공해야 합니다. 이렇게 하면 클라우드 Mac은 사람의 기억에 의존해 유지되는 또 하나의 가져오기 환경이 아니라 반복 가능한 현지화 검증 노드로 기능합니다.

자주 묻는 질문