paraglide-js

Paraglide JS

概要

Paraglide JS は、型付きメッセージ関数とランタイムヘルパーを生成する、コンパイラベースの i18n ライブラリです。プロジェクトで Paraglide のセットアップ、メッセージの使用、ロケールの検出、SSR の統合、または生成された paraglide/ 出力に関連するリファクタリングが必要な場合に、このスキルを使用してください。

使用する場面

• 新規または既存のアプリに Paraglide JS を追加する
• ロケール戦略の順序やカスタム戦略を更新する
• paraglideMiddleware() を使った SSR のロケール検出を組み込む
• Paraglide を TanStack Start に統合する
• モノレポで 1 つの project.inlang を再利用する

一般的なコピーライティングや翻訳品質のレビューには、このスキルを使用しないでください。コードの統合とランタイムの動作を対象としています。

基本的なワークフロー

1. アプリの構成を特定します。Vite アプリ、SSR アプリ、TanStack Start アプリ、またはモノレポのいずれかです。
2. Vite ベースのアプリでは、Vite プラグインを優先します。
3. バンドラーとの統合が利用できない場合、またはパッケージに明示的なコンパイルスクリプトが必要な場合は、CLI によるコンパイルを使用します。
4. SSR／サーバーのリクエストフローに限り、サーバーミドルウェアを追加します。
5. project.inlang とメッセージファイルを信頼できる情報源とし、生成された paraglide/ 出力はビルド成果物として扱います。
6. メッセージ、ロケール、戦略、または出力設定を変更したら、再コンパイルします。

基本方針

• Vite プロジェクトでは、生成された出力を手作業で作成するのではなく、paraglideVitePlugin() を優先します。
• カスタム戦略を追加する前に、組み込み戦略を優先します。
• 戦略の順序を意図的に決めます。先にある戦略が優先されます。
• URL の書き換えを担当する箇所は 1 つにします。リダイレクトループが発生しないか確認せずに、ルーターレベルの URL 書き換えとミドルウェアによる URL ローカライズを組み合わせないでください。
• モノレポでは、すべてのコンシューマーが同一の戦略／ランタイムを共有できる場合を除き、「各パッケージがコンパイルする」方針をデフォルトとします。

リファレンスガイド

• セットアップ、生成ファイル、メッセージ／ランタイムの使い方については、references/basics.md をお読みください。
• 戦略の順序とカスタム戦略については、references/strategies.md をお読みください。
• TanStack Start の統合パターンについては、references/tanstack-start.md をお読みください。
• パッケージ間で project.inlang を共有するパターンについては、references/monorepo.md をお読みください。

よくある間違い

• 元のメッセージや設定を変更せず、生成された src/paraglide/* ファイルを直接編集する
• messages/*.json または project.inlang/settings.json を変更した後、再コンパイルを忘れる
• クライアントのみの SPA に paraglideMiddleware() を追加する
• リダイレクトの動作を考慮せず、url より前に優先設定の戦略を置く
• ループが発生しないかテストせずに、TanStack Router の書き換えと URL ベースのミドルウェアローカライズを併用する

外部ソース

• 公式ドキュメント：https://inlang.com/m/gerre34r/library-inlang-paraglideJs/
• Vite ガイド：https://inlang.com/m/gerre34r/library-inlang-paraglideJs/vite
• モノレポガイド：https://inlang.com/m/gerre34r/library-inlang-paraglideJs/monorepo
• ミドルウェアガイド：https://inlang.com/m/gerre34r/library-inlang-paraglideJs/middleware
• TanStack Router i18n ガイド：https://tanstack.com/router/v1/docs/framework/react/guide/internationalization-i18n