strings.xml로 Android 앱 로컬라이제이션하기

Lingo.dev CLI는 설정된 로컬라이제이션 엔진을 통해 Android 문자열 리소스(strings.xml)를 번역합니다. CLI의 android 버킷 유형은 <resources>, <string>, <string-array>, <plurals> 요소를 기본 지원하므로 XML 구조를 그대로 유지하면서 각 대상 로캘에 맞는 올바른 복수 범주를 생성합니다.

이 가이드는 Android 앱 로컬라이제이션의 전체 흐름을 안내합니다. CLI 설정부터 로컬 번역, GitHub Actions를 활용한 자동화까지 다뤄서 푸시할 때마다 번역이 함께 배포되도록 할 수 있습니다.

데모 저장소

함께 따라 하려면 lingodotdev/android-app-localization-example를 클론하거나 포크하세요. 이 저장소에는 문자열 리소스, Lingo.dev CLI 설정, GitHub Actions 워크플로가 포함된 동작 가능한 Android 프로젝트가 들어 있습니다.

Android 로컬라이제이션 작동 방식#

Android는 각 로캘마다 전용 values-[locale]/ 디렉터리를 사용하는 리소스 디렉터리 규칙을 따릅니다. 시스템은 기기의 언어 설정에 따라 런타임에 올바른 strings.xml를 로드합니다.

text

app/src/main/res/
  values/              # Default (source) strings
    strings.xml
  values-es/           # Spanish
    strings.xml
  values-fr/           # French
    strings.xml
  values-ja/           # Japanese
    strings.xml

일반적인 strings.xml에는 세 가지 요소 유형이 있습니다:

xml

<resources>
  <!-- Simple strings -->
  <string name="app_name">My App</string>
  <string name="welcome_message">Welcome back!</string>

  <!-- String arrays -->
  <string-array name="planets">
    <item>Mercury</item>
    <item>Venus</item>
    <item>Earth</item>
  </string-array>

  <!-- Plurals -->
  <plurals name="items_count">
    <item quantity="one">%d item</item>
    <item quantity="other">%d items</item>
  </plurals>
</resources>

CLI는 이 세 가지 요소 유형을 모두 파싱하고, 로컬라이제이션 엔진을 통해 내용을 번역한 다음, 로캘별 파일을 올바른 values-[locale]/ 디렉터리에 기록합니다.

사전 준비#

로컬라이제이션 엔진 만들기

CLI를 실행할 때마다 모든 콘텐츠는 로컬라이제이션 엔진을 거칩니다. 이 설정은 어떤 LLM 모델, 용어집, 브랜드 보이스, 지침을 적용할지 결정합니다. Lingo.dev dashboard에서 엔진을 만들고 API key를 생성하세요.

Node.js 확인

CLI를 사용하려면 Node.js 18 이상이 필요합니다:

bash

node -v

Android 프로젝트 준비

프로젝트에는 app/src/main/res/values/ 안에 기본 strings.xml 파일이 있어야 합니다. Android Studio는 새 프로젝트를 만들 때 이 파일을 자동으로 생성합니다. 리소스 디렉터리 설정은 Android의 localization guide를 참고하세요.

CLI 설정#

프로젝트 루트에 i18n.json 파일을 생성하세요. android 버킷은 CLI가 Android XML 리소스를 파싱하고 로캘별로 별도 파일을 만들도록 지정합니다:

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

[locale] 플레이스홀더는 런타임에 설정된 각 로캘 코드로 해석됩니다. CLI는 이 패턴에 소스 로캘을 대입하므로 source: "en"를 사용하면 values-en/strings.xml를 찾습니다. 대상 로캘의 경우 values-es/strings.xml, values-fr/strings.xml 등이 생성됩니다.

기본 로캘 디렉터리 연결하기#

Android는 기본 문자열을 values/(로캘 접미사 없음)에 저장하지만, CLI는 [locale]를 문자 그대로 해석해 values-en/strings.xml를 찾습니다. 이 두 규칙을 이어 주려면 심볼릭 링크를 만드세요:

