shopify-alt-text

Shopify Alt Text

Shopify ストア全体で、欠落している画像の代替テキストを補完します。代替テキストは、まずアクセシビリティ要件（スクリーンリーダーが読み上げます）であり、次に画像 SEO のシグナルです。このスキルは代替テキストがない画像を補完します。すでに存在する代替テキストを書き換えることはありません。

SEO タイトルと説明を補完する姉妹スキルは shopify-seo-metadata です。同じセーフモードの方針を採用し、対象フィールドが異なります。全商品カタログのうち代替テキストがない画像の数を測定する FIND ステージ（対象を一括処理する前の計測）は、shopify-catalog-audit が担当します。

1つの更新処理、2つの検索方法

Shopify ストアでは画像が2か所に保存されていますが、どちらも同じ更新処理で書き込みます。商品画像も Files ライブラリの画像も MediaImage ノードで、File のサブタイプであるため、どちらも単一の fileUpdate で alt を設定できます。商品メディア専用の代替テキスト更新処理を覚える必要はありません。

• fileUpdate が唯一の書き込み処理です。 画像の MediaImage GID と新しい alt を指定します。これは両方の検索元ツールが最終的に使用する書き込み方法です。（Shopify の旧 productUpdateMedia は shopify.dev で非推奨です。 代替テキストの設定には使用しないでください。）
• 画像を検索する方法は2つ、修正する方法は1つです。
  • 商品メディア： 商品をページネーションし、product.media 内の各 MediaImage を読み取ります。read_products が必要です。
  • Files ライブラリ： files 接続をページネーションします（Content → Files：テーマセクション、メタオブジェクト、リッチテキスト、コレクションバナー）。read_files が必要です。
  • どちらも MediaImage GID を返します。そのまま fileUpdate に渡してください。

両方の検索方法でのカウント、取得、更新、検証の詳しい手順は references/queries.md を参照してください。

ストアへのアクセス

Admin API にアクセスするすべてのスキルは、この定型文から始めます。方法は2つあります。どちらかを選んでください。

方法 A、カスタムアプリのトークン（スクリプトで実行可能）。 Shopify 管理画面で、Settings → Apps and sales channels → Develop apps の順に移動してアプリを作成し、以下の最小限のスコープを付与してから、アプリをインストールし、Admin API アクセストークンをコピーします。環境変数にエクスポートし、コミット対象のファイルには決して書き込まないでください。

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # keep it in the env, not on disk

GraphQL エンドポイントを呼び出します（このスキルに必要な最小限のスコープは、商品画像の所有元を列挙するための read_products、Files ライブラリをページネーションするための read_files、および fileUpdate が両方の代替テキストを書き込むための write_files です）。

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

方法 B、Shopify CLI OAuth（トークンを保存しません）。 shopify store auth --store $SHOPIFY_STORE --scopes read_products,read_files,write_files を実行し、続けて shopify store execute を実行して、検証済みの操作を実行します。オーナーが対話形式でログインする、トークンを保存しないストアに適しています。

ツールキットの事前確認。 方法 B は Shopify CLI を使用します。まず shopify version を実行し、インストールされていない場合はインストールしてください。Admin GraphQL スキーマ全体と検証済みの実行には、このスキルと Shopify 公式 AI ツールキットプラグインを併用してください。Claude Code では claude plugin list を確認し、見つからない場合は次を実行します。

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

推奨ですが必須ではありません。方法 A に必要なのは curl とトークンだけです。ツールキットはエージェントに API を提供し、このスキルは手順を提供します。

スクリプトではなくレシピ

これはプログラムではなくレシピです。 リファレンス内の GraphQL ブロックは、コピーして調整するための出発点です。作業ごとに現在のスキーマに合わせて使い捨てコードを書き、実行して破棄してください。Shopify がスキーマを変更するとひそかに劣化する、常設のバイナリをリリースしないでください。

セーフモード／プレビュー／検証の原則

これを単独で明記し、毎回実行してください。これは稼働中のストアに対する一括書き込みです。問題のない一括処理とサポートチケットの発生を分けるのは、慎重な運用です。

