@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/ja/intlayer_with_nextjs_14.md

@@ -42,6 +42,8 @@ author: aymericzip
 
 **Next.js を完全にカバー**
 
+<Accordion header="Full Next.js coverage">
+
 Intlayer は、効率的なレンダリングのために **サーバー コンポーネント** と連携するように最適化されており、[**Turbopack**](https://nextjs.org/docs/architecture/turbopack) と完全に互換性があります。静的レンダリングをブロックせず、ミドルウェアとスケーリング国際化 (i18n) に必要なすべての機能を提供します。
 
 > Intlayer は Next.js 12、13、14、15、および 16 と互換性があります。 Next.js Pages Router を使用している場合は、この [ガイド](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_page_router.md) を参照してください。
@@ -50,6 +52,8 @@ Intlayer は、効率的なレンダリングのために **サーバー コン
 
 **バンドルサイズ**
 
+<Accordion header="バンドルサイズ">
+
 大量の JSON ファイルをページにロードするのではなく、必要なコンテンツのみをロードします。 Intlayer は、**バンドルとページのサイズを最大 50% 削減**するのに役立ちます。
 
 **保守性**
@@ -58,24 +62,64 @@ Intlayer は、効率的なレンダリングのために **サーバー コン
 
 **AI エージェント**
 
+</Accordion>
+
+<Accordion header="AI Agent">
+
 コンテンツを同じ場所に配置すると、大規模言語モデル (LLM) によって **必要なコンテキストが削減**されます。 Intlayer には、翻訳の欠落をテストする **CLI**、**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**、**[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** などのツール スイートも付属しています。および **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/agent_skills.md)** により、AI エージェントの開発者エクスペリエンス (DX) がさらにスムーズになります。
 
 **オートメーション**
 
+<Accordion header="自動化">
+
 AI プロバイダーの費用で、選択した LLM を使用して CI/CD パイプラインで自動化を変換します。 Intlayer は、コンテンツ抽出を自動化する **コンパイラー** と、**バックグラウンドでの翻訳**を支援する [Web プラットフォーム](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) も提供します。
 
 **パフォーマンス**
 
+<Accordion header="パフォーマンス">
+
 大量の JSON ファイルをコンポーネントに接続すると、パフォーマンスと反応性の問題が発生する可能性があります。 Intlayer は、ビルド時のコンテンツの読み込みを最適化します。
 
 **非開発によるスケーリング**
 
+<Accordion header="非開発環境でのスケーリング">
+
 Intlayer は単なる i18n ソリューションではなく、**自己ホスト型 [ビジュアル エディター](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** と **[完全な CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** を提供します。 **リアルタイム**で多言語コンテンツを管理できるようになり、翻訳者、コピーライター、その他のチーム メンバーとのコラボレーションがシームレスになります。コンテンツはローカルおよび/またはリモートに保存できます。
 
+</Accordion>
+</AccordionGroup>
+
 ---
 
 ## Next.jsアプリケーションでIntlayerをセットアップするステップバイステップガイド
 
+<Tabs defaultTab="code">
+  <Tab label="Code" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-next-14-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - Intlayerを使用してアプリケーションを国際化する方法"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+  <Tab label="デモ" value="demo">
+
+<iframe
+  src="https://intlayer-next-14-template.vercel.app"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo - intlayer-next-14-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+[Application Template](https://github.com/aymericzip/intlayer-next-14-template) を GitHub で確認してください。
+
 <Steps>
 
 <Step number={1} title="依存関係のインストール">
@@ -197,6 +241,15 @@ export default withIntlayer(nextConfig);
 
 > `withIntlayer()` は Next.js と Intlayer を統合するための Next.js プラグインです。これにより、コンテンツ宣言ファイルのビルドが保証され、開発モードでの監視が行われます。また、[Webpack](https://webpack.js.org/) や [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack) 環境内で Intlayer の環境変数を定義します。さらに、パフォーマンスを最適化するためのエイリアスを提供し、サーバーコンポーネントとの互換性も確保します。
 
+> `withIntlayer()` 関数は promise 関数です。他のプラグインと一緒に使用したい場合は、それを await できます。例：
+>
+> ```tsx
+> const nextConfig = await withIntlayer(nextConfig);
+> const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
+>
+> export default nextConfigWithOtherPlugins;
+> ```
+
 </Step>
 
 <Step number={4} title="ロケール検出のためのミドルウェアを設定する">
@@ -214,8 +267,25 @@ export const config = {
 
 > `intlayerMiddleware` は、ユーザーの優先ロケールを検出し、[設定](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)で指定された適切なURLにリダイレクトするために使用されます。さらに、ユーザーの優先ロケールをクッキーに保存することも可能にします。
 
+> Intlayer v9 以降、このミドルウェアは `routing.enableProxy` オプション（デフォルトでは `true`）を尊重します。このファイルを削除せずにパススルーに変更するには、設定で `routing.enableProxy: false` を設定してください。[v9 リリースノート](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/releases/v9.md)を参照してください。
+
 > `matcher` パラメータは、アプリケーションのルートに合わせて調整してください。詳細については、[Next.js の matcher 設定に関するドキュメント](https://nextjs.org/docs/app/building-your-application/routing/middleware)を参照してください。
 
+> 複数のミドルウェアをチェーンする必要がある場合（例えば、`intlayerMiddleware` と認証やカスタムミドルウェア），Intlayer は `multipleMiddlewares` というヘルパーを提供しています。
+
+```ts
+import {
+  multipleMiddlewares,
+  intlayerMiddleware,
+} from "next-intlayer/middleware";
+import { customMiddleware } from "@utils/customMiddleware";
+
+export const middleware = multipleMiddlewares([
+  intlayerMiddleware,
+  customMiddleware,
+]);
+```
+
 </Step>
 
 <Step number={5} title="動的ロケールルートの定義">
@@ -235,11 +305,38 @@ export default RootLayout;
 
 動的ルーティングを実装するには、`[locale]` ディレクトリに新しいレイアウトを追加してロケールのパスを提供します。
 
+<Tabs>
+ <Tab label='Intlayer >=9.4' value='>=9.4'>
+
 ```tsx fileName="src/app/[locale]/layout.tsx" codeFormat={["typescript", "esm"]}
-import {
-  type Next14LayoutIntlayer,
-  IntlayerClientProvider,
-} from "next-intlayer";
+import { type Next14LayoutIntlayer } from "next-intlayer";
+import { IntlayerProvider } from "next-intlayer/server";
+import { Inter } from "next/font/google";
+import { getHTMLTextDir } from "intlayer";
+
+const inter = Inter({ subsets: ["latin"] });
+
+const LocaleLayout: Next14LayoutIntlayer = ({
+  children,
+  params: { locale },
+}) => (
+  <IntlayerProvider locale={locale}>
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <body className={inter.className}>{children}</body>
+    </html>
+  </IntlayerProvider>
+);
+
+export default LocaleLayout;
+```
+
+> 単一の `IntlayerProvider` はツリーの両方の半分をカバーしています。リクエストスコープのサーバーコンテキストをシードして、サーバーフックで読み取られ、クライアントプロバイダーをマウントして、クライアントコンポーネントが同じロケールを受け取ります。
+
+ </Tab>
+ <Tab label='Intlayer <9.4' value='<9.4'>
+
+```tsx fileName="src/app/[locale]/layout.tsx" codeFormat={["typescript", "esm"]}
+import { type Next14LayoutIntlayer, IntlayerProvider } from "next-intlayer";
 import { Inter } from "next/font/google";
 import { getHTMLTextDir } from "intlayer";
 
@@ -251,9 +348,7 @@ const LocaleLayout: Next14LayoutIntlayer = ({
 }) => (
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <body className={inter.className}>
-      <IntlayerClientProvider locale={locale}>
-        {children}
-      </IntlayerClientProvider>
+      <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
     </body>
   </html>
 );
@@ -261,6 +356,9 @@ const LocaleLayout: Next14LayoutIntlayer = ({
 export default LocaleLayout;
 ```
 
+ </Tab>
+</Tabs>
+
 > `[locale]` パスセグメントはロケールを定義するために使用されます。例：`/en-US/about` は `en-US` を指し、`/fr/about` は `fr` を指します。
 
 > この段階で、`Error: Missing <html> and <body> tags in the root layout.` というエラーが発生します。これは予期されたもので、`/app/page.tsx` ファイルはもはや使用されておらず、削除して問題ありません。代わりに、`[locale]` パスセグメントが `/app/[locale]/page.tsx` ページを有効にします。その結果、ブラウザ上で `/en`、`/fr`、`/es` のようなパスでページにアクセスできるようになります。デフォルトのロケールをルートページとして設定するには、ステップ4の `middleware` 設定を参照してください。
@@ -345,6 +443,40 @@ export default pageContent;
 
 アプリケーション全体でコンテンツ辞書にアクセスします:
 
+<Tabs>
+ <Tab label='Intlayer >=9.4' value='>=9.4'>
+
+```tsx fileName="src/app/[locale]/page.tsx" codeFormat={["typescript", "esm"]}
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { type Next14PageIntlayer } from "next-intlayer";
+import { useIntlayer } from "next-intlayer";
+
+const Page: Next14PageIntlayer = ({ params: { locale } }) => {
+  const content = useIntlayer("page", locale);
+
+  return (
+    <>
+      <p>
+        {content.getStarted.main}
+        <code>{content.getStarted.pageLink}</code>
+      </p>
+
+      <ServerComponentExample />
+      <ClientComponentExample />
+    </>
+  );
+};
+
+export default Page;
+```
+
+- **`IntlayerProvider`** はロケールレイアウトに一度だけマウントされます。サーバーコンポーネントとクライアントコンポーネントの両方にロケールを提供するため、ページ自体はラップされなくなります。
+- サーバーフックはこの順序でロケールを解決します：呼び出しサイトで渡されたロケール、プロバイダーによってシードされたサーバーコンテキスト、その後リクエストで遂行されたロケール（Intlayer プロキシによって設定された `x-intlayer-locale` ヘッダー、その後ロケール Cookie）。最後のステップにより、レイアウト（およびプロバイダー）が再実行されないページセグメントのみを再レンダリングするクライアント側ナビゲーションでコンテンツが正しく保たれます。
+
+ </Tab>
+ <Tab label='Intlayer <9.4' value='<9.4'>
+
 ```tsx fileName="src/app/[locale]/page.tsx" codeFormat={["typescript", "esm"]}
 import { ClientComponentExample } from "@components/ClientComponentExample";
 import { ServerComponentExample } from "@components/ServerComponentExample";
@@ -377,6 +509,9 @@ export default Page;
 
 > レイアウトとページは共通のサーバーコンテキストを共有できません。なぜなら、サーバーコンテキストシステムはリクエストごとのデータストア（[Reactのキャッシュ](https://react.dev/reference/react/cache)メカニズムを通じて）に基づいており、アプリケーションの異なるセグメントごとに「コンテキスト」が再作成されるためです。プロバイダーを共有レイアウトに配置すると、この分離が破られ、サーバーコンポーネントへのサーバーコンテキスト値の正しい伝播が妨げられます。
 
+</Tab>
+</Tabs>
+
 ```tsx {4,7} fileName="src/components/ClientComponentExample.tsx" codeFormat={["typescript", "esm"]}
 "use client";
 
@@ -395,6 +530,30 @@ const ClientComponentExample: FC = () => {
 };
 ```
 
+<Tabs>
+ <Tab label='Intlayer >=9.4' value='>=9.4'>
+
+```tsx {2} fileName="src/components/ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+const ServerComponentExample: FC = () => {
+  const content = useIntlayer("server-component-example"); // 関連するコンテンツ宣言を作成
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+> `next-intlayer` は isomorphic import path です。`react-server` export condition によって、サーバーコンポーネントは ambient-locale 実装を取得し、クライアントコンポーネントは context-backed 実装を取得します。同じ呼び出しが両側で機能します。
+
+ </Tab>
+ <Tab label='Intlayer <9.4' value='<9.4'>
+
 ```tsx {2} fileName="src/components/ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
 import { useIntlayer } from "next-intlayer/server";
@@ -411,6 +570,9 @@ const ServerComponentExample: FC = () => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 > コンテンツを `alt`、`title`、`href`、`aria-label` などの `string` 属性で使用したい場合は、関数の値を使用できます。例えば：
 
 > ```html
@@ -476,87 +638,6 @@ export default metadataContent;
 }
 ```
 
-````typescript fileName="src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx" codeFormat="typescript"
-import { getIntlayer, getMultilingualUrls } from "intlayer";
-import type { Metadata } from "next";
-import type { LocalParams } from "next-intlayer";
-
-export const generateMetadata = ({
-  params: { locale },
-}: LocalParams): Metadata => {
-  const metadata = getIntlayer("page-metadata", locale);
-
-  /**
-   * 各ロケールのすべてのURLを含むオブジェクトを生成します。
-   *
-   * 例:
-   * ```ts
-   *  getMultilingualUrls('/about');
-   *
-   *  // 戻り値
-   *  // {
-   *  //   en: '/about',
-   *  //   fr: '/fr/about',
-   *  //   es: '/es/about',
-   *  // }
-   * ```
-   */
-  const multilingualUrls = getMultilingualUrls("/");
-  const localizedUrl =
-    multilingualUrls[locale as keyof typeof multilingualUrls];
-
-  return {
-    ...metadata,
-    alternates: {
-      canonical: localizedUrl,
-      languages: { ...multilingualUrls, "x-default": "/" },
-    },
-    openGraph: {
-      url: localizedUrl,
-    },
-  };
-};
-
-javascript fileName="src/app/[locale]/layout.mjs or src/app/[locale]/page.mjs" codeFormat="esm"
-import { getIntlayer, getMultilingualUrls } from "intlayer";
-
-export const generateMetadata = ({ params: { locale } }) => {
-  const metadata = getIntlayer("page-metadata", locale);
-
-  /**
-   * 各ロケールのすべてのURLを含むオブジェクトを生成します。
-   *
-   * 例:
-   * ```ts
-   *  getMultilingualUrls('/about');
-   *
-   *  // 戻り値
-   *  // {
-   *  //   en: '/about',
-   *  //   fr: '/fr/about',
-   *  //   es: '/es/about'
-   *  // }
-   * ```
-   */
-  const multilingualUrls = getMultilingualUrls("/");
-  const localizedUrl =
-    multilingualUrls[locale];
-
-  return {
-    ...metadata,
-    alternates: {
-      canonical: localizedUrl,
-      languages: { ...multilingualUrls, "x-default": "/" },
-    },
-    openGraph: {
-      url: localizedUrl,
-    },
-  };
-};
-
-// ... 残りのコード
-````
-
 ````javascript fileName="src/app/[locale]/layout.cjs or src/app/[locale]/page.cjs" codeFormat="commonjs"
 const { getIntlayer, getMultilingualUrls } = require("intlayer");
 
@@ -865,6 +946,33 @@ Link.displayName = "Link";
 
 `next-intlayer` を使用すると、辞書はデフォルトですべてのページのバンドルに含まれます。バンドルサイズを最適化するために、Intlayer はマクロを使用して `useIntlayer` の呼び出しをインテリジェントに置き換えるオプションの SWC プラグインを提供しています。これにより、辞書は実際に使用されているページのバンドルにのみ含まれるようになります。
 
+```tsx fileName="src/app/actions/getLocale.ts" codeFormat="typescript"
+"use server";
+
+import { getLocale } from "next-intlayer/server";
+
+export const myServerAction = async () => {
+  const locale = await getLocale();
+
+  // ロケール を使って何かを実行
+};
+```
+
+> `getLocale` 関数は、ユーザーのロケールを決定するためにカスケード戦略に従います：
+>
+> 1. まず、ミドルウェアによって設定されている可能性のあるロケール値をリクエストヘッダーで確認します
+> 2. ヘッダーにロケールが見つからない場合、Cookie に保存されているロケールを探します
+> 3. Cookie が見つからない場合、ブラウザ設定からユーザーの優先言語の検出を試みます
+> 4. 最後の手段として、アプリケーションで設定されたデフォルトロケールにフォールバックします
+>
+> これにより、利用可能なコンテキストに基づいて最も適切なロケールが選択されることが保証されます。
+
+</Step>
+
+<Step number={13} title="Bundle サイズを最適化する" isOptional={true}>
+
+`next-intlayer`を使用する場合、デフォルトではすべてのページのバンドルに辞書が含まれます。バンドルサイズを最適化するために、Intlayerはマクロを使用して`useIntlayer`呼び出しをインテリジェントに置き換える、オプションのSWCプラグインを提供しています。これにより、実際に使用しているページのバンドルにのみ辞書が含まれるようになります。
+
 この最適化を有効にするには、`@intlayer/swc` パッケージをインストールしてください。インストール後、`next-intlayer` は自動的にプラグインを検出して使用します。
 
 ```bash packageManager="npm"
@@ -885,6 +993,8 @@ bun add @intlayer/swc --dev
 
 > 注意: この最適化は Next.js 13 以降でのみ利用可能です。
 
+> 注意: このパッケージはデフォルトではインストールされません。SWC プラグインは Next.js でまだ実験的な段階にあるためです。将来的に変わる可能性があります。
+
 > 注意: このパッケージは、Next.jsでSWCプラグインがまだ実験的なため、デフォルトではインストールされていません。将来的に変更される可能性があります。
 > </Step>
 
@@ -936,8 +1046,6 @@ Intlayer での開発体験を向上させるために、公式の **Intlayer VS
 
 拡張機能の使い方の詳細については、[Intlayer VS Code 拡張機能のドキュメント](https://intlayer.org/doc/vs-code-extension)を参照してください。
 
----
-
 ### さらに進むには
 
 さらに進むには、[ビジュアルエディター](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_visual_editor.md)を実装するか、[CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_CMS.md)を使用してコンテンツを外部化することができます。