안드로이드 앱 현지화하기
안드로이드 리소스를 번역해 알맞은 로캘 디렉터리에 배치하고, 앱에서 메시지를 확인하세요.
안드로이드는 리소스 디렉터리에서 현지화된 텍스트를 선택하고, 애플리케이션 코드는 기존 리소스 이름을 그대로 사용합니다. Lingo.dev는 이 리소스를 번역해 대상 디렉터리에 배치합니다. 먼저 기본 리소스 파일에서 인사말 하나, 목록 하나, 복수형 리소스 하나를 골라 다른 로캘로 실행한 화면에 표시해 보세요.
이 절차는 네이티브 안드로이드 XML에 사용하세요. Flutter를 사용한다면 ARB 리소스와 자동 생성된 현지화 코드를, JSON 카탈로그를 사용한다면 리액트 네이티브 현지화를 참고하세요.
화면에서 불러올 리소스 준비하기 #
기본 리소스는 app/src/main/res/values/strings.xml에 두세요.
<resources>
<string name="welcome">Welcome, %1$s!</string>
<string name="product_name" translatable="false">ExampleApp</string>
<string-array name="delivery_options">
<item>Standard delivery</item>
<item>Express delivery</item>
</string-array>
<plurals name="items_count">
<item quantity="one">%d item</item>
<item quantity="other">%d items</item>
</plurals>
</resources>애플리케이션의 기존 리소스 호출을 사용해 이 리소스를 화면에 연결하세요. welcome는 메시지를 식별하고, %1$s는 코드에서 전달한 이름을 받습니다. 복수형 리소스에는 알맞은 형태를 선택하고 서식을 적용할 수 있도록 개수를 전달해야 합니다. translatable="false"는 제품 이름을 번역 대상에서 제외합니다.
안드로이드 파일 처리기는 일반 텍스트 항목을 선택하고, 인라인 하위 마크업이 섞인 항목은 건너뜁니다. 메시지에 <b> 또는 <xliff:g> 같은 하위 요소가 있다면 해당 항목은 별도로 처리하세요. CDATA 텍스트는 감싸는 구문을 유지한 채 번역할 수 있습니다. 그 안의 마크업은 보호되는 하위 구조가 아니라 텍스트로 취급됩니다. 서식이 포함된 리소스는 애플리케이션에서 실제로 사용하는 렌더러로 확인하세요.
원본 선택과 로캘 경로 설정하기 #
프로젝트 루트에서 CLI를 설치하고 연결하세요.
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,pt-BR,zh-Hans --files 'app/src/main/res/values/strings.xml' --yes
lingo link.lingo/config.json에서 연결된 조직과 로컬라이제이션 엔진의 식별자는 그대로 두고, 파일 형식을 명시적으로 설정하세요.
{
"pattern": "app/src/main/res/values/strings.xml",
"format": "android"
}이 객체를 파일 항목으로 사용하세요. .xml 확장자만으로는 안드로이드 리소스 형식과 다른 XML 형식을 구분할 수 없습니다. arrays.xml 같은 다른 리소스 파일에도 원본 항목을 추가하되, 생성된 대상 디렉터리는 포함하지 마세요.
현재 CLI는 한정자가 없는 values/ 디렉터리를 인식하고, 대상 경로를 안드로이드 한정자 형식으로 생성합니다.
| 대상 로캘 | 대상 디렉터리 |
|---|---|
es | values-es |
pt-BR | values-pt-rBR |
zh-Hans | values-b+zh+Hans |
이 구조에는 values-en 심볼릭 링크가 필요하지 않습니다. 이전 설정에서 이 링크를 사용했다면, 삭제하기 전에 설정을 업데이트하고 점검하세요. values-pt-BR처럼 로캘을 그대로 쓴 디렉터리는 필요한 지역 한정자 형식을 따르지 않습니다. 대상 경로를 명시적으로 지정하는 방법과 로캘 표기법은 CLI 설정을 참고하세요.
첫 대상 로캘로 번역하고 불러오기 #
대상 파일이 없다면 다음을 실행하세요.
lingo push --backfill-missing --wait설정된 검토 절차까지 모두 끝날 때까지 기다린 뒤, 가져온 XML을 점검하세요. 리소스 이름, 배열 순서, 수량 속성, 고정된 제품 이름, 서식 지정자를 원본과 비교하세요. --wait를 사용하지 않았다면 제출에 사용한 checkout에서 lingo pull로 완료된 실행 결과를 가져오세요.
프로젝트의 그래들 설정으로 빌드한 뒤, 대상 로캘로 설정된 기기나 에뮬레이터에서 앱을 실행하세요. 화면을 열고 이름과 여러 개숫값을 입력하세요. 빌드가 성공하면 리소스 구문과 참조가 유효한지 확인할 수 있습니다. 기기에서는 안드로이드가 실제로 번역된 디렉터리를 선택했는지 확인하세요.
대상 언어의 각 복수형 범주에 해당하는 개숫값을 입력해 출력을 확인하세요. 처리기는 원본의 복수형 구조를 유지하므로, 영어의 one 및 other만으로는 대상 언어에 필요한 모든 형태를 갖출 수 없습니다. 긴 레이블과 접근성 텍스트를 확인하고, 필요한 경우 오른쪽에서 왼쪽으로 쓰는 레이아웃도 점검하세요. lingo check는 안드로이드 리소스 검사나 누락 여부 검사를 대신하지 않습니다.
원본 변경 사항 반영하기 #
원본, 승인된 번역본, 연결된 설정, .lingo/lock.json를 함께 커밋하세요. 원본 문자열을 수정한 뒤에는 다음 명령으로 변경 사항을 번역하세요.
lingo push --wait엔진 지침을 바꾼 뒤 원본 파일 하나의 모든 번역을 다시 생성하려면, 승인된 번역본을 저장하고 다음을 실행하세요.
lingo push "app/src/main/res/values/strings.xml" --force --wait이 작업은 설정된 대상 로캘에서 선택한 파일의 번역을 교체합니다. 파일 선택과 재생성 방법은 CLI 범위를 참고하세요.
대상 파일의 변경 전후 차이를 보관하세요. 위의 제품 이름 예시처럼 번역하지 않고 고정할 안드로이드 리소스에 translatable="false"를 표시하세요. 번역을 새로 생성하기 전에 기존 수정 사항을 저장하세요. 제출 후 대상 파일이 수정되었는지 확인하려면 --wait를 생략하고, 결과를 가져오기 전에 lingo pull --dry-run를 점검하세요. 이 확인 절차와 충돌 처리 방법은 검토된 번역 보존하기를 참고하세요.
화면 하나가 정상적으로 작동하면 GitHub App이나 지속적 통합 실행기를 사용해 반복적인 번역 작업을 처리하세요. 실행기는 인증과 검토 가능한 형태의 결과 반영을 담당합니다. 다만 승인 전에는 여전히 안드로이드 빌드와 대표 화면 검사를 수행해야 합니다. 다른 곳에서 커밋된 번역은 버전 관리를 통해 전달되며, lingo pull는 로컬에 기록된 제출 건의 결과를 가져옵니다.