Flutter 앱 현지화하기
ARB 메시지를 번역하고 Flutter 리소스를 생성한 다음, 각 대상 로캘에서 화면을 확인하세요.
Flutter의 현지화 도구는 ARB 메시지를 위젯에서 호출할 수 있는 메서드로 변환합니다. Lingo.dev는 이 ARB 리소스를 번역하므로, 생성된 API를 그대로 유지하면서 언어를 추가할 수 있습니다. 인사말과 항목 수를 표시하는 화면 하나부터 시작해 텍스트, 변수, 복수형 처리를 함께 확인하세요.
이 절차는 프로젝트에서 이미 Flutter의 현지화 리소스 생성 기능으로 원본 ARB를 불러오고 있다는 전제하에 진행합니다. 기존 l10n.yaml, 생성기, 위젯 호출은 그대로 유지하세요. 여기서는 Lingo.dev가 파일 번역을 담당하고, 로캘 선택과 메시지 표시는 계속 Flutter가 처리합니다.
각 메시지에 필요한 정보 제공하기 #
원본이 lib/l10n/app_en.arb에 있다면 다음과 같이 카탈로그를 작성하세요.
{
"@@locale": "en",
"welcome": "Welcome, {name}",
"@welcome": {
"description": "Greeting on the signed-in account screen",
"placeholders": { "name": { "type": "String" } }
},
"itemCount": "{count, plural, =0{No items} =1{One item} other{{count} items}}",
"@itemCount": {
"description": "Number of items in the cart",
"placeholders": { "count": { "type": "int" } }
}
}설명은 번역자에게 메시지가 어디에 쓰이는지 알려줍니다. 자리표시자 정의는 호출 측에서 어떤 값을 전달하는지 Flutter에 알려줍니다. ARB 처리기는 두 메시지 문자열을 번역하고 메타데이터를 유지하며, 기존 @@locale 필드를 대상 로캘로 변경합니다.
먼저 원본을 대상으로 프로젝트의 현지화 생성기를 실행한 다음, 생성된 인사말 메서드와 항목 수 메서드를 화면에서 사용하세요. 이렇게 하면 다른 언어를 추가하기 전에 원본 카탈로그와 호출 코드가 맞물려 작동하는지 확인할 수 있습니다.
카탈로그를 로컬라이제이션 엔진에 연결하기 #
프로젝트 루트에서 최신 CLI를 설치하고 인증하세요.
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets de,fr --files 'lib/l10n/app_en.arb' --yes
lingo linkinit는 .lingo/config.json를 작성하고, link는 조직과 로컬라이제이션 엔진을 선택합니다. 생성된 식별자는 그대로 유지하세요. 현지화 필드는 원본 파일만 선택하도록 설정해야 합니다.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [
{ "pattern": "lib/l10n/app_en.arb", "format": "flutter" }
]
}이는 연결된 설정 중 현지화에 해당하는 부분이며, 조직과 로컬라이제이션 엔진의 식별자를 대체하지 않습니다. .arb 확장자를 사용하면 flutter도 자동으로 선택됩니다. 이 구조에서는 app_de.arb와 app_fr.arb가 생성되므로, 프로젝트의 생성기가 이 파일들을 읽는지 확인하세요. 다른 구조를 사용하려면 명시적 대상 경로를 설정하세요.
번역된 카탈로그까지 선택하는 app_*.arb 같은 원본 패턴은 피하세요. 지역별 로캘을 사용할 때는 모든 로캘 문자열을 파일 이름에 그대로 쓸 수 있다고 가정하지 말고, Flutter 프로젝트 설정에 맞게 파일 이름을 표기하세요.
대상 리소스 번역 및 생성하기 #
아직 없는 대상 파일을 생성하려면 다음을 실행하세요.
lingo push --backfill-missing --wait이 명령은 실행이 완료될 때까지 기다린 다음 파일을 가져옵니다. 실행이 검토 대기 상태이거나 실패한 경우, 릴리스용 리소스를 생성하기 전에 해당 상태를 해결하세요. 최초 푸시를 일반 푸시로 진행하면 누락된 번역을 요청하지 않고 원본의 기준 상태만 설정할 수 있습니다.
대상 파일의 키, 설명, 자리표시자의 이름과 유형, @@locale를 점검하세요. 그런 다음 프로젝트의 Flutter 현지화 리소스 생성, 분석, 테스트, 빌드를 실행하세요. 잘못된 ICU 표현식, 누락된 자리표시자, 호환되지 않는 유형이 있다면 다음 단계로 넘어가기 전에 수정하세요. ARB 재구성 과정은 메타데이터를 보존하지만, 번역된 모든 메시지가 Flutter 생성기와 호환되는지까지 검증하지는 않습니다.
독일어와 프랑스어로 화면을 열어 보세요. 짧은 이름과 긴 이름을 입력하고, 항목 수에는 0, 1, 2와 그보다 큰 숫자를 넣어 보세요. 숫자가 표시되는지만 확인하지 말고 복수형 문구도 읽어 보세요. 언어에 따라 영어 원본에 없는 복수형 범주가 필요할 수 있으므로, 대상 언어에 필요한 형태를 검토하세요. 로캘 선택, 대체 동작, 번역에 따른 텍스트 길이 증가를 확인하고, 필요한 경우 텍스트 방향도 확인하세요. 날짜와 숫자 형식은 계속 Flutter 런타임에서 결정합니다.
이후 업데이트도 원본과 연계해 관리하기 #
설정, 원본, 승인된 대상 파일, .lingo/lock.json를 함께 관리하세요. 원본 메시지를 변경한 뒤에는 lingo push --wait를 실행하고, 변경하지 않은 인접 메시지와 해당 메시지를 나란히 비교하며 점검하세요. 설명만 수정한다고 메시지 텍스트가 새 번역 작업의 대상이 되지는 않습니다. 수정된 맥락을 반영해 다시 번역해야 한다면 범위를 제한한 업데이트를 사용하세요.
파일에 다시 쓰는 작업이 대기 중일 때는 대상 파일을 편집하지 마세요. 대상 파일에서 로컬로 수정한 내용을 보호하려면 --wait 없이 제출하고 lingo pull --dry-run를 점검한 다음, 제출에 사용한 checkout에서 lingo pull로 파일을 가져오세요. 다른 컴퓨터에서는 마지막 실행 결과가 공유된다고 가정해서는 안 됩니다. 커밋된 번역을 사용하거나 산출물을 명시적으로 전달해야 합니다. 복구 방법은 검토된 번역 보존하기를 참고하세요.
이 과정이 정상적으로 작동하면 GitHub App 또는 지속적 통합 자동화를 사용해 검토 전에 번역과 리소스 생성을 반복하세요. 네이티브 안드로이드 XML과 애플 리소스는 파일 및 런타임 규약이 다르므로, 크로스 플랫폼 프로젝트에서는 ARB 생성과 분리해 관리하세요.