bash

cd app/src/main/res
ln -s values values-en

이렇게 하면 소스 문자열이 values/strings.xml(Android가 기대하는 위치)과 values-en/strings.xml(CLI가 찾는 위치) 모두에서 보이게 됩니다. 심볼릭 링크는 저장소에 커밋하세요. git은 macOS와 Linux에서 심볼릭 링크를 기본적으로 추적합니다.

Windows

Windows에서는 설정에 따라 Git이 심볼릭 링크를 일반 텍스트 파일로 체크아웃할 수 있습니다. Windows를 사용 중이라면 클론 전에 git config core.symlinks true을 실행하거나, 대신 values/ 디렉터리를 values-en/로 복사하세요.

여러 리소스 파일

프로젝트에서 문자열을 여러 파일(예: strings.xml, arrays.xml)로 나눠 관리한다면 모두 나열하세요. 심볼릭 링크는 디렉터리 전체를 연결하므로 values/ 안의 모든 파일은 values-en/를 통해 접근할 수 있습니다:

json

{
  "buckets": {
    "android": {
      "include": [
        "app/src/main/res/values-[locale]/strings.xml",
        "app/src/main/res/values-[locale]/arrays.xml"
      ]
    }
  }
}

로컬에서 번역하기#

API 키를 설정한 뒤 CLI를 실행하세요:

bash

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

CLI는 소스 strings.xml를 읽고 lockfile을 기준으로 미번역 항목을 찾아낸 다음, 변경분만 로컬라이제이션 엔진을 통해 번역해 대상 values-[locale]/ 디렉터리에 기록합니다. 대상 파일을 열어 번역된 문자열을 확인해 보세요.

개발 중 특정 로캘만 대상으로 하려면:

bash

npx lingo.dev@latest run --target-locale es

복수형#

Android는 복수형 처리를 위해 <plurals> 요소와 CLDR quantity strings(zero, one, two, few, many, other)를 사용합니다. 언어마다 필요한 복수 범주는 다릅니다. 영어는 두 개(one, other)가 필요하고, 러시아어는 네 개, 아랍어는 여섯 개가 필요합니다.

CLI는 번역 중에도 <plurals> 구조를 유지하고 각 대상 로캘에 맞는 올바른 수량 항목을 생성합니다. 예를 들어 두 개 범주를 가진 소스 항목이 있으면:

xml

<plurals name="messages_count">
  <item quantity="one">%d new message</item>
  <item quantity="other">%d new messages</item>
</plurals>

각 대상 언어에 맞는 올바른 범주가 생성됩니다. 로컬라이제이션 엔진은 각 로캘에 어떤 CLDR plural rules가 적용되는지 알고 있으며, 해당 언어에 필요한 범주만 생성합니다.

키 잠금#

브랜드명, API 엔드포인트, 형식 패턴처럼 모든 언어에서 동일하게 유지해야 하는 문자열 값도 있습니다. 이런 경우 키 잠금을 사용해 번역 없이 그대로 복사하세요:

json

{
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"],
      "lockedKeys": ["app_name", "api_base_url"]
    }
  }
}

잠긴 키는 번역 파이프라인을 거치지 않고 소스에서 모든 대상 파일로 그대로 복사됩니다.

GitHub Actions로 자동화하기#

푸시할 때마다 번역이 실행되도록 .github/workflows/translate.yml에 워크플로 파일을 추가하세요:

번역이 main에 직접 커밋됩니다. 설정이 간단하고 마찰이 적어 소규모 팀에 적합합니다:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

GitHub 저장소의 Settings > Secrets and variables > Actions에서 API 키를 LINGODOTDEV_API_KEY로 저장하세요.

배포 전 검증#

번역되지 않은 문자열이 프로덕션에 배포되지 않도록 --frozen 플래그를 배포 게이트로 사용하세요. 번역이 필요한 항목이 하나라도 있으면 CLI는 0이 아닌 상태 코드로 종료합니다:

