withastro · Yusaku01 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026
diff --git a/src/content/docs/ja/guides/prefetch.mdx b/src/content/docs/ja/guides/prefetch.mdx
@@ -0,0 +1,273 @@
+---
+title: プリフェッチ
+description: ページ間のすばやいナビゲーションのためにリンクをプリフェッチします。
+i18nReady: true
+---
+
+import { Steps } from '@astrojs/starlight/components'
+import Since from '~/components/Since.astro'
+
+ページのロード時間は、サイトの使いやすさとサイト全体の快適さに大きな影響を与えます。Astroの**オプトインのプリフェッチ**を利用すると、訪問者がマルチページアプリケーション（MPA）のサイトを操作する際に、ほぼ瞬時にページナビゲーションできるようになります。
+
+## プリフェッチを有効にする
+
+プリフェッチは、`prefetch`設定で有効にできます。
+
+```js title="astro.config.mjs" ins={4}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  prefetch: true
+});
+```
+
+プリフェッチスクリプトがサイトのすべてのページに追加されます。その後、サイト上の任意の`<a />`リンクに`data-astro-prefetch`属性を追加することで、プリフェッチにオプトインできます。リンク上にホバーすると、スクリプトがページをバックグラウンドでフェッチします。
+
+```html
+<a href="/about" data-astro-prefetch>
+```
+
+プリフェッチはサイト内のリンクに対してのみ機能し、外部リンクに対しては機能しないことに注意してください。
+
+## プリフェッチの設定
+
+`prefetch`設定は、プリフェッチをさらにカスタマイズするためのオプションのオブジェクトも受け付けます。
+
+### プリフェッチ戦略
+
+Astroは、さまざまなユースケースのために、以下の4種類のプリフェッチ戦略をサポートします。
+
+- `hover`（デフォルト）。リンク上にホバーまたはフォーカスしたときにプリフェッチします。
+- `tap`。リンクをクリックする直前にプリフェッチします。
+- `viewport`。リンクがビューポートに入ったときにプリフェッチします。
+- `load`。ページのロード後に、ページ上のすべてのリンクをプリフェッチします。
+
+個別のリンクに対して戦略を指定するには、戦略を`data-astro-prefetch`属性に渡します。
+
+```html
+<a href="/about" data-astro-prefetch="tap">About</a>
+```
+
+各戦略はファインチューニングされており、必要なときにのみプリフェッチしてユーザーの帯域を節約します。たとえば、
+
+- 訪問者が[データ節約モード](https://developer.mozilla.org/ja/docs/Web/API/NetworkInformation/saveData)や[低速なコネクション](https://developer.mozilla.org/ja/docs/Web/API/NetworkInformation/effectiveType)を使っている場合、プリフェッチは`tap`戦略にフォールバックします。
+- リンク上にすばやくホバーやスクロールした場合はプリフェッチしません。
+
+### デフォルトのプリフェッチ戦略
+
+`data-astro-prefetch`属性を追加した場合のデフォルトのプリフェッチ戦略は`hover`です。デフォルトを変更するには、`astro.config.mjs`ファイルで[`prefetch.defaultStrategy`](/ja/reference/configuration-reference/#prefetchdefaultstrategy)を設定します。
+
+```js title="astro.config.mjs" ins={4-6}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  prefetch: {
+    defaultStrategy: 'viewport'
+  }
+});
+```
+
+### すべてのリンクをデフォルトでプリフェッチする
+
+`data-astro-prefetch`属性のないリンクも含めて、すべてのリンクをプリフェッチするには、[`prefetch.prefetchAll`](/ja/reference/configuration-reference/#prefetchprefetchall)を`true`に設定します。
+
+```js title="astro.config.mjs" ins={4-6}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  prefetch: {
+    prefetchAll: true
+  }
+});
+```
+
+その後、`data-astro-prefetch="false"`に設定することで、個別のリンクのプリフェッチをオプトアウトできます。
+
+```html
+<a href="/about" data-astro-prefetch="false">About</a>
+```
+
+すべてのリンクに対するデフォルトのプリフェッチ戦略は、[デフォルトのプリフェッチ戦略](#デフォルトのプリフェッチ戦略)に示したように、`prefetch.defaultStrategy`で変更できます。
+
+## プログラムによるプリフェッチ
+
+ナビゲーションは常に`<a />`リンクとして表示されるとは限らないため、`astro:prefetch`モジュールの`prefetch()` APIを使用してプログラムからプリフェッチすることもできます。
+
+```astro
+<button id="btn">Click me</button>
+
+<script>
+  import { prefetch } from 'astro:prefetch';
+
+  const btn = document.getElementById('btn');
+  btn?.addEventListener('click', () => {
+    prefetch('/about');
+  });
+</script>
+```
+
+`prefetch()` APIには、同様の[データ節約モード](https://developer.mozilla.org/ja/docs/Web/API/NetworkInformation/saveData)と[低速なコネクション](https://developer.mozilla.org/ja/docs/Web/API/NetworkInformation/effectiveType)の検出機能があるため、必要なときにだけプリフェッチします。
+
+低速なコネクションの検出を無視するには、`ignoreSlowConnection`オプションが利用できます。
+
+```js
+// データ節約モードや低速なコネクションの場合でもプリフェッチする
+prefetch('/about', { ignoreSlowConnection: true });
+```
+
+### `eagerness`
+
+<p>
+**型:** `'immediate' | 'eager' | 'moderate' | 'conservative'`<br />
+**デフォルト:** `'immediate'`<br />
+<Since v="5.6.0" />
+</p>
+
+実験的な[`clientPrerender`](/ja/reference/experimental-flags/client-prerender/)フラグを有効にすると、`prefetch()`の`eagerness`オプションを使用して、リンク先をどの程度積極的にプリフェッチまたはプリレンダリングするかをブラウザに提案できます。
+
+このオプションは[Speculation Rules API](https://developer.mozilla.org/ja/docs/Web/HTML/Element/script/type/speculationrules#eagerness)で説明されているものと同じAPIに従い、デフォルトはもっとも積極的な`immediate`です。積極度の高い順に、ほかの選択肢は`eager`、`moderate`、`conservative`です。
+
+`eagerness`オプションを使用すると、待ち時間を短縮するメリットと、サイト訪問者の帯域幅、メモリ、CPUのコストとのバランスを調整できます。Chromeなど一部のブラウザには、[過剰な投機的読み込み（リンクをプリレンダリングまたはプリフェッチしすぎること）を防ぐための制限](https://developer.chrome.com/blog/speculation-rules-improvements#chrome-limits)があります。
+
+```astro
+---
+---
+<script>
+// `experimental.clientPrerender`でプリフェッチの積極度を制御する
+import { prefetch } from 'astro:prefetch';
+
+// このページは多くのリソースを消費する
+prefetch('/data-heavy-dashboard', { eagerness: 'conservative' });
+
+// このページは訪問者の導線において重要である
+prefetch('/getting-started'); // デフォルトは`{ eagerness: 'immediate' }`
+
+// このページにはアクセスしない可能性がある
+prefetch('/terms-of-service', { eagerness: 'moderate' });
+</script>
+```
+
+多くのリンクをプログラムから`prefetch()`する場合は、`eagerness: 'moderate'`を設定できます。[先入れ先出し（FIFO）](https://ja.wikipedia.org/wiki/FIFO)方式とブラウザのヒューリスティックを活用し、どのリンクをどの順序でプリレンダリングまたはプリフェッチするかをブラウザに判断させられます。
+
+```astro "{eagerness: 'moderate'}"
+<a class="link-moderate" href="/nice-link-1">A Nice Link 1</a>
+<a class="link-moderate" href="/nice-link-2">A Nice Link 2</a>
+<a class="link-moderate" href="/nice-link-3">A Nice Link 3</a>
+<a class="link-moderate" href="/nice-link-4">A Nice Link 4</a>
+...
+<a class="link-moderate" href="/nice-link-20">A Nice Link 20</a>
+
+<script>
+  import { prefetch } from "astro:prefetch";
+
+  const linkModerate = document.getElementsByClassName("link-moderate");
+  for (const link of linkModerate) {
+    const href = link.getAttribute("href");
+    if (href) prefetch(href, { eagerness: "moderate" });
+  }
+</script>
+```
+
+ブラウザのAPIに依存しているため、クライアント側で`prefetch()`だけをインポートするようにしてください。
+
+## ビュートランジションとともに使用する
+
+ページで[Astroの`<ClientRouter />`](/ja/guides/view-transitions/#enabling-view-transitions-spa-mode)を使用すると、プリフェッチもデフォルトで有効になります。`{ prefetchAll: true }`がデフォルトで設定され、ページ内の[すべてのリンクに対するプリフェッチ](#すべてのリンクをデフォルトでプリフェッチする)が有効になります。
+
+デフォルトを上書きするには、`astro.config.mjs`内のプリフェッチ設定をカスタマイズできます。たとえば、次のように設定します。
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  // プリフェッチを完全に無効化する
+  prefetch: false
+});
+```
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  // プリフェッチは維持するが、`data-astro-prefetch`があるリンクのみをプリフェッチする。
+  prefetch: {
+    prefetchAll: false
+  }
+});
+```
+
+## ブラウザサポート
+
+Astroのプリフェッチは、ブラウザがサポートしている場合は[`<link rel="prefetch">`](https://developer.mozilla.org/ja/docs/Web/HTML/Attributes/rel/prefetch)を使用し、サポートしていない場合は[`fetch()` API](https://developer.mozilla.org/ja/docs/Web/API/Fetch_API)にフォールバックします。
+
+主要なブラウザはAstroのプリフェッチをサポートしていますが、動作には若干の違いがあります。
+
+### Chrome
+
+Chromeは`<link rel="prefetch">`をサポートしており、プリフェッチは意図どおりに動作します。
+
+また、[Speculation Rules API](https://developer.mozilla.org/ja/docs/Web/API/Speculation_Rules_API)の`<script type="speculationrules">`も完全にサポートしています。このAPIを使用すると、[プリフェッチの戦略やルール](#eagerness)をさらに詳しく指定でき、Chromeユーザーの体験を向上できます。`prefetch()`でこの機能を使用するには、実験的な[`clientPrerender`](/ja/reference/experimental-flags/client-prerender/)フラグを有効にする必要があります。
+
+### Firefox
+
+Firefoxは`<link rel="prefetch">`をサポートしていますが、エラーが表示されたり、まったく機能しなかったりする場合があります。
+
+- 明示的なキャッシュヘッダー（[`Cache-Control`](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Cache-Control)や[`Expires`](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Expires)など）がない場合、プリフェッチで`NS_BINDING_ABORTED`エラーが発生します。
+- エラーが発生しても、レスポンスに適切な[`ETag`](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/ETag)ヘッダーがあれば、ページ移動時に再利用されます。
+- それ以外の場合、エラーが発生し、ほかのキャッシュヘッダーもなければ、プリフェッチは機能しません。
+
+### Safari
+
+Safariは`<link rel="prefetch">`をサポートしていないため、`fetch()` APIにフォールバックします。プリフェッチを機能させるには、[`Cache-Control`](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Cache-Control)、[`Expires`](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Expires)、[`ETag`](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/ETag)などのキャッシュヘッダーを設定する必要があります。
+
+**エッジケース:** プライベートウィンドウでは`ETag`ヘッダーが機能しません。
+
+### 推奨事項
+
+すべてのブラウザをできる限りサポートするため、ページに適切なキャッシュヘッダーが設定されていることを確認してください。
+
+静的ページやプリレンダリングされたページでは、多くの場合デプロイ先のプラットフォームによって`ETag`ヘッダーが自動的に設定され、そのまま動作します。
+
+動的ページやサーバーサイドレンダリングされたページでは、ページの内容に応じて適切なキャッシュヘッダーを設定してください。詳しくは、[HTTPキャッシュに関するMDNドキュメント](https://developer.mozilla.org/ja/docs/Web/HTTP/Caching)を参照してください。
+
+## `@astrojs/prefetch`からのマイグレーション
+
+`@astrojs/prefetch`インテグレーションはv3.5.0で非推奨となり、現在はメンテナンスされていません。以下の手順に従って、このインテグレーションを置き換えるAstro組み込みのプリフェッチへ移行してください。
+
+<Steps>
+1. `@astrojs/prefetch`インテグレーションを削除し、`astro.config.mjs`内の`prefetch`設定を有効化します。
+
+    ```js title="astro.config.mjs" ins={6} del={2,5}
+    import { defineConfig } from 'astro/config';
+    import prefetch from '@astrojs/prefetch';
+
+    export default defineConfig({
+      integrations: [prefetch()],
+      prefetch: true
+    });
+    ```
+
+2. `@astrojs/prefetch`の設定オプションから変換します。
+
+    - 非推奨になったインテグレーションでは、ビューポートに入ったときにプリフェッチするリンクを指定するために、`selector`設定オプションを使用していました。
+
+      代わりに、これらの個別のリンクに`data-astro-prefetch="viewport"`を追加してください。
+
+      ```html
+      <a href="/about" data-astro-prefetch="viewport">
+      ```
+
+    - 非推奨になったインテグレーションでは、ホバーまたはフォーカスしたときにプリフェッチするリンクを指定するために、`intentSelector`設定オプションを使用していました。
+
+      代わりに、これらの個別のリンクに`data-astro-prefetch`または`data-astro-prefetch="hover"`を追加してください。
+
+      ```html
+      <!-- `defaultStrategy`が`hover`（デフォルト）に設定されている場合、値を省略できます -->
+      <a href="/about" data-astro-prefetch>
+
+      <!-- そうでない場合は、プリフェッチ戦略を明示的に定義できます -->
+      <a href="/about" data-astro-prefetch="hover">
+      ```
+
+    - 新しいプリフェッチ機能は自動的にスケジューリングを行って最適にプリフェッチするため、`@astrojs/prefetch`の`throttles`オプションは必要なくなりました。
+</Steps>