@intlayer/docs 7.0.0-canary.1 → 7.0.0-canary.3

package/docs/ja/releases/v7.md

@@ -0,0 +1,504 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: 新しい Intlayer v7 - 新機能は何ですか？
+description: Intlayer v7 の新機能を発見してください。パフォーマンス、開発者体験の大幅な改善と国際化ワークフローを強化する新機能。
+keywords:
+  - Intlayer
+  - ローカリゼーション
+  - 開発
+  - パフォーマンス
+  - 開発者体験
+  - 機能
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# 新しい Intlayer v7 - 新機能は何ですか？
+
+Intlayer v7 へようこそ！このメジャーリリースでは、パフォーマンス、型安全性、開発者体験において大幅な改善を導入しました。以下にハイライト、移行ノート、実用的な例を示します。
+
+## ハイライト
+
+- より高速なビルドのためのキャッシュ戦略
+- ロケール固有の型を用いたTypeScript型生成の改善
+- バンドル最適化：enumではなく文字列としてのロケール
+- 新しいルーティングモード：`prefix-no-default`、`prefix-all`、`no-prefix`、`search-params`
+- GDPR準拠のロケール保存、デフォルトはlocalStorage
+- 柔軟なストレージ設定：クッキー、localStorage、sessionStorage、または複数の組み合わせ
+- Visual Editorパッケージサイズが30%縮小
+- ミドルウェア設定オプションの強化
+- コンテンツ管理向上のためのfillコマンドの動作更新
+- コンテンツ宣言ファイルの完全更新による安定性向上
+- 翻訳精度のためのインテリジェントなリトライ管理
+- より高速な翻訳処理のための並列化
+- AIコンテキスト制限内で大きなファイルを扱うスマートチャンク処理
+
+---
+
+## パフォーマンス：より高速なビルドのためのキャッシュ
+
+esbuildで毎回コンテンツ宣言を再構築する代わりに、v7ではビルドプロセスを高速化するキャッシュ戦略を実装しています。
+
+```bash
+npx intlayer build
+```
+
+新しいキャッシュシステムは以下を実現します：
+
+- コンパイル済みのコンテンツ宣言を保存し、冗長な処理を回避
+- 変更を検出し、変更されたファイルのみを再構築
+- 大規模プロジェクトのビルド時間を大幅に短縮
+
+---
+
+## TypeScript：ロケール別の型生成
+
+TypeScriptの型はロケールごとに生成されるようになり、より強力な型付けが可能となり、全ロケールにまたがるユニオン型を排除します。
+
+**v6の挙動：**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**v7の挙動：**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" }
+```
+
+利点:
+
+- IDEでのより正確なオートコンプリート
+- ロケール間の型汚染がなく、より良い型安全性
+- 型の複雑さを減らすことでパフォーマンスが向上
+
+---
+
+## バンドル最適化: 文字列としてのロケール
+
+`Locales`型はもはや列挙型(enum)ではなくなり、完全にツリーシェイク可能となったため、使用されていない何千ものロケールレコードでバンドルが膨らむことがありません。
+
+**v6:**
+
+```typescript
+import { Locales } from "intlayer";
+// すべてのロケールを含む列挙型 -> ツリーシェイク不可
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// 文字列型 -> 完全にツリーシェイク可能
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> `Locales`はもはやenumではないため、型としてロケールを取得するには、型を`Locales`から`Locale`に変更する必要があります。
+
+詳細については、[実装の詳細](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)をご覧ください。
+
+---
+
+## より柔軟な新しいルーティングモード
+
+v7では、以前の`prefixDefault`および`noPrefix`オプションに代わる統一された`routing.mode`設定が導入され、URL構造に対するより細かな制御が可能になりました。
+
+### 利用可能なルーティングモード
+
+- **`prefix-no-default`**（デフォルト）：デフォルトロケールにはプレフィックスがなく、その他のロケールにはプレフィックスが付く
+  - `/dashboard`（en）または`/fr/dashboard`（fr）
+- **`prefix-all`**：すべてのロケールにプレフィックスが付く
+  - `/en/dashboard`（en）または`/fr/dashboard`（fr）
+- **`no-prefix`**: URLにロケールのプレフィックスがない（ロケールはストレージやヘッダーで管理）
+  - すべてのロケールで `/dashboard`
+- **`search-params`**: クエリパラメータとしてロケールを渡す
+  - `/dashboard?locale=en` または `/dashboard?locale=fr`
+
+### 基本設定
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // デフォルト
+  },
+};
+```
+
+---
+
+## GDPR準拠：localStorage / クッキーのストレージ
+
+v7では、ユーザーのプライバシーを優先し、クッキーの代わりに `localStorage` をデフォルトのストレージ機構として使用します。この変更により、ロケール設定に関するクッキー同意の必要がなくなり、GDPR準拠が容易になります。
+
+### ストレージ設定オプション
+
+新しい `routing.storage` フィールドは、以前の `middleware.cookieName` および `middleware.serverSetCookie` オプションに加えて利用可能であり、柔軟なストレージ構成を提供します。
+
+```typescript
+// ストレージを無効化
+storage: false
+
+// シンプルなストレージタイプ
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// カスタム属性付きのクッキー
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// カスタムキー付きの localStorage
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// 冗長性のための複数ストレージタイプ
+storage: ['cookie', 'localStorage']
+```
+
+### GDPR準拠の設定例
+
+機能性とGDPR準拠のバランスを取る必要がある本番アプリケーション向け：
+
+```typescript
+typescript;
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // 主なストレージ（同意不要）
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // オプションのクッキーストレージ（同意が必要）
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### クッキーストレージの有効化 / 無効化
+
+React / Next.js を使用した例：
+
+グローバルに定義可能：
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+各フックでローカルに上書き可能：
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**注意:** クッキーはデフォルトで有効になっています。
+**注意:** ご利用のケースに応じて、[GDPRのクッキー要件](https://gdpr.eu/cookies/)を確認してください。
+
+---
+
+## ビジュアルエディター: 30% 小さくなったパッケージ
+
+ビジュアルエディターパッケージは、以下の理由により前バージョンより30%小さく最適化されました：
+
+- コードエディターのパフォーマンス向上
+- Intlayerコアパッケージの不要な依存関係の削除
+- より良いツリーシェイキングとモジュールバンドリング
+
+これにより、ダウンロード時間の短縮とアプリケーションの実行時パフォーマンスの向上が実現します。
+
+---
+
+## fillコマンド: より良いコンテンツ管理のための動作更新
+
+v7では、`fill`コマンドの動作が改善され、より予測可能で柔軟なコンテンツ管理が可能になりました：
+
+### 新しい fill の動作
+
+- **`fill: true`** - すべてのロケールに対して内容を埋めた状態で現在のファイルを書き換えます
+- **`fill: "path/to/file"`** - 現在のファイルを変更せずに指定したファイルを埋めます
+- **`fill: false`** - 自動埋めを完全に無効にします
+
+### 複雑なコンテンツ構造への対応強化
+
+fill コマンドは、以下を含む複雑なコンテンツ宣言構造をサポートするようになりました：
+
+- **合成オブジェクト**：他のオブジェクトを参照するコンテンツ宣言
+- **分割代入されたコンテンツ**：分割代入パターンを使用したコンテンツ
+- **ネストされた参照**：複雑な階層で互いに呼び合うオブジェクト
+- **動的コンテンツ構造**：条件付きまたは計算されたプロパティを持つコンテンツ
+
+### 利点
+
+- **意図の明確化**：何が変更されるかがより明確になりました
+- **より良い分離**: コンテンツファイルを翻訳済みファイルから分けて管理できます
+- **改善されたワークフロー**: 開発者は翻訳の保存場所をより細かく制御できます
+- **複雑な構造のサポート**: 複数の相互接続されたオブジェクトを持つ高度なコンテンツ構造を扱えます
+
+### 使用例
+
+```typescript
+// すべてのロケールで現在のファイルを書き換え
+const content = {
+  key: "example",
+  fill: true, // このファイルを書き換え
+  content: {
+    title: "Hello World",
+  },
+};
+
+// 現在のファイルを変更せずに別ファイルを埋める
+const content = {
+  key: "example",
+  fill: "./translations.json", // translations.jsonを作成/更新
+  content: {
+    title: "Hello World",
+  },
+};
+
+// 自動埋めを無効化
+const content = {
+  key: "example",
+  fill: false, // 自動埋めなし
+  content: {
+    title: "Hello World",
+  },
+};
+
+// 複合オブジェクトを用いた複雑なコンテンツ構造
+const sharedContent = {
+  buttons: {
+    save: "保存", // 保存ボタン
+    cancel: "キャンセル", // キャンセルボタン
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // 他のオブジェクトへの参照
+    sharedContent,
+
+    // 分割代入されたコンテンツ
+    ...sharedContent,
+
+    // ネストされた参照
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "セクション 1",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## 安定性と翻訳管理の強化
+
+v7では、コンテンツ翻訳をより信頼性が高く効率的にするためのいくつかの改善が導入されました。
+
+### コンテンツ宣言ファイルの完全更新
+
+システムは部分的な更新ではなく、`.content.{ts,js,cjs,mjs}` ファイル全体を更新するようになり、以下を保証します：
+
+- **データの完全性**: ファイル全体の書き換えにより、部分的な更新によってコンテンツが破損するのを防ぎます
+- **一貫性**: すべてのロケールが原子単位で更新され、同期が維持されます
+- **信頼性**: 不完全または不正なコンテンツファイルのリスクを低減します
+
+### インテリジェントなリトライ管理
+
+新しいリトライ機構により、不正な形式のコンテンツのプッシュを防ぎ、1つのリクエストが失敗しても全体のfillプロセスが壊れるのを回避します。
+
+### 高速処理のための並列化
+
+翻訳操作はキューで実行され、並列処理されるため、処理速度が大幅に向上します。
+
+### 大規模ファイルのためのスマートチャンク分割
+
+高度なチャンク分割戦略により、AIのコンテキストウィンドウを超えないように大規模なコンテンツファイルを処理します：
+
+### ワークフローの例
+
+```typescript
+// 大規模なコンテンツファイルが自動的にチャンク分割される
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // AI処理のために自動的にチャンク分割された大容量コンテンツ
+    introduction: "..." // 5000文字以上
+    sections: [
+      // 複数の大きなセクション
+    ]
+  }
+};
+```
+
+システムは自動的に以下を行います：
+
+1. コンテンツのサイズと構造を解析
+2. 適切にコンテンツをチャンク分割
+3. チャンクを並列処理
+4. 必要に応じて検証とリトライ
+5. 完全なファイルを再構築
+
+---
+
+## v6からの移行ノート
+
+### 削除された設定
+
+- **`middleware.cookieName`**：`routing.storage`に置き換え
+- **`middleware.serverSetCookie`**：`routing.storage`に置き換え
+- **`middleware.prefixDefault`**：`routing.mode`に置き換え
+- **`middleware.noPrefix`**：`routing.mode`に置き換え
+
+### 移行マッピング
+
+#### 設定マッピング
+
+| v6 設定                    | v7 設定                                                |
+| -------------------------- | ------------------------------------------------------ |
+| `autoFill: xxx`            | `fill: xxx`                                            |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                            |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                   |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                    |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`       |
+| `serverSetCookie: 'never'` | `storage: false` または storage 配列から cookie を削除 |
+
+#### マイグレーション例
+
+**以前 (v6):**
+
+````typescript
+export default {
+#### 設定マッピング
+
+| v6 設定                   | v7 設定                                              |
+| -------------------------- | ---------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                          |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                          |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                 |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                  |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`     |
+| `serverSetCookie: 'never'` | `storage: false` または storage 配列から cookie を削除 |
+
+#### マイグレーション例
+
+**以前 (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+````
+
+**以降 (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // cookie ストレージが必要な場合は 'cookie'
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### 辞書コンテンツのマッピング
+
+| v6 辞書コンテンツ | v7 辞書コンテンツ |
+| ----------------- | ----------------- |
+| `autoFill: xxx`   | `fill: xxx`       |
+
+#### マイグレーション例
+
+**以前 (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // このファイルを書き換えます
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+**After (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // このファイルを書き換えます
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+---
+
+## v5 から v6 へのマイグレーションノート
+
+詳細については、[v5 から v6 へのマイグレーションノート](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/releases/v6.md)を参照してください。
+
+---
+
+## 便利なリンク
+
+- [設定リファレンス](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)
+- [ミドルウェアドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/next-intlayer/index.md)
+- [TypeScript タイプ](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [GDPR クッキーガイドライン](https://gdpr.eu/cookies/)