아이오에스 앱 현지화하기

공유 로캘을 보존하면서 애플 문자열 카탈로그나 레거시 리소스를 번역하고, Xcode와 앱에서 결과를 확인하세요.

아이오에스 앱은 리소스 파일에 새 언어를 추가해도 기존의 현지화 문자열 조회 호출을 그대로 사용할 수 있습니다. Lingo.dev는 리소스를 번역하고, 사용자에게 표시할 번들, 테이블, 로캘, 변형은 기존처럼 Xcode와 앱이 결정합니다.

프로젝트에서 이미 불러오는 형식을 사용하세요. 문자열 카탈로그는 하나의 .xcstrings 파일에 여러 언어를 담지만, .strings 및 .stringsdict 리소스는 로캘별 파일을 사용합니다. 이 차이에 따라 결과가 기록되는 위치와 업데이트 중 보호해야 할 항목이 달라집니다.

기준이 되는 리소스 정하기 #

문자열 카탈로그를 사용하는 프로젝트에서는 개발 언어, 지원 대상 언어, 앱에서 불러오는 카탈로그를 파악하세요. Xcode 15에서 도입된 .xcstrings의 파일 이름은 보통 Localizable.xcstrings입니다. 메시지를 기능이나 번들에 따라 여러 카탈로그로 나눌 수 있으므로, 현지화할 화면에서 사용하는 카탈로그를 모두 포함하세요.

레거시 리소스를 사용한다면 관련 .lproj 디렉터리, 문자열 테이블, 복수형 사전을 파악하세요. Base.lproj에는 기본 인터페이스 리소스가 들어 있을 수 있습니다. 하지만 이 리소스가 있다는 이유만으로 번역기가 사용할 원문 언어나 문자열 테이블을 알 수 있다고 가정해서는 안 됩니다. 프로젝트의 개발 언어 설정과 파일 구성을 일치시키세요.

번역하기 전에 화면의 텍스트를 현지화 문자열 조회 호출에 연결하세요. 파일을 번역해도 하드코딩된 사용자 인터페이스 문자열이 바뀌거나 Xcode 타깃에 리소스가 등록되지는 않습니다. 검토자가 참고할 수 있도록 화자와 화면을 설명하는 주석을 유지하세요. 기존 문자열 카탈로그 핸들러는 주석을 보존하지만 번역 단위 힌트에는 포함하지 않습니다. 따라서 생성에 꼭 필요한 맥락은 로컬라이제이션 엔진이 지원하는 지침에 넣으세요.

공유 문자열 카탈로그 구성하기 #

프로젝트 루트에서 최신 CLI를 설치하고 연결하세요:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'App/Localizable.xcstrings' --yes
lingo link

해당 경로에 카탈로그가 있다면, 생성되는 .lingo/config.json의 구조는 다음과 같아야 합니다:

json
{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr"],
  "files": [{ "pattern": "App/Localizable.xcstrings" }]
}

자리표시자를 복사하지 말고 연결 과정에서 생성된 식별자를 그대로 사용하세요. 확장자에 따라 xcode-xcstrings이 선택됩니다. 각 대상의 결과는 같은 카탈로그 경로에 기록되며, 원문과 다른 로캘을 보존하면서 로캘 항목을 추가합니다. 이 공유 파일 형식에서는 별도의 targetPath을 사용할 수 없습니다.

원문 값은 공유 구조 안에 있습니다:

json
{
  "sourceLanguage": "en",
  "strings": {
    "Welcome": {
      "comment": "Greeting on the signed-in home screen",
      "localizations": {
        "en": { "stringUnit": { "state": "translated", "value": "Welcome" } }
      }
    }
  },
  "version": "1.0"
}

번역 후 en 옆에 요청한 로캘 항목이 있는지 확인하세요. 핸들러는 원문의 복수형 및 기기별 변형의 말단 항목도 지원하며, shouldTranslate: false로 표시된 항목은 건너뜁니다. 항목에 원문 언어의 현지화 값이 없으면 키가 원문 텍스트로 사용됩니다. 기술적인 키는 실제로 전달하려는 메시지를 대신할 수 없습니다. 애플 문자열 카탈로그에서 이러한 선택 규칙과 현재 원문을 기존 카탈로그와 일치시켜야 하는 이유를 확인할 수 있습니다.

레거시 파일은 별도 경로로 유지하기 #

레거시 프로젝트에서는 공유 카탈로그 항목 대신 다음 파일 항목을 사용하세요:

json
[{ "pattern": "App/en.lproj/Localizable.strings" }, { "pattern": "App/en.lproj/Localizable.stringsdict" }]

프로젝트에 실제로 있는 리소스만 포함하세요. 확장자에 따라 핸들러가 선택되며, 스페인어 출력은 App/es.lproj/에 저장해야 합니다. 프로젝트의 개발 언어 설정도 여기서 선택한 원문 언어와 일치시키세요.

