¿Qué hace asc localize metadata?
Usa esta habilidad para extraer metadatos de la App Store en inglés (o cualquier idioma origen), traducirlos con un LLM y enviar las traducciones de vuelta a App Store Connect de forma automatizada.
Descubrimiento de comandos y convenciones de salida
- Siempre confirma los flags con
--helppara la versión exacta deasc:asc localizations --helpasc localizations download --helpasc localizations upload --helpasc apps info edit --help
- Prefiere flags largos explícitos (
--app,--version,--version-id,--type,--app-info). - La salida por defecto es JSON; usa
--output tablesolo para pasos de verificación humana. - Prefiere operaciones deterministas basadas en ID. No "elijas la primera fila" con
head -1a menos que el usuario lo acepte explícitamente.
Requisitos previos
- Autenticación configurada (
asc auth logino variables de entornoASC_*) - Conocer el ID de tu app (
asc apps listpara encontrarlo) - Al menos una configuración regional (normalmente en-US) ya tiene metadatos en App Store Connect
Configuraciones regionales soportadas
Configuraciones regionales de App Store Connect para localizaciones de versión e información de la app:
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
Dos tipos de metadatos
Localizaciones de versión (por lanzamiento)
Campos: description, keywords, whatsNew, supportUrl, marketingUrl, promotionalText
Localizaciones de información de la app (a nivel de app, persistentes)
Campos: name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText
Flujo de trabajo
Paso 1: Resolver IDs
# Encontrar el ID de la app
asc apps list --output table
# Encontrar el ID de la última versión
asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table
# o para versión editable:
asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table
# Encontrar el ID de información de la app (para campos a nivel de app como nombre/subtítulo)
asc apps info list --app "APP_ID" --output table
Notas:
- Los campos de localización de versión (descripción, palabras clave, novedades, etc.) son por versión.
- Los campos de información de la app (nombre, subtítulo, URL de privacidad/texto) son a nivel de app y usan
--type app-info. - Si solo tienes nombres (nombre de la app, cadena de versión) y necesitas IDs de forma determinista, usa
asc-id-resolver.
Paso 2: Descargar la configuración regional origen
# Descargar localizaciones de versión a archivos .strings locales
# (description, keywords, whatsNew, promotionalText, supportUrl, marketingUrl, ...)
asc localizations download --version "VERSION_ID" --path "./localizations"
# Descargar localizaciones de información de la app a archivos .strings locales
# (name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText, ...)
asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Esto crea archivos como ./localizations/en-US.strings y ./app-info-localizations/en-US.strings. Si la descarga no está disponible, lee los campos individualmente:
# Listar localizaciones de versión para ver configuraciones regionales existentes y su contenido
asc localizations list --version "VERSION_ID" --output table
Paso 3: Traducir con LLM
Para cada configuración regional destino, traduce el texto origen. Sigue estas reglas:
Directrices de traducción
- Tono y registro: Usa siempre lenguaje formal y cortés. Usa formas de "usted" formales cuando el idioma las distinga (ruso: «вы», alemán: «Sie», francés: «vous», español: «usted», neerlandés: «u», italiano: «Lei», portugués: «você» formal, etc.). Las descripciones de la App Store son texto promocional profesional — nunca uses un registro informal.
- description: Traduce de forma natural, adapta el tono al mercado local. Mantén el formato (saltos de línea, viñetas, emojis). No superes los 4000 caracteres.
- keywords: NO traduzcas literalmente. Investiga qué buscarían los usuarios en esa configuración regional. Separados por comas, máximo 100 caracteres en total. Sin duplicados, sin el nombre de la app (Apple lo añade automáticamente).
- whatsNew: Traduce las notas de la versión. Sé conciso. Máximo 4000 caracteres.
- promotionalText: Traduce el eslogan promocional. Máximo 170 caracteres. Este campo se puede actualizar sin una nueva versión.
- subtitle: Traduce o adapta el eslogan. Máximo 30 caracteres — es muy restrictivo, puede requerir adaptación creativa.
- name: Normalmente conserva el nombre original de la app. Solo traduce si el usuario lo pide explícitamente. Máximo 30 caracteres.
Plantilla de solicitud de traducción al LLM
Para cada configuración regional destino, usa este enfoque:
Traduce los siguientes metadatos de la App Store de {source_locale} a {target_locale}.
Reglas:
- description: Traducción natural y fluida. Conserva el formato (saltos de línea, viñetas, emojis). Máximo 4000 caracteres.
- keywords: NO traduzcas literalmente. Elige palabras clave que los hablantes nativos buscarían en la App Store. Separadas por comas, máximo 100 caracteres en total. No incluyas el nombre de la app.
- whatsNew: Traduce las notas de la versión de forma natural. Máximo 4000 caracteres.
- promotionalText: Traduce el eslogan promocional. Máximo 170 caracteres.
- subtitle: Adapta el eslogan de forma creativa para que quepa en un máximo de 30 caracteres.
- name: Mantén el nombre original de la app a menos que se solicite explícitamente traducirlo. Máximo 30 caracteres.
- Usa lenguaje formal y cortés y formas de "usted" formales (ruso: вы, alemán: Sie, francés: vous, español: usted, neerlandés: u, etc.). El texto de la App Store es promoción profesional — nunca uses un registro informal.
- Respeta el contexto cultural. Un tono divertido en inglés puede necesitar ajustes para mercados formales (p. ej., ja, de-DE).
Origen ({source_locale}):
description: """
{description}
"""
keywords: {keywords}
whatsNew: """
{whatsNew}
"""
promotionalText: {promotionalText}
name: {name}
subtitle: {subtitle}
Paso 4: Subir traducciones
Opción A: Mediante archivos .strings (masivo)
Crea un archivo .strings por configuración regional en el directorio correspondiente.
Ejemplo de localización de versión:
// nl-NL.strings
"description" = "Je app-beschrijving hier";
"keywords" = "wiskunde,kinderen,tafels,leren";
"whatsNew" = "Bugfixes en verbeteringen";
"promotionalText" = "Leer de tafels van vermenigvuldiging!";
Luego sube las localizaciones de versión:
asc localizations upload --version "VERSION_ID" --path "./localizations"
Ejemplo de localización de información de la app:
// nl-NL.strings
"subtitle" = "Leer tafels spelenderwijs";
Luego sube las localizaciones de información de la app:
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Opción B: Mediante comandos individuales (control preciso)
# Campos de localización de versión (control fino).
# Prefiere pasar el ID de versión 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 a nivel de app:
# Subtítulo/nombre (localización de información de la app) se gestiona mediante localizaciones de información de la app.
# Usa el flujo .strings de localización de información de la app + subida (no existe un comando `asc app-infos localizations ...`).
#
# 1) Editar: ./app-info-localizations/nl-NL.strings
# "subtitle" = "Leer tafels spelenderwijs";
#
# 2) Subir:
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Paso 5: Verificar
# Comprobar que todas las configuraciones regionales están presentes
asc localizations list --version "VERSION_ID" --output table
# Comprobar las localizaciones de información de la app
asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table
Límites de caracteres (¡obligatorio validar antes de subir!)
| Campo | Límite |
|---|---|
| Name | 30 |
| Subtitle | 30 |
| Keywords | 100 (separados por comas) |
| Description | 4000 |
| What's New | 4000 |
| Promotional Text | 170 |
Siempre valida que el texto traducido quepa dentro de los límites antes de subir. El texto truncado se ve poco profesional. Si la traducción supera el límite, acórtala — no trunque a mitad de frase.
Ejemplo completo: Añadir nl-NL y ru a Roxy Math
# 1) Resolver IDs de forma determinista (no auto-seleccionar la "primera" fila)
# Si solo tienes nombres, usa la habilidad 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) Descargar el origen en inglés (o la configuración regional origen elegida)
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) Leer en-US.strings, traducir a nl-NL y ru (paso LLM)
# 4) Escribir nl-NL.strings y ru.strings en:
# - ./localizations/ (campos de localización de versión)
# - ./app-info-localizations/ (campos de subtítulo/nombre/privacidad)
# 5) Subir todo
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
Comportamiento del agente
- Siempre comienza leyendo la configuración regional origen — nunca traduzcas de memoria o suposiciones.
- Verifica primero las localizaciones existentes — no sobrescribas traducciones existentes a menos que el usuario pida actualizarlas.
- Versión vs información de la app es diferente — los campos de versión están bajo
--version "VERSION_ID"; subtítulo/nombre/privacidad están bajo--app ... --type app-info. - Prefiere IDs deterministas — no selecciones IDs mediante
head -1a menos que se solicite explícitamente; usa--output tablepara la selección oasc-id-resolver. - Valida los límites de caracteres antes de subir. Cuenta los caracteres de cada campo. Si supera el límite, vuelve a traducir con menos texto.
- Las palabras clave son especiales — no las traduzcas literalmente. Investiga términos de búsqueda apropiados para la configuración regional. Piensa como un usuario que busca en la App Store en ese idioma.
- Muestra las traducciones al usuario antes de subir — presenta una tabla resumen de todos los campos × configuraciones regionales para su aprobación. No publiques sin confirmación.
- Procesa una configuración regional a la vez si traduces muchos idiomas — es más fácil revisar y detectar errores.
- Si falla la subida para una configuración regional, registra el error, continúa con las demás configuraciones, informa de todos los fallos al final.
- Para actualizaciones de localizaciones existentes — descarga la actual, muestra la diferencia de lo que cambiará, obtén aprobación y luego sube.
Notas
- Las localizaciones de versión están vinculadas a una versión específica. Crea la versión primero si no existe.
promotionalTextse puede actualizar en cualquier momento sin enviar una nueva versión.whatsNewsolo es relevante para actualizaciones, no para la primera versión.- Usa la habilidad
asc-id-resolversi solo tienes nombres de app/versión en lugar de IDs. - Usa la habilidad
asc-metadata-syncpara operaciones de metadatos que no sean de traducción. - Para la localización de nombres de visualización de suscripciones/IAP, usa la habilidad
asc-subscription-localization.