O que asc localize metadata faz?
Use esta skill para extrair metadados da App Store em inglês (ou qualquer idioma de origem), traduzi-los com LLM e enviar as traduções de volta para o App Store Connect — tudo automatizado.
Descoberta de comandos e convenções de saída
- Sempre confirme as flags com
--helppara a versão exata doasc:asc localizations --helpasc localizations download --helpasc localizations upload --helpasc apps info edit --help
- Prefira flags longas explícitas (
--app,--version,--version-id,--type,--app-info). - A saída padrão é JSON; use
--output tableapenas para etapas de verificação humana. - Prefira operações determinísticas baseadas em IDs. Não "pegue a primeira linha" via
head -1a menos que o usuário concorde explicitamente.
Pré-condições
- Autenticação configurada (
asc auth loginou variáveis de ambienteASC_*) - Saiba o ID do seu aplicativo (
asc apps listpara encontrá-lo) - Pelo menos um idioma (normalmente en-US) já possui metadados no App Store Connect
Idiomas suportados
Idiomas do App Store Connect para localizações de versão e informações do aplicativo:
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
Dois tipos de metadados
Localizações de Versão (por lançamento)
Campos: description, keywords, whatsNew, supportUrl, marketingUrl, promotionalText
Localizações de Informações do Aplicativo (nível do app, persistente)
Campos: name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText
Fluxo de trabalho
Etapa 1: Resolver IDs
# Encontrar ID do aplicativo
asc apps list --output table
# Encontrar ID da versão mais recente
asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table
# ou para versão editável:
asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table
# Encontrar ID das informações do aplicativo (para campos de nível do app como nome/subtítulo)
asc apps info list --app "APP_ID" --output table
Observações:
- Campos de localização de versão (description, keywords, whatsNew, etc.) são por versão.
- Campos de informações do aplicativo (nome, subtítulo, URLs de privacidade/texto) são de nível do app e usam
--type app-info. - Se você tiver apenas nomes (nome do app, string da versão) e precisar de IDs deterministicamente, use
asc-id-resolver.
Etapa 2: Baixar o idioma de origem
# Baixar localizações de versão para arquivos .strings locais
# (description, keywords, whatsNew, promotionalText, supportUrl, marketingUrl, ...)
asc localizations download --version "VERSION_ID" --path "./localizations"
# Baixar localizações de informações do aplicativo para arquivos .strings locais
# (nome, subtítulo, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText, ...)
asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Isso cria arquivos como ./localizations/en-US.strings e ./app-info-localizations/en-US.strings. Se o download não estiver disponível, leia os campos individualmente:
# Listar localizações de versão para ver os idiomas existentes e seu conteúdo
asc localizations list --version "VERSION_ID" --output table
Etapa 3: Traduzir com LLM
Para cada idioma de destino, traduza o texto de origem. Siga estas regras:
Diretrizes de tradução
- Tom e Registro: Sempre use linguagem formal e educada. Use formas formais de "você" onde o idioma as distingue (Russo: «вы», Alemão: «Sie», Francês: «vous», Espanhol: «usted», Holandês: «u», Italiano: «Lei», Português: «você» formal, etc.). Descrições da App Store são textos de marketing profissionais — nunca use registro casual ou informal.
- description: Traduza naturalmente, adapte o tom ao mercado local. Mantenha a formatação (quebras de linha, marcadores, emojis). Fique dentro de 4000 caracteres.
- keywords: NÃO traduza literalmente. Pesquise quais termos os usuários daquele idioma pesquisariam. Separados por vírgula, máximo de 100 caracteres no total. Sem duplicatas, sem nome do aplicativo (a Apple adiciona automaticamente).
- whatsNew: Traduza as notas de versão. Mantenha conciso. Máximo de 4000 caracteres.
- promotionalText: Traduza o gancho de marketing. Máximo de 170 caracteres. Pode ser atualizado sem uma nova versão.
- subtitle: Traduza ou adapte o slogan. Máximo de 30 caracteres — é muito restrito, pode exigir adaptação criativa.
- name: Geralmente mantenha o nome original do aplicativo. Só traduza se o usuário pedir explicitamente. Máximo de 30 caracteres.
Modelo de prompt para tradução com LLM
Para cada idioma de destino, use esta abordagem:
Traduza os seguintes metadados da App Store de {source_locale} para {target_locale}.
Regras:
- description: Tradução natural e fluente. Preserve a formatação (quebras de linha, marcadores, emojis). Máximo de 4000 caracteres.
- keywords: NÃO traduza literalmente. Escolha palavras-chave que falantes nativos pesquisariam na App Store. Separadas por vírgula, máximo de 100 caracteres no total. Não inclua o nome do aplicativo.
- whatsNew: Traduza as notas de versão naturalmente. Máximo de 4000 caracteres.
- promotionalText: Traduza o slogan de marketing. Máximo de 170 caracteres.
- subtitle: Adapte o slogan criativamente para caber em no máximo 30 caracteres.
- name: Mantenha o nome original do aplicativo, a menos que seja solicitado explicitamente a traduzi-lo. Máximo de 30 caracteres.
- Use linguagem formal e educada e formas formais de "você" (Russo: вы, Alemão: Sie, Francês: vous, Espanhol: usted, Holandês: u, etc.). O texto da App Store é marketing profissional — nunca use registro informal.
- Respeite o contexto cultural. Um tom lúdico em inglês pode precisar de ajustes para mercados formais (ex.: ja, de-DE).
Fonte ({source_locale}):
description: """
{description}
"""
keywords: {keywords}
whatsNew: """
{whatsNew}
"""
promotionalText: {promotionalText}
name: {name}
subtitle: {subtitle}
Etapa 4: Enviar traduções
Opção A: Via arquivos .strings (em lote)
Crie um arquivo .strings por idioma no diretório apropriado.
Exemplo de localização de versão:
// nl-NL.strings
"description" = "Je app-beschrijving hier";
"keywords" = "wiskunde,kinderen,tafels,leren";
"whatsNew" = "Bugfixes en verbeteringen";
"promotionalText" = "Leer de tafels van vermenigvuldiging!";
Em seguida, envie as localizações de versão:
asc localizations upload --version "VERSION_ID" --path "./localizations"
Exemplo de localização de informações do aplicativo:
// nl-NL.strings
"subtitle" = "Leer tafels spelenderwijs";
Em seguida, envie as localizações de informações do aplicativo:
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Opção B: Via comandos individuais (controle refinado)
# Campos de localização de versão (controle refinado).
# Prefira passar o ID da versão explícito para determinismo.
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"
Para campos de nível do aplicativo:
# Subtítulo/nome (localização de informações do aplicativo) é gerenciado via localizações de informações do aplicativo.
# Use o fluxo de .strings + upload de localizações de informações do aplicativo (não existe comando `asc app-infos localizations ...`).
#
# 1) Edite: ./app-info-localizations/nl-NL.strings
# "subtitle" = "Leer tafels spelenderwijs";
#
# 2) Envie:
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Etapa 5: Verificar
# Verificar se todos os idiomas estão presentes
asc localizations list --version "VERSION_ID" --output table
# Verificar localizações de informações do aplicativo
asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table
Limites de caracteres (validar antes do envio!)
| Campo | Limite |
|---|---|
| Nome | 30 |
| Subtítulo | 30 |
| Palavras-chave | 100 (separadas por vírgula) |
| Descrição | 4000 |
| Novidades | 4000 |
| Texto promocional | 170 |
Sempre valide se o texto traduzido cabe nos limites antes de enviar. Texto truncado parece amador. Se a tradução exceder o limite, encurte-a — não trunque no meio da frase.
Exemplo completo: Adicionar nl-NL e ru ao Roxy Math
# 1) Resolver IDs deterministicamente (não escolher automaticamente a "primeira" linha)
# Se você tiver apenas nomes, use a skill asc-id-resolver.
asc apps list --output table
APP_ID="APP_ID_AQUI"
asc versions list --app "$APP_ID" --state PREPARE_FOR_SUBMISSION --output table
VERSION_ID="VERSION_ID_AQUI"
asc apps info list --app "$APP_ID" --output table
APP_INFO_ID="APP_INFO_ID_AQUI"
# 2) Baixar fonte em inglês (ou o idioma de origem escolhido)
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) Ler en-US.strings, traduzir para nl-NL e ru (etapa LLM)
# 4) Escrever nl-NL.strings e ru.strings em:
# - ./localizations/ (campos de localização de versão)
# - ./app-info-localizations/ (campos de subtítulo/nome/privacidade)
# 5) Enviar tudo
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) Verificar
asc localizations list --version "$VERSION_ID" --output table
asc localizations list --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --output table
Comportamento do agente
- Sempre comece lendo o idioma de origem — nunca traduza de memória ou suposições.
- Verifique as localizações existentes primeiro — não sobrescreva traduções existentes a menos que o usuário peça para atualizá-las.
- Versão vs informações do aplicativo são diferentes — campos de versão ficam sob
--version "VERSION_ID"; subtítulo/nome/privacidade ficam sob--app ... --type app-info. - Prefira IDs determinísticos — não selecione IDs via
head -1a menos que explicitamente solicitado; use--output tablepara seleção ouasc-id-resolver. - Valide os limites de caracteres antes de enviar. Conte caracteres de cada campo. Se ultrapassar o limite, retraduza de forma mais curta.
- Palavras-chave são especiais — não traduza literalmente. Pesquise termos de busca apropriados para o idioma. Pense como um usuário pesquisando na App Store naquele idioma.
- Mostre as traduções ao usuário antes de enviar — apresente uma tabela resumo de todos os campos × idiomas para aprovação. Não envie sem confirmação.
- Processe um idioma por vez se estiver traduzindo muitos idiomas — mais fácil revisar e capturar erros.
- Se o envio falhar para um idioma, registre o erro, continue com os outros idiomas, relate todas as falhas no final.
- Para atualizações de localizações existentes — baixe o atual, mostre o diff do que será alterado, obtenha aprovação, depois envie.
Observações
- Localizações de versão estão vinculadas a uma versão específica. Crie a versão primeiro se ela não existir.
promotionalTextpode ser atualizado a qualquer momento sem o envio de uma nova versão.whatsNewé relevante apenas para atualizações, não para a primeira versão.- Use a skill
asc-id-resolverse você tiver apenas nomes de aplicativos/versões em vez de IDs. - Use a skill
asc-metadata-syncpara operações de metadados que não envolvam tradução. - Para localização de nomes de exibição de assinaturas/IAP, use a skill
asc-subscription-localization.