@intlayer/docs 7.0.3 → 7.0.4

package/blog/ja/intlayer_with_next-intl.md

@@ -1,392 +1,114 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayerとnext-intl
-description: Reactアプリのためにnext-intlとIntlayerを連携する
-keywords:
-  - next-intl
-  - Intlayer
-  - 国際化
-  - ドキュメンテーション
-  - Next.js
-  - JavaScript
-  - React
+updatedAt: 2025-10-29
+title: Intlayerを使ってnext-intlのJSON翻訳を自動化する方法
+description: Next.jsアプリケーションの国際化を強化するために、Intlayerとnext-intlを使ってJSON翻訳を自動化する方法。
 slugs:
   - blog
   - intlayer-with-next-intl
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: syncJSONプラグインへの変更
 ---
 
-# Next.js 国際化 (i18n) with next-intl and Intlayer
+# Intlayerを使ってnext-intlのJSON翻訳を自動化する方法
 
-next-intl と Intlayer は、Next.js アプリケーション向けに設計されたオープンソースの国際化 (i18n) フレームワークです。これらは、ソフトウェアプロジェクトにおける翻訳、ローカリゼーション、および言語切替の管理に広く使用されています。
+## Intlayerとは？
 
-それぞれは、3 つの主要な概念を共有しています。
+**Intlayer**は、従来のi18nソリューションの欠点を解決するために設計された革新的なオープンソースの国際化ライブラリです。Next.jsアプリケーションにおけるコンテンツ管理に対してモダンなアプローチを提供します。
 
-1. **コンテンツ宣言**: アプリケーションの翻訳可能なコンテンツを定義するためのメソッド。
-   - Intlayer では `content declaration file` と呼ばれ、構造化データをエクスポートする JSON、JS、または TS ファイルです。詳細は [Intlayer documentation](https://intlayer.org/fr/doc/concept/content) を参照してください。
-   - next-intl では `messages` または `locale messages` と呼ばれ、通常は JSON ファイルにあります。詳細は [next-intl documentation](https://github.com/amannn/next-intl) を参照してください。
+next-intlとの具体的な比較については、当社のブログ記事[ next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ja/next-i18next_vs_next-intl_vs_intlayer.md)をご覧ください。
 
-2. **ユーティリティ**: アプリケーション内でコンテンツ宣言を構築および解釈するためのツールで、Intlayer の `useIntlayer()` または `useLocale()`、および next-intl の `useTranslations()` などがあります。
+## なぜIntlayerをnext-intlと組み合わせるのか？
 
-3. **プラグインとミドルウェア**: URL リダイレクション、バンドル最適化などの機能, 例として、Intlayer の `intlayerMiddleware` や next-intl の [`createMiddleware`](https://github.com/amannn/next-intl) があります。
+Intlayerは優れた単独のi18nソリューションを提供します（当社の[Next.js統合ガイド](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_with_nextjs_16.md)を参照）が、いくつかの理由でnext-intlと組み合わせたい場合があります。
 
-## Intlayer と next-intl の主な違い
+1. **既存のコードベース**: 既に確立されたnext-intlの実装があり、Intlayerの改善された開発者体験に徐々に移行したい場合。
+2. **レガシー要件**: プロジェクトが既存のnext-intlプラグインやワークフローとの互換性を必要とする場合。
+3. **チームの慣れ親しみ**: チームがnext-intlに慣れているが、より良いコンテンツ管理を望んでいる場合。
 
-Intlayer が Next.js 用の他の i18n ライブラリ（next-intl など）と比較される方法の詳細な分析については、[next-i18next vs. next-intl vs. Intlayer blog post](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ja/i18next_vs_next-intl_vs_intlayer.md) をチェックしてください。
+**そのために、Intlayerはnext-intlのアダプターとして実装でき、CLIやCI/CDパイプラインでのJSON翻訳の自動化、翻訳のテストなどを支援します。**
 
-## Intlayer で next-intl メッセージを生成する方法
+このガイドでは、next-intlとの互換性を維持しながら、Intlayerの優れたコンテンツ宣言システムを活用する方法を示します。
 
-### なぜ Intlayer を next-intl と一緒に使用するのか？
+## 目次
 
-Intlayer のコンテンツ宣言ファイルは、一般的により良い開発者体験を提供します。主に 2 つの利点により、柔軟性と保守性が向上しています。
+<TOC/>
 
-1. **柔軟な配置**: Intlayer のコンテンツ宣言ファイルをアプリケーションのファイルツリーのどこにでも配置できます。これにより、使用されていないメッセージファイルやダングリングファイルを残すことなく、コンポーネントの名前を変更したり削除したりすることが容易になります。
+## next-intlとIntlayerをセットアップするステップバイステップガイド
 
-   例となるファイル構造:
+### ステップ1: 依存関係のインストール
 
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # コンテンツ宣言ファイル
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # コンテンツ宣言ファイル
-               └── index.mjx
-   ```
-
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # コンテンツ宣言ファイル
-               └── index.cjx
-   ```
-
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # コンテンツ宣言ファイル
-               └── index.jsx
-   ```
-
-2. **中央集約型の翻訳**: Intlayer はすべての翻訳を単一のコンテンツ宣言に保存し、翻訳が失われることはありません。TypeScript プロジェクトでは、失われた翻訳が自動的に型エラーとしてフラグされ、開発者に即座にフィードバックを提供します。
-
-### インストール
-
-Intlayer と next-intl を一緒に使用するには、両方のライブラリをインストールします:
+必要なパッケージをインストールします:
 
 ```bash packageManager="npm"
-npm install intlayer next-intl
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="yarn"
-yarn add intlayer next-intl
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="pnpm"
-pnpm add intlayer next-intl
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-### Intlayer を設定して next-intl メッセージをエクスポートする
+**パッケージの説明:**
 
-> **注意:** Intlayer から next-intl へメッセージをエクスポートすると、構造にわずかな違いが生じることがあります。統合を簡素化するために、可能であれば Intlayer のみまたは next-intl のみのフローを維持してください。Intlayer から next-intl メッセージを生成する必要がある場合は、以下の手順に従ってください。
+- **intlayer**: 国際化管理、コンテンツ宣言、およびビルドのためのコアライブラリ
+- **@intlayer/sync-json-plugin**: Intlayerのコンテンツ宣言をnext-intl互換のJSON形式にエクスポートするプラグイン
 
-プロジェクトのルートに `intlayer.config.ts` ファイル（.mjs / .cjs）を作成または更新します:
+### ステップ 2: JSONをラップするためのIntlayerプラグインの実装
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
+サポートするロケールを定義するためのIntlayer設定ファイルを作成します:
 
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["next-intl"], // next-intl 出力を使用する
-    nextIntlMessagesDir: "./intl/messages", // next-intl メッセージを保存する場所
-  },
-};
-
-export default config;
-```
-
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["react-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
+**next-intl用のJSON辞書もエクスポートしたい場合は、`syncJSON`プラグインを追加してください:**
 
-export default config;
-```
-
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
+const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
   },