문자열 키와 서식 자리표시자는 런타임 규약의 일부입니다. %@, 위치 인수, 호출 코드가 기대하는 자료형을 보존하세요. .stringsdict에 담긴 복수형 변수 구조는 서식 문자열과 일관성을 유지해야 합니다. 어느 쪽도 임의의 XML이나 텍스트로 취급하지 말고, 애플 문자열과 문자열 사전에서 각각의 규약을 확인하세요.

번역하고 병합 결과 확인하기 #

교체하기 전에 현재 카탈로그를 버전 관리 시스템에 저장하거나 별도 사본으로 보관하세요. 로컬 수정 사항을 보호하려면 --wait 없이 제출하고, 결과를 가져오기 전에 lingo pull --dry-run을 확인하세요. 강제로 덮어쓰지 말고 차이를 조정하세요. 완료를 기다린 뒤 결과를 기록하는 방식은 가져오기 방식과 달리 기록 직전의 최신 상태를 기준으로 충돌을 검사하지 않습니다. 검토된 번역 보존하기를 참고하세요.

첫 번역을 문제없이 진행하려면, 대기하는 동안 카탈로그가 변경되지 않는 경우에만 다음 명령을 사용하세요. 기존 프로젝트에 로캘을 추가하기 전에는 먼저 기존 로캘의 일반적인 원문 업데이트를 마치고 결과를 가져와 확인하세요. 그런 다음 로캘을 추가하고 누락된 번역을 채우는 동안 해당 원문 리비전을 고정하세요. 필요한 순서는 언어 추가하기에서 확인할 수 있습니다:

bash
lingo push --backfill-missing --wait

공유 카탈로그는 파일이 이미 있어도 로캘별로 작업이 계획됩니다. 새 파일 이름을 찾는 대신 요청한 로캘 항목을 확인하세요. 처음에 별도 옵션 없이 푸시하면 번역하지 않고 원문 기준 상태만 설정할 수 있습니다. 일반적인 원문 변경 후에는 lingo push --wait을 사용하세요. 완료를 기다리지 않았다면 제출에 사용한 checkout에서 lingo pull으로 기록된 결과를 가져오세요.

표현을 수정하려면 Xcode에서 대상 언어 항목을 편집하세요. CLI의 --force은 변경되지 않은 카탈로그에 포함된 번역을 여전히 재사용할 수 있습니다. 지침을 변경한 뒤 항목 하나를 다시 생성하려면, 원문과 주변 번역을 보존하는 카탈로그 수정 절차를 따르세요.

lingo purge은 원문과 대상 언어가 같은 경로를 공유하는 문자열 카탈로그를 건너뜁니다. 선택한 번역을 다시 생성하려면 문자열 카탈로그 수정 워크플로를 사용하세요.

Xcode와 대표 화면에서 검증하기 #

Xcode에서 결과 파일을 열고 카탈로그나 레거시 파일이 의도한 타깃과 번들에 포함되어 있는지 확인하세요. 프로젝트의 기존 스킴으로 빌드하세요. 대상 언어 설정으로 실행한 뒤, 간단한 레이블, 서식이 적용된 값, 복수형 또는 기기별 변형이 포함된 화면을 확인하세요.

대상 언어의 자리표시자를 호출 코드와 비교하세요. 각 언어에서 서로 다른 복수형이 선택되도록 수량 값을 바꿔 테스트하세요. 영어의 복수형 범주만으로 모든 대상 언어의 규칙을 정의할 수는 없습니다. 병합된 카탈로그에 수정하지 않은 로캘이 그대로 남아 있는지 확인하세요. 긴 레이블, 접근성 텍스트, 텍스트 잘림을 검토하고, 해당하는 경우 오른쪽에서 왼쪽으로 표시되는 동작도 확인하세요.

Xcode의 빌드 검사는 리소스 문제를 감지할 수 있지만, 의미는 언어 검토자나 적절한 측정 방식으로 확인해야 합니다. lingo check만으로는 .xcstrings의 완전성이나 애플 복수형 동작의 정확성을 확인할 수 없습니다.

자동화에서도 공유 파일 보존하기 #

원문, 승인된 대상 번역, 구성, .lingo/lock.json을 함께 보관한 다음, 반복 작업에 사용할 GitHub App 또는 지속적 통합 실행기를 선택하세요. 실행기는 자체 인증과 상태를 관리하고, 결과를 검토 가능한 형태로 다시 기록합니다. 문자열 카탈로그의 차이 내역은 공유 파일의 변경 사항으로 검토하세요. 승인하기 전에 원문 리비전, 변경된 로캘, 보존된 로캘을 파악하세요.

크로스플랫폼 프로젝트에서는 XML 한정자와 ARB 생성을 위해 별도의 안드로이드 및 Flutter 워크플로를 사용하세요. 각 플랫폼의 리소스 로딩과 실제 화면 표시는 여전히 별도로 확인해야 합니다.