新しい 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ではビルドプロセスを高速化するキャッシュ戦略を実装しています。

npx intlayer build

新しいキャッシュシステムは以下を実現します：

• コンパイル済みのコンテンツ宣言を保存し、冗長な処理を回避
• 変更を検出し、変更されたファイルのみを再構築
• 大規模プロジェクトのビルド時間を大幅に短縮

TypeScript：ロケール別の型生成

TypeScriptの型はロケールごとに生成されるようになり、より強力な型付けが可能となり、全ロケールにまたがるユニオン型を排除します。

v6の挙動：

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

v7の挙動：

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" }

利点:

• IDEでのより正確なオートコンプリート
• ロケール間の型汚染がなく、より良い型安全性
• 型の複雑さを減らすことでパフォーマンスが向上

バンドル最適化: 文字列としてのロケール

Locales型はもはや列挙型(enum)ではなくなり、完全にツリーシェイク可能となったため、使用されていない何千ものロケールレコードでバンドルが膨らむことがありません。

v6:

import { Locales } from "intlayer";// すべてのロケールを含む列挙型 -> ツリーシェイク不可const locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// 文字列型 -> 完全にツリーシェイク可能const locale: Locale = Locales.ENGLISH;

Localesはもはやenumではないため、型としてロケールを取得するには、型をLocalesからLocaleに変更する必要があります。

詳細については、実装の詳細をご覧ください。

より柔軟な新しいルーティングモード

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

基本設定

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default", // デフォルト  },};

GDPR準拠：localStorage / クッキーのストレージ

v7では、ユーザーのプライバシーを優先し、クッキーの代わりに localStorage をデフォルトのストレージ機構として使用します。この変更により、ロケール設定に関するクッキー同意の必要がなくなり、GDPR準拠が容易になります。

ストレージ設定オプション

新しい routing.storage フィールドは、以前の middleware.cookieName および middleware.serverSetCookie オプションに加えて利用可能であり、柔軟なストレージ構成を提供します。

// ストレージを無効化storage: false// シンプルなストレージタイプstorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// カスタム属性付きのクッキーstorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// カスタムキー付きの localStoragestorage: {  type: 'localStorage',  name: 'custom-locale'}// 冗長性のための複数ストレージタイプstorage: ['cookie', 'localStorage']

GDPR準拠の設定例

機能性とGDPR準拠のバランスを取る必要がある本番アプリケーション向け：

typescript;// intlayer.config.tsexport 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 を使用した例：

グローバルに定義可能：

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

各フックでローカルに上書き可能：

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

注意: クッキーはデフォルトで有効になっています。 注意: ご利用のケースに応じて、GDPRのクッキー要件を確認してください。

ビジュアルエディター: 30% 小さくなったパッケージ

ビジュアルエディターパッケージは、以下の理由により前バージョンより30%小さく最適化されました：

• コードエディターのパフォーマンス向上
• Intlayerコアパッケージの不要な依存関係の削除
• より良いツリーシェイキングとモジュールバンドリング

これにより、ダウンロード時間の短縮とアプリケーションの実行時パフォーマンスの向上が実現します。

自動コードフォーマット: formatCommand 設定

v7 では、エディタ設定に formatCommand オプションが導入されました。これにより、Intlayer によってコンテンツファイルが書き込まれるときに、自動的にコンテンツをフォーマットできます。これにより、コンテンツ宣言ファイル全体で一貫したコードスタイルとフォーマットが保証されます。

設定されていない場合、Intlayer は自動的にフォーマットコマンドを検出しようとします。次のコマンドの解決を試みます: prettier、biome、eslint。

設定

formatCommand オプションは、{{file}} が実際のファイルパスに置き換わる文字列テンプレートを受け入れます:

