Que fait asc localize metadata ?
Utilisez cette compétence pour extraire les métadonnées App Store en anglais (ou toute autre langue source), les traduire via LLM et les repousser automatiquement dans App Store Connect.
Découverte des commandes et conventions de sortie
- Confirmez toujours les options avec
--helppour la version exacte deasc:asc localizations --helpasc localizations download --helpasc localizations upload --helpasc apps info edit --help
- Privilégiez les options longues explicites (
--app,--version,--version-id,--type,--app-info). - La sortie par défaut est JSON ; utilisez
--output tableuniquement pour les étapes de vérification humaine. - Privilégiez les opérations basées sur des identifiants déterministes. Ne « sélectionnez pas la première ligne » via
head -1sauf accord explicite de l'utilisateur.
Prérequis
- Authentification configurée (
asc auth loginou variables d'environnementASC_*) - Connaître l'identifiant de votre application (
asc apps listpour le trouver) - Au moins une locale (généralement en-US) possède déjà des métadonnées dans App Store Connect
Locales prises en charge
Locales App Store Connect pour les localisations de version et d'informations de l'application :
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
Deux types de métadonnées
Localisations de version (par version)
Champs : description, keywords, whatsNew, supportUrl, marketingUrl, promotionalText
Localisations des informations de l'application (niveau application, persistantes)
Champs : name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText
Workflow
Étape 1 : Résoudre les identifiants
# Trouver l'identifiant de l'application
asc apps list --output table
# Trouver l'identifiant de la dernière version
asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table
# ou pour une version modifiable :
asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table
# Trouver l'identifiant des infos de l'application (pour les champs de niveau app comme nom/sous-titre)
asc apps info list --app "APP_ID" --output table
Remarques :
- Les champs de localisation de version (description, keywords, whatsNew, etc.) sont liés à une version spécifique.
- Les champs d'informations de l'application (nom, sous-titre, URL de confidentialité/texte) sont au niveau de l'application et utilisent
--type app-info. - Si vous ne disposez que de noms (nom de l'app, numéro de version) et avez besoin des identifiants de manière déterministe, utilisez
asc-id-resolver.
Étape 2 : Télécharger la locale source
# Télécharger les localisations de version dans des fichiers .strings locaux
# (description, keywords, whatsNew, promotionalText, supportUrl, marketingUrl, ...)
asc localizations download --version "VERSION_ID" --path "./localizations"
# Télécharger les localisations des infos de l'application dans des fichiers .strings locaux
# (name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText, ...)
asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Cela crée des fichiers comme ./localizations/en-US.strings et ./app-info-localizations/en-US.strings. Si le téléchargement est indisponible, lisez les champs individuellement :
# Lister les localisations de version pour voir les locales existantes et leur contenu
asc localizations list --version "VERSION_ID" --output table
Étape 3 : Traduire avec LLM
Pour chaque locale cible, traduisez le texte source. Suivez ces règles :
Consignes de traduction
- Ton et registre : Utilisez toujours un langage formel et poli. Utilisez les formes de vouvoiement là où la langue les distingue (russe : «вы», allemand : «Sie», français : «vous», espagnol : «usted», néerlandais : «u», italien : «Lei», portugais : «você» formel, etc.). Les descriptions App Store sont des textes marketing professionnels — n'utilisez jamais un registre décontracté ou informel.
- description : Traduisez naturellement, adaptez le ton au marché local. Conservez la mise en forme (sauts de ligne, puces, émojis). Restez sous 4000 caractères.
- keywords : Ne traduisez PAS littéralement. Recherchez ce que les utilisateurs de cette locale rechercheraient. Séparés par des virgules, max 100 caractères au total. Pas de doublons, pas de nom d'app (Apple l'ajoute automatiquement).
- whatsNew : Traduisez les notes de version. Restez concis. Max 4000 caractères.
- promotionalText : Traduisez l'accroche marketing. Max 170 caractères. Peut être mis à jour sans nouvelle version.
- subtitle : Traduisez ou adaptez le slogan. Max 30 caractères — c'est très limité, une adaptation créative peut être nécessaire.
- name : Conservez généralement le nom original de l'application. Ne traduisez que si l'utilisateur le demande explicitement. Max 30 caractères.
Modèle de prompt de traduction LLM
Pour chaque locale cible, utilisez cette approche :
Traduisez les métadonnées App Store suivantes de {source_locale} vers {target_locale}.
Règles :
- description : Traduction naturelle et fluide. Conservez la mise en forme (sauts de ligne, puces, émojis). Max 4000 caractères.
- keywords : Ne traduisez PAS littéralement. Choisissez des mots-clés que les locuteurs natifs rechercheraient dans l'App Store. Séparés par des virgules, max 100 caractères au total. N'incluez pas le nom de l'application.
- whatsNew : Traduisez les notes de version naturellement. Max 4000 caractères.
- promotionalText : Traduisez l'accroche marketing. Max 170 caractères.
- subtitle : Adaptez le slogan de manière créative pour tenir dans 30 caractères max.
- name : Conservez le nom original de l'application sauf demande explicite de traduction. Max 30 caractères.
- Utilisez un langage formel et poli ainsi que les formes de vouvoiement (russe : вы, allemand : Sie, français : vous, espagnol : usted, néerlandais : u, etc.). Le texte App Store est une communication marketing professionnelle — n'utilisez jamais un registre informel.
- Respectez le contexte culturel. Un ton ludique en anglais peut nécessiter un ajustement pour les marchés formels (par exemple, ja, de-DE).
Source ({source_locale}) :
description : """
{description}
"""
keywords : {keywords}
whatsNew : """
{whatsNew}
"""
promotionalText : {promotionalText}
name : {name}
subtitle : {subtitle}
Étape 4 : Téléverser les traductions
Option A : Via les fichiers .strings (en masse)
Créez un fichier .strings par locale dans le répertoire approprié.
Exemple de localisation de version :
// nl-NL.strings
"description" = "Je app-beschrijving hier";
"keywords" = "wiskunde,kinderen,tafels,leren";
"whatsNew" = "Bugfixes en verbeteringen";
"promotionalText" = "Leer de tafels van vermenigvuldiging!";
Ensuite, téléversez les localisations de version :
asc localizations upload --version "VERSION_ID" --path "./localizations"
Exemple de localisation des infos de l'application :
// nl-NL.strings
"subtitle" = "Leer tafels spelenderwijs";
Ensuite, téléversez les localisations des infos de l'application :
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Option B : Via des commandes individuelles (contrôle fin)
# Champs de localisation de version (contrôle fin).
# Privilégiez le passage explicite de l'ID de version pour le déterminisme.
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"
Pour les champs au niveau de l'application :
# Le sous-titre/le nom (localisation des infos de l'application) est géré via les localisations des infos de l'application.
# Utilisez le flux .strings + téléversement des localisations des infos de l'application (il n'y a pas de commande `asc app-infos localizations ...`).
#
# 1) Modifiez : ./app-info-localizations/nl-NL.strings
# "subtitle" = "Leer tafels spelenderwijs";
#
# 2) Téléversez :
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
Étape 5 : Vérifier
# Vérifier que toutes les locales sont présentes
asc localizations list --version "VERSION_ID" --output table
# Vérifier les localisations des infos de l'application
asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table
Limites de caractères (à vérifier avant téléversement !)
| Champ | Limite |
|---|---|
| Nom (name) | 30 |
| Sous-titre (subtitle) | 30 |
| Mots-clés (keywords) | 100 (séparés par des virgules) |
| Description | 4000 |
| Notes de version (whatsNew) | 4000 |
| Texte promotionnel (promotionalText) | 170 |
Validez toujours que le texte traduit respecte les limites avant de téléverser. Un texte tronqué donne un aspect non professionnel. Si la traduction dépasse la limite, raccourcissez-la — ne tronquez pas au milieu d'une phrase.
Exemple complet : Ajouter nl-NL et ru à Roxy Math
# 1) Résoudre les identifiants de manière déterministe (ne pas sélectionner automatiquement la « première » ligne)
# Si vous ne disposez que de noms, utilisez la compétence asc-id-resolver.
asc apps list --output table
APP_ID="ID_DE_L_APP"
asc versions list --app "$APP_ID" --state PREPARE_FOR_SUBMISSION --output table
VERSION_ID="ID_DE_LA_VERSION"
asc apps info list --app "$APP_ID" --output table
APP_INFO_ID="ID_DES_INFOS_APP"
# 2) Télécharger la source anglaise (ou votre locale source choisie)
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) Lire en-US.strings, traduire vers nl-NL et ru (étape LLM)
# 4) Écrire nl-NL.strings et ru.strings dans :
# - ./localizations/ (champs de localisation de version)
# - ./app-info-localizations/ (champs sous-titre/nom/confidentialité)
# 5) Tout téléverser
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) Vérifier
asc localizations list --version "$VERSION_ID" --output table
asc localizations list --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --output table
Comportement de l'agent
- Commencez toujours par lire la locale source — ne traduisez jamais de mémoire ou par supposition.
- Vérifiez d'abord les localisations existantes — n'écrasez pas les traductions existantes sauf si l'utilisateur demande de les mettre à jour.
- Version vs informations de l'application sont différents — les champs de version se trouvent sous
--version "VERSION_ID"; le sous-titre/nom/confidentialité se trouvent sous--app ... --type app-info. - Privilégiez les identifiants déterministes — ne sélectionnez pas les identifiants via
head -1sauf demande explicite ; utilisez--output tablepour la sélection ouasc-id-resolver. - Validez les limites de caractères avant de téléverser. Comptez les caractères pour chaque champ. Si la limite est dépassée, retraduction plus courte.
- Les mots-clés sont spéciaux — ne les traduisez pas littéralement. Recherchez des termes de recherche adaptés à la locale. Pensez comme un utilisateur recherchant dans l'App Store dans cette langue.
- Montrez les traductions à l'utilisateur avant de téléverser — présentez un tableau récapitulatif de tous les champs × locales pour approbation. Ne poussez pas sans confirmation.
- Traitez une locale à la fois si vous traduisez plusieurs langues — plus facile à réviser et à détecter les erreurs.
- Si le téléversement échoue pour une locale, enregistrez l'erreur, continuez avec les autres locales, signalez tous les échecs à la fin.
- Pour les mises à jour de localisations existantes — téléchargez les actuelles, affichez la différence de ce qui va changer, obtenez l'approbation, puis téléversez.
Remarques
- Les localisations de version sont liées à une version spécifique. Créez d'abord la version si elle n'existe pas.
promotionalTextpeut être mis à jour à tout moment sans soumettre une nouvelle version.whatsNewn'est pertinent que pour les mises à jour, pas pour la première version.- Utilisez la compétence
asc-id-resolversi vous ne disposez que des noms d'application/de version au lieu des identifiants. - Utilisez la compétence
asc-metadata-syncpour les opérations de métadonnées non liées à la traduction. - Pour la localisation des noms d'affichage des abonnements/IAP, utilisez plutôt la compétence
asc-subscription-localization.