bash

npx lingo.dev@latest run --frozen

빌드 전에 별도의 CI 단계로 추가하세요:

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

다음 단계#

모바일 앱 로컬라이제이션

iOS, Android, Flutter, React Native를 포함한 모든 모바일 플랫폼 개요

CI/CD 워크플로

GitHub Actions, GitLab CI, Bitbucket Pipelines 활용 패턴

용어집

브랜드명과 기술 용어가 번역되지 않도록 고정하기

키 잠금

특정 값을 번역하지 않고 그대로 복사하기

데모 저장소

Android 로컬라이제이션 작동 방식#

text

app/src/main/res/
  values/              # Default (source) strings
    strings.xml
  values-es/           # Spanish
    strings.xml
  values-fr/           # French
    strings.xml
  values-ja/           # Japanese
    strings.xml

일반적인 strings.xml에는 세 가지 요소 유형이 있습니다:

xml

<resources>
  <!-- Simple strings -->
  <string name="app_name">My App</string>
  <string name="welcome_message">Welcome back!</string>

  <!-- String arrays -->
  <string-array name="planets">
    <item>Mercury</item>
    <item>Venus</item>
    <item>Earth</item>
  </string-array>

  <!-- Plurals -->
  <plurals name="items_count">
    <item quantity="one">%d item</item>
    <item quantity="other">%d items</item>
  </plurals>
</resources>

사전 준비#

로컬라이제이션 엔진 만들기

Node.js 확인

CLI를 사용하려면 Node.js 18 이상이 필요합니다:

bash

node -v

Android 프로젝트 준비

CLI 설정#

프로젝트 루트에 i18n.json 파일을 생성하세요. android 버킷은 CLI가 Android XML 리소스를 파싱하고 로캘별로 별도 파일을 만들도록 지정합니다:

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

기본 로캘 디렉터리 연결하기#

bash

cd app/src/main/res
ln -s values values-en

Windows

여러 리소스 파일

json

{
  "buckets": {
    "android": {
      "include": [
        "app/src/main/res/values-[locale]/strings.xml",
        "app/src/main/res/values-[locale]/arrays.xml"
      ]
    }
  }
}

로컬에서 번역하기#

API 키를 설정한 뒤 CLI를 실행하세요:

bash

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

개발 중 특정 로캘만 대상으로 하려면:

bash

npx lingo.dev@latest run --target-locale es

복수형#

CLI는 번역 중에도 <plurals> 구조를 유지하고 각 대상 로캘에 맞는 올바른 수량 항목을 생성합니다. 예를 들어 두 개 범주를 가진 소스 항목이 있으면:

xml

<plurals name="messages_count">
  <item quantity="one">%d new message</item>
  <item quantity="other">%d new messages</item>
</plurals>

키 잠금#

json

{
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"],
      "lockedKeys": ["app_name", "api_base_url"]
    }
  }
}

잠긴 키는 번역 파이프라인을 거치지 않고 소스에서 모든 대상 파일로 그대로 복사됩니다.

GitHub Actions로 자동화하기#

푸시할 때마다 번역이 실행되도록 .github/workflows/translate.yml에 워크플로 파일을 추가하세요:

번역이 main에 직접 커밋됩니다. 설정이 간단하고 마찰이 적어 소규모 팀에 적합합니다:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

GitHub 저장소의 Settings > Secrets and variables > Actions에서 API 키를 LINGODOTDEV_API_KEY로 저장하세요.

배포 전 검증#

bash

npx lingo.dev@latest run --frozen

빌드 전에 별도의 CI 단계로 추가하세요:

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

다음 단계#

모바일 앱 로컬라이제이션

iOS, Android, Flutter, React Native를 포함한 모든 모바일 플랫폼 개요

CI/CD 워크플로

GitHub Actions, GitLab CI, Bitbucket Pipelines 활용 패턴

용어집

브랜드명과 기술 용어가 번역되지 않도록 고정하기

키 잠금

특정 값을 번역하지 않고 그대로 복사하기