1. 不足分だけを補い、決して上書きしないでください。 alt が null、または空白をトリミングした後に空である場合に限り、画像を候補として扱います。すでに alt テキストがある画像は、たとえ質が低くても対象外です。既存の alt を上書きするのは、個々の画像について人間が意図的に判断する別の作業であり、一括処理のデフォルトではありません。
2. まず読み取り専用の件数をプレビューしてください。 データを変更する前に、これから対象とする検索パスの件数クエリを実行し、結果の数値を確認します。妥当性を確認してください。商品が 300 件あるストアで「商品画像のうち alt が未設定のものが 1,900 件」という結果はあり得ますが、同じストアで「未設定が 40,000 件」となる場合、フィルターが間違っています（おそらく画像以外のファイルや、すでにキャプションがある画像まで数えています）。想定を大きく上回る件数が出たら、処理を止めて対象範囲を見直してください。続行してはいけません。
3. 実際に 1 トークンの補完を行い、生成 API キーを事前に検証してください。 LLM で画像にキャプションを付ける場合、一括処理の前に実際に 1 回、低コストの補完リクエストを送り、200 が返ることを確認します。models.list や認証のみの確認を信頼しないでください。モデル一覧を取得できるキーでも、実際の補完では失敗することがあります（課金、モデルごとのアクセス権、組織の制限など）。事前確認しないと、一括処理で 400 件の画像を処理した後に初めて問題が分かることになります。
4. すべての書き込みを記録し、Admin API で検証してください。 問題のあるバッチを監査・元に戻せるよう、書き込みごとに記録（画像の GID、検索パス、変更前の alt、変更後の alt、ステータス）を保持します。書き込み後、同じ画像を admin/api/.../graphql.json 経由で再クエリし、alt が設定されていることを確認してください。ストアフロントは CDN にキャッシュされているため、数分間は古い（空の）alt が表示されます。これは書き込みが反映された証拠にはなりません。参照資料に読み戻し用のクエリがあります。
5. Admin API アクセストークンや生成キーを表示したり、コミットしたりしないでください。 両方とも環境変数から読み取ってください。

適切な alt テキストとは

alt テキストは、画像を見られない人に向けて画像を説明するものです。キーワードを詰め込んだり、商品の宣伝文句を繰り返したりする場所ではありません。

• マーケティング文句ではなく、画像を説明してください。 「真鍮製ファスナー付きの茶色のレザーボストンバッグ、側面から見たところ」のように記述し、「高級な手作りバッグ、送料無料、今すぐ購入」のような表現は避けてください。
• 長さは約 125 文字未満にしてください。 スクリーンリーダーは文字列全体を読み上げるため、長い alt は聞く人に負担をかけます。スクリーンリーダーに関する多くのガイダンスでは、実用上の上限を約 125 文字としています。生成したキャプションは、書き込む前に 125 文字以内にしてください。
• キーワードを詰め込まないでください。 商品名に検索語句の一覧を加えて繰り返すと、alt テキスト本来のアクセシビリティ用途を損ない、検索エンジンにはスパムのように見えます。自然な説明を 1 つだけ記述してください。
• 装飾画像や重複画像は除外してください。 純粋な背景テクスチャやスペーサーにはキャプションではなく、空の alt（alt=""）を設定します。1 つの商品にほぼ同じ角度の画像が 5 枚ある場合、それぞれに異なる段落を付ける必要はありません。視覚的に見たときに気づく違いだけを示してください（「正面」「背面」「モデル着用」など）。
• 「画像」「写真」などの前置きを付けないでください。 スクリーンリーダーはすでに画像であることを読み上げるため、この前置きは冗長です。生成ツールが付け加えた場合は削除してください。

画像からキャプションを生成する場合（ビジョンモデルを使用する場合）でも、上記のセーフモードのルールに従って、すべての書き込みを制御してください。標準的なガイダンスについては、W3C WAI のalt テキスト決定木を参照してください。

参考資料

• references/queries.md：両方の検索パス（商品メディアと Files ライブラリ）に対応した、件数確認／取得／更新／検証のレシピ。ページネーションと MIME フィルタリングを使用し、すべての書き込みを fileUpdate 経由で行います。

来歴とメンテナンス

最終確認日：2026-07-05。GraphQL は Admin API 2025-07 に固定されています。Shopify は四半期ごとに順次バージョンを廃止するため、バージョン固有の記述を信頼する前に、shopify.dev で fileUpdate を確認してください。productUpdateMedia は非推奨です。fileUpdate は、商品メディアと Files の両方で現在使用されている代替テキストの書き込み方法です。何も変更せずに商品メディアを一覧表示し、代替テキストがないものを確認できる、第三者が実行可能な読み取り専用の再確認方法：

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(first: 5) { edges { node { title media(first: 10) { edges { node { ... on MediaImage { id alt } } } } } } } }"}'

正規ドキュメント： fileUpdate および WAI の画像チュートリアル。これらのスキルには、ドキュメントに記載されていない運用上の教訓がまとめられています。リファレンスの代わりとなるものではありません。