-  content: {
-    dictionaryOutput: ["next-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
-
-module.exports = config;
-```
-
-### コンテンツ宣言
-
-以下は、複数のフォーマットのコンテンツ宣言ファイルの例です。Intlayer はこれらを next-intl が消費できるメッセージファイルにコンパイルします。
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
-import { t, type Dictionary } from "intlayer";
-
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-} satisfies Dictionary;
-
-export default content;
-```
-
-```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
-import { t } from "intlayer";
-
-/** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
     }),
-  },
+  ],
 };
 
-export default content;
+export default config;
 ```
 
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
+`syncJSON` プラグインは JSON を自動的にラップします。コンテンツの構造を変更することなく、JSON ファイルの読み書きを行います。
 
-module.exports = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
-```
+JSON と intlayer のコンテンツ宣言ファイル（`.content` ファイル）を共存させたい場合、Intlayer は以下の手順で処理します：
 
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "my-component",
-  "content": {
-    "helloWorld": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Hello World",
-        "fr": "Bonjour le monde",
-        "es": "Hola Mundo"
-      }
-    }
-  }
-}
-```
-
-### next-intl メッセージのビルド
+    1. JSON ファイルとコンテンツ宣言ファイルの両方を読み込み、intlayer の辞書に変換します。
 
-next-intl 用のメッセージファイルをビルドするには、次のコマンドを実行します:
+2. JSONとコンテンツ宣言ファイル間に競合がある場合、Intlayerはすべての辞書をマージします。プラグインの優先順位やコンテンツ宣言ファイルの優先順位に応じて処理されます（すべて設定可能です）。
 
-```bash packageManager="npm"
-npx intlayer dictionaries build
-```
+CLIを使用してJSONの翻訳を行った場合やCMSを使用した場合、Intlayerは新しい翻訳でJSONファイルを更新します。
 
-```bash packageManager="yarn"
-yarn intlayer build
-```
+## Git設定
 
-```bash packageManager="pnpm"
-pnpm intlayer build
-```
+自動生成されたIntlayerファイルは無視することを推奨します：
 
-これにより、`./intl/messages` ディレクトリにリソースが生成されます（`intlayer.config.*` で構成された通り）。期待される出力:
-
-```bash
-.
-└── intl
-    └── messages
-       └── /ja
-           └── my-content.json
-       └── /fr
-           └── my-content.json
-       └── /es
-           └── my-content.json
+```plaintext fileName=".gitignore"
+# Intlayerによって生成されたファイルを無視
+.intlayer
 ```
 
-各ファイルには、すべての Intlayer コンテンツ宣言からのコンパイル済みのメッセージが含まれています。トップレベルのキーは通常、`content.key` フィールドに一致します。
-
-### 次.js アプリで next-intl を使用する
-
-> 詳細については、公式の [next-intl usage docs](https://github.com/amannn/next-intl#readme) を参照してください。
-
-1. **ミドルウェアを作成する (オプション)**:  
-   自動的なロケール検出またはリダイレクションを管理したい場合、next-intl の [createMiddleware](https://github.com/amannn/next-intl#createMiddleware) を使用してください。
-
-   ```typescript fileName="middleware.ts"
-   import createMiddleware from "next-intl/middleware";
-   import { NextResponse } from "next/server";
-
-   export default createMiddleware({
-     locales: ["ja", "fr", "es"],
-     defaultLocale: "ja",
-   });
-
-   export const config = {
-     matcher: ["/((?!api|_next|.*\\..*).*)"],
-   };
-   ```
-
-2. **メッセージを読み込むための `layout.tsx` または `_app.tsx` を作成する:**  
-   App Router（Next.js 13+）を使用している場合は、レイアウトを作成します。
-
-   ```typescript fileName="app/[locale]/layout.tsx"
-   import { NextIntlClientProvider } from 'next-intl';
-   import { notFound } from 'next/navigation';
-   import React, { ReactNode } from 'react';
-
-
-   export default async function RootLayout({
-     children,
-     params
-   }: {
-     children: ReactNode;
-     params: { locale: string };
-   }) {
-     let messages;
-     try {
-       messages = (await import(`../../intl/messages/${params.locale}.json`)).default;
-     } catch (error) {
-       notFound();
-     }
-
-     return (
-       <html lang={params.locale}>
-         <body>
-           <NextIntlClientProvider locale={params.locale} messages={messages}>
-             {children}
-           </NextIntlClientProvider>
-         </body>
-       </html>
-     );
-   }
-   ```
-
-   Pages Router（Next.js 12 以下）を使用している場合は、`_app.tsx` でメッセージを読み込みます。
-
-   ```typescript fileName="pages/_app.tsx"
-   import type { AppProps } from 'next/app';
-   import { NextIntlProvider } from 'next-intl';
-
-   function MyApp({ Component, pageProps }: AppProps) {
-     return (
-       <NextIntlProvider locale={pageProps.locale} messages={pageProps.messages}>
-         <Component {...pageProps} />
-       </NextIntlProvider>
-     );
-   }
-
-   export default MyApp;
-   ```
-
-3. **サーバーサイドでメッセージを取得する (Pages Router の例):**
-
-   ```typescript fileName="pages/index.tsx"
-   import { GetServerSideProps } from "next";
-   import HomePage from "../components/HomePage";
-
-   export default HomePage;
-
-   export const getServerSideProps: GetServerSideProps = async ({ locale }) => {
-     const messages = (await import(`../intl/messages/${locale}.json`)).default;
-
-     return {
-       props: {
-         locale,
-         messages,
-       },
-     };
-   };
-   ```
-
-### Next.js コンポーネントでのコンテンツの使用
-
-メッセージが next-intl に読み込まれると、`useTranslations()` フックを介してコンポーネント内で使用できます:
-
-```typescript fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
-import type { FC } from "react";
-import { useTranslations } from 'next-intl';
-
-const MyComponent: FC = () => {
-  const t = useTranslations('my-component');
-  // 'my-component' は Intlayer 内のコンテンツキーに対応します
-
-  return (
-    <div>
-      <h1>{t('helloWorld')}</h1>
-    </div>
-  );
-};
-
-export default MyComponent;
-```
+これらのファイルはビルドプロセス中に再生成可能であり、バージョン管理にコミットする必要はありません。
 
-```jsx fileName="src/components/MyComponent/index.jsx" codeFormat="esm"
-import { useTranslations } from "next-intl";
+### VS Code拡張機能
 
-export default function MyComponent() {
-  const t = useTranslations("my-component");
+開発者体験を向上させるために、公式の**Intlayer VS Code拡張機能**をインストールしてください：
 
-  return (
-    <div>
-      <h1>{t("helloWorld")}</h1>
-    </div>
-  );
-}
-```
+[VS Codeマーケットプレイスからインストール](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-**これで完了です!** Intlayer コンテンツ宣言ファイルを更新または追加するたびに、`intlayer build` コマンドを再実行して next-intl JSON メッセージを再生成してください。next-intl は更新されたコンテンツを自動的に取得します。
+[VS Codeマーケットプレイスからインストール](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)