asc-localize-metadata

asc localize metadata

このスキルを使用すると、英語（またはその他のソースロケール）の App Store メタデータを取得し、LLM で翻訳して、App Store Connect に翻訳を自動で反映できます。

コマンドの確認と出力規約

• 使用する asc のバージョンで、必ず --help を使ってフラグを確認してください。
  • asc localizations --help
  • asc localizations download --help
  • asc localizations upload --help
  • asc apps info edit --help
• 明示的なロングフラグ（--app、--version、--version-id、--type、--app-info）を優先してください。
• 出力形式のデフォルトは TTY を考慮します。対話型ターミナルではテーブル、CI やその他の非対話型環境では JSON が出力されます。形式が重要な場合は、明示的に --output を指定してください。
• 決定的な ID ベースの操作を優先してください。ユーザーが明示的に同意しない限り、head -1 を使って「先頭の行を選ぶ」ことは避けてください。

前提条件

• 認証を設定済みであること（asc auth login または ASC_* 環境変数）
• アプリ ID がわかっていること（asc apps list で確認できます）
• App Store Connect に少なくとも 1 つのロケール（通常は en-US）のメタデータがあること

対応ロケール

バージョンおよびアプリ情報のローカライズで App Store Connect が対応するロケール：

ar-SA, bn-BD, ca, cs, da, de-DE, el, en-AU, en-CA, en-GB,
en-US, es-ES, es-MX, fi, fr-CA, fr-FR, gu-IN, he, hi, hr,
hu, id, it, ja, kn-IN, ko, ml-IN, mr-IN, ms, nl-NL, no,
or-IN, pa-IN, pl, pt-BR, pt-PT, ro, ru, sk, sl-SI, sv,
ta-IN, te-IN, th, tr, uk, ur-PK, vi, zh-Hans, zh-Hant

2 種類のメタデータ

バージョンのローカライズ（リリースごと）

フィールド：description、keywords、whatsNew、supportUrl、marketingUrl、promotionalText

アプリ情報のローカライズ（アプリ単位、永続）

フィールド：name、subtitle、privacyPolicyUrl、privacyChoicesUrl、privacyPolicyText

ワークフロー

ステップ 1：ID を特定する

# Find app ID
asc apps list --output table

# Find latest version ID
asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table
# or for editable version:
asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table

# Find app info ID (for app-level fields like name/subtitle)
asc apps info list --app "APP_ID" --output table

注意：

• バージョンのローカライズのフィールド（description、keywords、whatsNew など）は、バージョンごとに設定されます。
• アプリ情報のフィールド（name、subtitle、プライバシー URL／テキスト）はアプリ単位で設定され、--type app-info を使用します。
• 名前（アプリ名、バージョン文字列）しかなく、ID を決定的に特定する必要がある場合は、asc-id-resolver を使用してください。

ステップ 2：ソースロケールをダウンロードする

# Download version localizations to local .strings files
# (description, keywords, whatsNew, promotionalText, supportUrl, marketingUrl, ...)
asc localizations download --version "VERSION_ID" --path "./localizations"

# Download app-info localizations to local .strings files
# (name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText, ...)
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 のようなファイルが作成されます。ダウンロードできない場合は、各フィールドを個別に読み取ってください。

# List version localizations to see existing locales and their content
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 翻訳プロンプトのテンプレート

各対象ロケールについて、次の方法を使用してください。

Translate the following App Store metadata from {source_locale} to {target_locale}.

Rules:
- description: Natural, fluent translation. Preserve formatting (line breaks, bullets, emoji). Max 4000 chars.
- keywords: Do NOT literally translate. Choose keywords native speakers would search for in the App Store. Comma-separated, max 100 chars total. Do not include the app name.
- whatsNew: Translate release notes naturally. Max 4000 chars.
- promotionalText: Translate marketing tagline. Max 170 chars.
- subtitle: Adapt tagline creatively to fit 30 chars max.
- name: Keep the original app name unless explicitly requested to translate it. Max 30 chars.
- Use formal, polite language and formal "you" forms (Russian: вы, German: Sie, French: vous, Spanish: usted, Dutch: u, etc.). App Store copy is professional marketing — never use informal register.
- Respect cultural context. A playful tone in English may need adjustment for formal markets (e.g., ja, de-DE).

