Lingo.dev CLI는 설정된 로컬라이제이션 엔진을 통해 Xcode .xcstringsString Catalogs()를 번역합니다. String Catalogs는 Xcode 15에서 도입된 Apple의 최신 로컬라이제이션 포맷으로, 모든 언어를 하나의 JSON 파일에 저장합니다. CLI는 이 파일을 직접 수정하므로 로캘별 디렉터리를 따로 둘 필요가 없습니다.
이 가이드는 iOS 앱을 처음부터 끝까지 로컬라이즈하는 전체 과정을 안내합니다. CLI 설정부터 로컬 번역, GitHub App을 통한 자동화까지 다뤄 푸시할 때마다 번역이 반영되어 배포되도록 합니다.
데모 리포지토리
함께 따라 하려면 lingodotdev/ios-app-localization-example 저장소를 클론하거나 포크하세요. 이 저장소에는 String Catalog와 Lingo.dev CLI 설정이 포함된 작동 가능한 Xcode 프로젝트가 들어 있습니다.
String Catalogs 작동 방식#
Xcode 15 이전에는 iOS 로컬라이제이션을 위해 .strings 디렉터리 전반에 걸쳐 별도의 .stringsdict 및 [locale].lproj/ 파일을 관리해야 했습니다. String Catalogs는 이를 Xcode가 자동으로 관리하는 하나의 Localizable.xcstrings 파일로 대체합니다.
SwiftUI나 UIKit에서 문자열을 로컬라이즈 가능하도록 표시하면, Xcode가 빌드 중 이를 감지해 String Catalog에 항목을 추가합니다. 각 항목에는 원문 문자열, 설정된 각 로캘의 번역, 그리고 번역가에게 맥락을 전달하는 선택적 주석 필드가 포함됩니다.
| 항목 | 기존 .strings | String Catalogs .xcstrings |
|---|---|---|
| 파일 수 | 테이블·로캘별 파일 1개 | 파일 1개에 모든 로캘 포함 |
| 형식 | 키-값 텍스트 | 구조화된 JSON |
| 복수형 지원 | 별도 .stringsdict 파일 | 복수 규칙 내장 |
| Xcode 연동 | 수동 내보내기/가져오기 | 자동 감지 |
| 번역가 메모 | 지원 안 함 | 항목별 주석 필드 |
CLI는 파일 확장자로 .xcstrings 형식을 감지하고, 이 JSON 구조를 파싱한 뒤 각 항목을 로컬라이제이션 엔진으로 번역한 다음 주석, 복수형 규칙, 메타데이터를 그대로 유지한 채 동일한 파일에 다시 기록합니다.
사전 준비#
로컬라이제이션 엔진 만들기
모든 번역은 어떤 LLM 모델, 용어집, 브랜드 보이스, 규칙을 적용할지 결정하는 설정인 로컬라이제이션 엔진을 거쳐 처리됩니다. Lingo.dev dashboard에서 로컬라이제이션 엔진을 만들고 API key를 생성하세요.
Node.js 확인
CLI를 사용하려면 Node.js 22 이상이 필요합니다:
node -vXcode에서 로컬라이제이션 활성화
Xcode 프로젝트에서 Project Settings > Info > Localizations로 이동한 뒤 대상 언어를 추가하세요. Xcode는 추가한 각 로캘에 맞는 String Catalog 항목을 생성합니다. 자세한 내용은 Apple의 localization documentation을 참고하세요.
CLI 설치 및 설정#
CLI를 설치하고 인증한 다음 프로젝트를 설정하세요. 전체 과정은 Quickstart에서 확인할 수 있습니다.
npm install -g @lingo.dev/cli
lingo login프로젝트 루트에서 lingo init을 실행하고 안내에 따라 답하세요(소스 로캘, 대상 로캘, 그리고 String Catalog를 가리키는 파일 패턴). 그런 다음 lingo link을 실행해 프로젝트를 조직과 엔진에 연결합니다. 이 두 단계로 .lingo/config.json 파일이 생성됩니다:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "MyApp/Localizable.xcstrings" }]
}.lingo/config.json은 반드시 커밋하세요. 무엇을 번역할지 결정하는 기준 파일이기 때문입니다. .xcstrings 형식은 파일 확장자로 감지됩니다. String Catalog는 모든 로캘을 하나의 파일에 저장하므로 패턴에 로캘 플레이스홀더를 넣을 필요가 없습니다. CLI는 소스 언어 항목을 읽고 모든 대상 언어를 동일한 파일에 다시 기록합니다. 전체 스키마는 configuration 레퍼런스를 참고하세요.
여러 String Catalog 사용하기
프로젝트에서 여러 String Catalog 파일을 사용한다면(예: 프레임워크 타깃마다 하나씩), 각각에 대해 files 항목을 추가하세요:
{
"files": [
{ "pattern": "MyApp/Localizable.xcstrings" },
{ "pattern": "MyAppWidgets/Localizable.xcstrings" }
]
}로컬에서 번역하기#
프로젝트 루트에서 첫 번역을 실행하세요:
lingo push --backfill-missingCLI는 String Catalog를 읽고 누락된 모든 항목을 로컬라이제이션 엔진으로 번역한 뒤, 작업이 끝날 때까지 기다렸다가 결과를 .xcstrings 파일에 다시 기록합니다. Xcode에서 파일을 열어 설정한 각 로캘에 번역이 채워진 것을 확인하세요.
소스 문자열을 수정한 뒤에는 일반 lingo push 실행만으로 변경된 부분만 번역됩니다. 소스가 바뀌지 않은 항목은 서버 측에서 건너뛰며, 이는 lockfile로 추적됩니다:
lingo push번역가 메모#
String Catalogs는 항목별 주석 필드를 지원하며, CLI는 이 주석을 번역 요청에 함께 포함합니다. 이런 주석은 로컬라이제이션 엔진에 맥락을 제공해 용어의 의미를 분명히 하고, 톤을 지정하거나, 문자열이 UI의 어디에 표시되는지 설명하는 데 도움이 됩니다.
Xcode에서 String Catalog 편집기에서 문자열을 선택한 뒤 검사기 패널에 주석을 추가하세요. 이 주석은 .xcstrings JSON에 저장됩니다:
{
"sourceLanguage": "en",
"strings": {
"Set": {
"comment": "Refers to a collection of items, not the verb",
"localizations": { }
}
}
}CLI는 이 주석을 문자열과 함께 전송해 모델이 올바르게 해석하도록 유도합니다. 예를 들어 맥락 없이 "Set"만 있으면 많은 언어에서 동사로 번역될 수 있지만, 주석이 있으면 이런 모호함을 없앨 수 있습니다. 더 많은 패턴은 Translator Notes를 참고하세요.
복수형#
String Catalogs는 CLDR plural rules를 사용해 복수형을 기본으로 처리합니다. Xcode에서 복수형 변형을 정의하면 String Catalog는 대상 언어에 필요한 각 복수 범주(zero, one, two, few, many, other)에 대한 규칙을 저장합니다.
CLI는 번역 과정에서도 이 구조를 유지하고 각 대상 로캘에 맞는 올바른 복수 범주를 생성합니다. 영어는 두 가지 범주(one 및 other)만 사용하지만, 아랍어는 여섯 가지, 폴란드어는 네 가지, 일본어는 한 가지만 필요합니다. 로컬라이제이션 엔진이 이런 차이를 자동으로 처리합니다.
GitHub App으로 자동화하기#
지속적 로컬라이제이션을 위해 저장소에 Lingo.dev GitHub App을 설치하세요. 별도의 CI runner나 API key secret, lockfile을 직접 관리할 필요가 없습니다. 설치 후 .lingo/config.json(및 해당 engineId)를 가리키도록 설정하면 푸시와 pull request에 자동으로 반응합니다. 변경된 소스 문자열을 감지해 엔진으로 번역하고, 업데이트된 .xcstrings을 브랜치에 커밋하거나 pull request를 생성합니다.
직접 실행하는 방식을 선호하시나요?
원한다면 자체 CI 작업(Node.js를 실행할 수 있는 어떤 runner든 가능)에서 lingo push을 실행하고 결과를 커밋할 수도 있습니다. 이 경우 LINGO_API_KEY으로 인증하면 됩니다. runner 기반 패턴은 CI/CD 워크플로를 참고하세요.
배포 전 검증#
번역되지 않은 문자열이 프로덕션에 배포되지 않도록 lingo check을 배포 게이트로 활용하세요. 누락되었거나 오래된 번역을 보고하고, 아직 처리할 작업이 남아 있으면 0이 아닌 상태 코드로 종료합니다:
lingo check빌드 전에 별도의 CI 단계로 추가하세요.