export default {  content: {    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',  },};

サポートされているフォーマッター

ファイルパスを引数として受け入れる任意のコードフォーマッターを使用できます:

Biomeを使用:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Prettierを使用:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

ESLintを使用:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Bunの組み込みフォーマッターを使用:

formatCommand: 'bun format "{{file}}"';

メリット

• 一貫性のあるフォーマット: すべてのコンテンツファイルは、プロジェクトのスタイルガイドラインに従って自動的にフォーマットされます
• 開発者体験: Intlayerがファイルを作成した後、手動でフォーマットする必要がありません
• チーム間の一貫性: すべてのチームメンバーが同じフォーマットをコンテンツファイルに適用していることを保証します
• CI/CD統合: コンテンツファイルは自動化されたワークフローで一貫性のあるフォーマットを維持します

仕組み

Intlayer がコンテンツ宣言ファイル（.content.ts、.content.js など）を書き込みまたは更新する場合、指定された format コマンドをファイルに対して自動的に実行します。{{file}} プレースホルダーは実際のファイル パスに置き換えられ、コマンドはプロジェクトのベース ディレクトリで実行されます。

辞書設定: より良い組織化と構造

v7では、辞書関連の設定をより良く組織化し、コンテンツ管理を改善する新しい専用のdictionary設定セクションが導入されています。

新しい dictionary 設定構造

fill プロパティが content セクションから新しい dictionary セクションに移動され、より明確な関心の分離を提供します:

v6 設定:

export default {  content: {    autoFill: "./{{fileName}}.content.json",    contentDir: ["src"],  },};

v7 設定:

export default {  content: {    contentDir: ["src"],  },  dictionary: {    fill: "./{{fileName}}.content.json",  },};

新しい構造のメリット

• より明確な組織: 辞書固有の設定がまとめられています
• 関心の分離の向上: コンテンツディスカバリーと辞書操作が明確に分離されています
• 保守性の向上: 辞書関連の設定を理解および変更しやすくなっています
• 将来の拡張性: 辞書セクションは追加の辞書固有の設定に対応できます
• 包括的な辞書管理: 新しい辞書を作成および管理するための title、live、priority、tags、version、description などのプロパティが含まれています

設定の使用方法

辞書設定には、2つの主な目的があります：

1. デフォルト値: コンテンツ宣言ファイルを作成する際のデフォルト値を定義します
2. フォールバック動作: 特定のフィールドが定義されていない場合にフォールバック値を提供し、辞書の動作をグローバルに定義できます

辞書セクションには、辞書管理のための包括的なプロパティが含まれています：

• fill: コンテンツ生成の自動入力動作
• title: 新しい辞書のデフォルトタイトル
• live: リアルタイム更新のためのライブ同期設定
• priority: 辞書解決の優先度設定
• tags: コンテンツ整理のためのデフォルトタグ
• version: 辞書更新のバージョン管理
• description: 新しいコンテンツのデフォルト説明

コンテンツ宣言ファイルおよび設定値がどのように適用されるかについての詳細は、コンテンツファイルドキュメンテーションを参照してください。

fillコマンド: より良いコンテンツ管理のための動作更新

v7では、fillコマンドの動作が改善され、より予測可能で柔軟なコンテンツ管理が可能になりました：

新しい fill の動作

• fill: true - すべてのロケールに対して内容を埋めた状態で現在のファイルを書き換えます
• fill: "path/to/file" - 現在のファイルを変更せずに指定したファイルを埋めます
• fill: false - 自動埋めを完全に無効にします

複雑なコンテンツ構造への対応強化

fill コマンドは、以下を含む複雑なコンテンツ宣言構造をサポートするようになりました：

• 合成オブジェクト：他のオブジェクトを参照するコンテンツ宣言
• 分割代入されたコンテンツ：分割代入パターンを使用したコンテンツ
• ネストされた参照：複雑な階層で互いに呼び合うオブジェクト
• 動的コンテンツ構造：条件付きまたは計算されたプロパティを持つコンテンツ

利点

• 意図の明確化：何が変更されるかがより明確になりました
• より良い分離: コンテンツファイルを翻訳済みファイルから分けて管理できます
• 改善されたワークフロー: 開発者は翻訳の保存場所をより細かく制御できます
• 複雑な構造のサポート: 複数の相互接続されたオブジェクトを持つ高度なコンテンツ構造を扱えます

使用例

// すべてのロケールで現在のファイルを書き換え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のコンテキストウィンドウを超えないように大規模なコンテンツファイルを処理します：

ワークフローの例

// 大規模なコンテンツファイルが自動的にチャンク分割される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に置き換え

新しい設定

• editor.formatCommand: コンテンツファイルの自動コードフォーマットのための新しいオプション

移行マッピング

設定マッピング

マイグレーション例

以前 (v6):

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

以降 (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // cookie ストレージが必要な場合は 'cookie'    headerName: "x-intlayer-locale",    basePath: "",  },};

辞書コンテンツのマッピング

マイグレーション例

以前 (v6):

const content = {  key: "example",  autoFill: true, // このファイルを書き換えます  content: {    title: "Hello World",  },};

After (v7):

const content = {  key: "example",  fill: true, // このファイルを書き換えます  content: {    title: "Hello World",  },};

v5 から v6 へのマイグレーションノート

詳細については、v5 から v6 へのマイグレーションノートを参照してください。

便利なリンク

• 設定リファレンス
• ミドルウェアドキュメント
• TypeScript タイプ
• GDPR クッキーガイドライン