Source ({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：個別のコマンドを使用（細かく制御）

# Version localization fields (fine control).
# Prefer passing the explicit version ID for determinism.
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"

アプリ単位のフィールドの場合：

# Subtitle/name (app-info localization) is managed via app-info localizations.
# Use the app-info localization .strings + upload flow; there is no app-infos localizations command.
#
# 1) Edit: ./app-info-localizations/nl-NL.strings
# "subtitle" = "Leer tafels spelenderwijs";
#
# 2) Upload:
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"

ステップ 5：確認する

# Check all locales are present
asc localizations list --version "VERSION_ID" --output table

# Check app info localizations
asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table

文字数制限（アップロード前に必ず確認してください！）

フィールド	制限
名前	30
サブタイトル	30
キーワード	100（カンマ区切り）
説明	4000
新機能	4000
プロモーションテキスト	170

アップロード前に、翻訳したテキストが制限内に収まっているか必ず確認してください。 テキストが途中で切れていると、プロらしく見えません。翻訳が制限を超える場合は、文の途中で切らずに短くしてください。

全例：Roxy Math に nl-NL と ru を追加する

# 1) Resolve IDs deterministically (do not auto-pick the "first" row)
# If you only have names, use asc-id-resolver skill.
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) Download English source (or your chosen source locale)
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) Read en-US.strings, translate to nl-NL and ru (LLM step)

# 4) Write nl-NL.strings and ru.strings to:
#    - ./localizations/ (version localization fields)
#    - ./app-info-localizations/ (subtitle/name/privacy fields)

# 5) Upload all
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) Verify
asc localizations list --version "$VERSION_ID" --output table
asc localizations list --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --output table

エージェントの動作

1. 必ず最初にソースロケールを読み込んでください — 記憶や推測をもとに翻訳しないでください。
2. まず既存のローカライズを確認してください — ユーザーから更新を依頼されない限り、既存の翻訳を上書きしないでください。
3. バージョンと app-info は異なります — バージョンのフィールドは --version "VERSION_ID" の下にあり、サブタイトル／名前／プライバシーは --app ... --type app-info の下にあります。
4. 決定的な ID を優先してください — 明示的に依頼されない限り、head -1 で ID を選択しないでください。選択には --output table または asc-id-resolver を使用してください。
5. アップロード前に文字数制限を確認してください。 各フィールドの文字数を数えます。制限を超えている場合は、短くなるように翻訳し直してください。
6. キーワードは特別です — 文字どおりに翻訳しないでください。ロケールに適した検索語を調べ、その言語で App Store を検索するユーザーの立場で考えてください。
7. アップロード前に翻訳をユーザーに提示してください — 承認を得るため、すべてのフィールドとロケールをまとめた表を提示してください。確認なしに反映しないでください。
8. 多数の言語を翻訳する場合は、ロケールごとに処理してください — 確認しやすく、誤りにも気づきやすくなります。
9. あるロケールのアップロードに失敗した場合 — エラーを記録し、ほかのロケールの処理を続け、最後にすべての失敗を報告してください。
10. 既存のローカライズを更新する場合 — 現在の内容をダウンロードし、変更箇所の差分を提示して承認を得てからアップロードしてください。

注意事項

• バージョンのローカライズは特定のバージョンに紐づいています。バージョンが存在しない場合は、先に作成してください。
• promotionalText は、新しいバージョンを提出しなくてもいつでも更新できます。
• whatsNew はアップデートの場合にのみ関係し、初回バージョンでは関係ありません。
• アプリ名やバージョン名しかわからず、ID がわからない場合は asc-id-resolver スキルを使用してください。
• 翻訳以外のメタデータ操作には asc-metadata-sync スキルを使用してください。
• サブスクリプション／IAP の表示名のローカライズには、代わりに asc-subscription-localization スキルを使用してください。