asc localize metadata
이 스킬을 사용하여 영어(또는 원하는 소스 로케일) App Store 메타데이터를 가져와 LLM으로 번역하고, 번역본을 App Store Connect에 자동으로 푸시할 수 있습니다.
명령어 검색 및 출력 규칙
- 정확한
asc버전에 맞는 플래그는 항상--help로 확인합니다:asc localizations --helpasc localizations download --helpasc localizations upload --helpasc apps info edit --help
- 명시적인 긴 플래그(
--app,--version,--version-id,--type,--app-info)를 선호합니다. - 기본 출력은 JSON입니다. 사람이 확인하는 단계에서만
--output table을 사용합니다. - 결정론적(deterministic) ID 기반 작업을 선호합니다. 사용자가 명시적으로 동의하지 않는 한
head -1로 "첫 번째 행을 선택"하지 않습니다.
전제 조건
- 인증 구성됨(
asc auth login또는ASC_*환경 변수) - 앱 ID를 알고 있어야 함(
asc apps list로 확인) - App Store Connect에 최소 하나의 로케일(보통 en-US)에 메타데이터가 있어야 함
지원 로케일
버전 및 앱 정보 현지화를 위한 App Store Connect 로케일:
ar-SA, ca, cs, da, de-DE, el, en-AU, en-CA, en-GB, en-US,
es-ES, es-MX, fi, fr-CA, fr-FR, he, hi, hr, hu, id, it,
ja, ko, ms, nl-NL, no, pl, pt-BR, pt-PT, ro, ru, sk,
sv, th, tr, uk, vi, zh-Hans, zh-Hant
두 가지 메타데이터 유형
버전 현지화 (릴리스별)
필드: description, keywords, whatsNew, supportUrl, marketingUrl, promotionalText
앱 정보 현지화 (앱 수준, 영구적)
필드: name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText
워크플로우
1단계: ID 확인
# 앱 ID 찾기
asc apps list --output table
# 최신 버전 ID 찾기
asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table
# 또는 편집 가능한 버전:
asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table
# 앱 정보 ID 찾기 (이름/부제목 등 앱 수준 필드)
asc apps info list --app "APP_ID" --output table
참고:
- 버전 현지화 필드(설명, 키워드, 새로운 기능 등)는 버전별로 적용됩니다.
- 앱 정보 필드(이름, 부제목, 개인정보 URL/텍스트)는 앱 수준이며
--type app-info를 사용합니다. - 앱 이름이나 버전 문자열만 알고 있고 ID를 결정론적으로 찾아야 한다면
asc-id-resolver를 사용하세요.
2단계: 소스 로케일 다운로드
# 버전 현지화를 로컬 .strings 파일로 다운로드
# (설명, 키워드, 새로운 기능, 프로모션 텍스트, 지원 URL, 마케팅 URL 등)
asc localizations download --version "VERSION_ID" --path "./localizations"
# 앱 정보 현지화를 로컬 .strings 파일로 다운로드
# (이름, 부제목, 개인정보 처리방침 URL, 개인정보 선택 URL, 개인정보 처리방침 텍스트 등)
asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
이 명령어는 ./localizations/en-US.strings 및 ./app-info-localizations/en-US.strings와 같은 파일을 생성합니다. 다운로드가 불가능한 경우 개별 필드를 읽습니다:
# 버전 현지화 목록을 조회하여 기존 로케일과 내용 확인
asc localizations list --version "VERSION_ID" --output table
3단계: LLM으로 번역
각 대상 로케일에 대해 소스 텍스트를 번역합니다. 다음 규칙을 따르세요:
번역 지침
- 어조 및 격식: 항상 격식 있고 공손한 언어를 사용하세요. 언어에 따라 격식 있는 "당신" 형태를 사용합니다(러시아어: «вы», 독일어: «Sie», 프랑스어: «vous», 스페인어: «usted», 네덜란드어: «u», 이탈리아어: «Lei», 포르투갈어: «você» 등). App Store 설명은 전문적인 마케팅 카피이므로 비격식적이거나 캐주얼한 표현을 절대 사용하지 마세요.
- description: 자연스럽게 번역하고, 현지 시장에 맞게 어조를 조정하세요. 서식(줄바꿈, 글머리 기호, 이모지)을 유지하세요. 4000자 이내.
- keywords: 문자 그대로 번역하지 마십시오. 해당 로케일의 사용자가 검색할 만한 키워드를 조사하세요. 쉼표로 구분하며 총 100자 이내. 중복 없음, 앱 이름 포함 금지(Apple이 자동으로 추가함).
- whatsNew: 릴리스 노트를 번역하세요. 간결하게 유지하세요. 최대 4000자.
- promotionalText: 마케팅 훅을 번역하세요. 최대 170자. 새 버전 없이도 업데이트할 수 있습니다.
- subtitle: 태그라인을 번역하거나 현지화에 맞게 조정하세요. 최대 30자로 매우 제한적이므로 창의적인 조정이 필요할 수 있습니다.
- name: 일반적으로 원래 앱 이름을 유지합니다. 사용자가 명시적으로 요청한 경우에만 번역하세요. 최대 30자.
LLM 번역 프롬프트 템플릿
각 대상 로케일에 대해 다음 방식을 사용합니다:
다음 App Store 메타데이터를 {source_locale}에서 {target_locale}로 번역하세요.
규칙:
- description: 자연스럽고 유창한 번역. 서식(줄바꿈, 글머리 기호, 이모지) 유지. 최대 4000자.
- keywords: 문자 그대로 번역하지 마십시오. 현지 사용자가 App Store에서 검색할 키워드를 선택하세요. 쉼표로 구분, 총 100자 이내. 앱 이름 포함 금지.
- whatsNew: 릴리스 노트를 자연스럽게 번역. 최대 4000자.
- promotionalText: 마케팅 태그라인을 번역. 최대 170자.
- subtitle: 태그라인을 창의적으로 조정하여 최대 30자에 맞춤.
- name: 명시적으로 요청하지 않는 한 원래 앱 이름을 유지. 최대 30자.
- 격식 있고 공손한 언어 사용, 격식 있는 "당신" 형태 사용(러시아어: вы, 독일어: Sie, 프랑스어: vous, 스페인어: usted, 네덜란드어: u 등). App Store 카피는 전문적인 마케팅입니다. 비격식 표현 사용 금지.
- 문화적 맥락을 존중하세요. 영어의 장난기 있는 어조는 격식을 중시하는 시장(예: ja, de-DE)에서는 조정이 필요할 수 있습니다.
소스 ({source_locale}):
description: """
{description}
"""
keywords: {keywords}
whatsNew: """
{whatsNew}
"""
promotionalText: {promotionalText}
name: {name}
subtitle: {subtitle}
4단계: 번역 업로드
옵션 A: .strings 파일을 통한 일괄 업로드
적절한 디렉토리에 로케일별 .strings 파일을 생성합니다.
버전 현지화 예시:
// nl-NL.strings
"description" = "Je app-beschrijving hier";
"keywords" = "wiskunde,kinderen,tafels,leren";
"whatsNew" = "Bugfixes en verbeteringen";
"promotionalText" = "Leer de tafels van vermenigvuldiging!";
그런 다음 버전 현지화를 업로드합니다:
asc localizations upload --version "VERSION_ID" --path "./localizations"
앱 정보 현지화 예시:
// nl-NL.strings
"subtitle" = "Leer tafels spelenderwijs";
그런 다음 앱 정보 현지화를 업로드합니다:
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
옵션 B: 개별 명령어를 통한 세밀한 제어
# 버전 현지화 필드 (세밀한 제어)
# 결정론성을 위해 명시적 버전 ID를 전달하는 것을 선호합니다.
asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "nl-NL" \
--description "Je beschrijving..." \
--keywords "wiskunde,kinderen,tafels" \
--whats-new "Bugfixes en verbeteringen"
앱 수준 필드의 경우:
# 부제목/이름(앱 정보 현지화)은 앱 정보 현지화를 통해 관리합니다.
# 앱 정보 현지화 .strings + 업로드 흐름을 사용하세요(`asc app-infos localizations ...` 명령어는 없습니다).
#
# 1) 편집: ./app-info-localizations/nl-NL.strings
# "subtitle" = "Leer tafels spelenderwijs";
#
# 2) 업로드:
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
5단계: 확인
# 모든 로케일이 있는지 확인
asc localizations list --version "VERSION_ID" --output table
# 앱 정보 현지화 확인
asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table
문자 수 제한 (업로드 전에 반드시 확인!)
| 필드 | 제한 |
|---|---|
| Name | 30 |
| Subtitle | 30 |
| Keywords | 100 (쉼표로 구분) |
| Description | 4000 |
| What's New | 4000 |
| Promotional Text | 170 |
항상 번역된 텍스트가 제한에 맞는지 업로드 전에 검증하세요. 잘린 텍스트는 전문적이지 않아 보입니다. 번역이 제한을 초과하면 문장 중간이 아니라 번역을 더 짧게 줄이세요.
전체 예제: Roxy Math에 nl-NL 및 ru 추가
# 1) 결정론적으로 ID 확인 ("첫 번째" 행을 자동 선택하지 마세요)
# 이름만 알고 있다면 asc-id-resolver 스킬을 사용하세요.
asc apps list --output table
APP_ID="APP_ID_HERE"
asc versions list --app "$APP_ID" --state PREPARE_FOR_SUBMISSION --output table
VERSION_ID="VERSION_ID_HERE"
asc apps info list --app "$APP_ID" --output table
APP_INFO_ID="APP_INFO_ID_HERE"
# 2) 영어 소스(또는 선택한 소스 로케일) 다운로드
asc localizations download --version "$VERSION_ID" --path "./localizations"
asc localizations download --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --path "./app-info-localizations"
# 3) en-US.strings 읽고 nl-NL 및 ru로 번역 (LLM 단계)
# 4) nl-NL.strings 및 ru.strings를 다음 위치에 작성:
# - ./localizations/ (버전 현지화 필드)
# - ./app-info-localizations/ (부제목/이름/개인정보 필드)
# 5) 모두 업로드
asc localizations upload --version "$VERSION_ID" --path "./localizations"
asc localizations upload --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --path "./app-info-localizations"
# 6) 확인
asc localizations list --version "$VERSION_ID" --output table
asc localizations list --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --output table
에이전트 동작 가이드
- 항상 소스 로케일을 먼저 읽습니다 — 기억이나 가정으로 번역하지 마세요.
- 기존 현지화를 먼저 확인합니다 — 사용자가 업데이트를 요청하지 않는 한 기존 번역을 덮어쓰지 마세요.
- 버전과 앱 정보는 다릅니다 — 버전 필드는
--version "VERSION_ID"아래에 있고, 부제목/이름/개인정보는--app ... --type app-info아래에 있습니다. - 결정론적 ID를 선호합니다 — 명시적으로 요청하지 않는 한
head -1로 ID를 선택하지 마세요. 선택을 위해--output table을 사용하거나asc-id-resolver를 사용하세요. - 업로드 전에 문자 수 제한을 확인합니다. 각 필드의 문자 수를 계산하세요. 제한을 초과하면 더 짧게 다시 번역하세요.
- 키워드는 특별히 취급합니다 — 문자 그대로 번역하지 마세요. 로케일에 적합한 검색어를 조사하세요. 해당 언어로 App Store를 검색하는 사용자의 입장에서 생각하세요.
- 업로드 전에 사용자에게 번역 결과를 보여줍니다 — 승인을 위해 모든 필드 × 로케일의 요약 테이블을 제공하세요. 확인 없이 푸시하지 마세요.
- 여러 언어를 번역하는 경우 한 번에 하나의 로케일씩 처리합니다 — 검토 및 오류 발견이 더 쉽습니다.
- 로케일 업로드가 실패하면 오류를 기록하고 다른 로케일을 계속 처리한 후, 마지막에 모든 실패를 보고합니다.
- 기존 현지화 업데이트의 경우 — 현재 내용을 다운로드하고, 변경될 사항의 차이점(diff)을 보여준 후 승인을 받고 업로드합니다.
참고 사항
- 버전 현지화는 특정 버전에 연결됩니다. 버전이 없으면 먼저 생성하세요.
promotionalText는 새 버전 제출 없이 언제든지 업데이트할 수 있습니다.whatsNew는 첫 번째 버전이 아닌 업데이트에만 관련됩니다.- ID 대신 앱/버전 이름만 알고 있다면
asc-id-resolver스킬을 사용하세요. - 번역 이외의 메타데이터 작업에는
asc-metadata-sync스킬을 사용하세요. - 구독/IAP 표시 이름 현지화에는
asc-subscription-localization스킬을 대신 사용하세요.