asc メタデータのローカライズ
このスキルを使うと、英語(または任意のソースロケール)の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を使用すること。 - 決定論的なIDベースの操作を優先すること。ユーザーが明示的に同意しない限り、
head -1で「最初の行を選択」しないこと。
前提条件
- 認証が設定されていること(
asc auth loginまたはASC_*環境変数) - アプリIDがわかっていること(
asc apps listで確認) - 少なくとも1つのロケール(通常はen-US)に、App Store Connect上でメタデータが存在していること
サポートされるロケール
バージョンおよびアプリ情報のローカライズでサポートされる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
2種類のメタデータ
バージョンローカライゼーション(リリースごと)
フィールド: 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
注意点:
- バージョンローカライゼーションフィールド(description、keywords、whatsNewなど)はバージョンごとに異なります。
- アプリ情報フィールド(name、subtitle、プライバシーURL/テキスト)はアプリレベルであり、
--type app-infoを使用します。 - 名前(アプリ名、バージョン文字列)しかなく、IDを決定論的に取得する必要がある場合は、
asc-id-resolverを使用してください。
ステップ2: ソースロケールをダウンロードする
# バージョンローカライゼーションをローカルの.stringsファイルにダウンロード
# (description、keywords、whatsNew、promotionalText、supportUrl、marketingUrlなど)
asc localizations download --version "VERSION_ID" --path "./localizations"
# アプリ情報ローカライゼーションをローカルの.stringsファイルにダウンロード
# (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のようなファイルが作成されます。ダウンロードが利用できない場合は、フィールドを個別に読み取ります:
# バージョンローカライゼーションを一覧表示して、既存のロケールとその内容を確認
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を検索しているユーザーの立場になって考えてください。
- 翻訳をアップロード前にユーザーに表示すること — 承認のために、すべてのフィールド×ロケールの要約表を提示してください。確認なしにプッシュしないでください。
- 多くの言語を翻訳する場合は、一度に1つのロケールを処理すること — レビューが容易になり、エラーを見つけやすくなります。
- ロケールのアップロードが失敗した場合 — エラーをログに記録し、他のロケールを続行し、最後にすべての失敗を報告してください。
- 既存のローカライゼーションの更新の場合 — 現在のものをダウンロードし、変更点の差分を表示し、承認を得てからアップロードしてください。
注意点
- バージョンローカライゼーションは特定のバージョンに紐付いています。バージョンが存在しない場合は先に作成してください。
promotionalTextは新しいバージョンの提出なしでいつでも更新できます。whatsNewは初回バージョンではなく、アップデートにのみ関連します。- アプリ/バージョン名しかIDがわからない場合は、
asc-id-resolverスキルを使用してください。 - 翻訳以外のメタデータ操作には、
asc-metadata-syncスキルを使用してください。 - サブスクリプション/IAPの表示名のローカライゼーションには、代わりに
asc-subscription-localizationスキルを使用してください。