このページとあなたの好きなAIアシスタントを使ってドキュメントを要約します
Intlayer MCPサーバーを統合することで、ChatGPT、DeepSeek、Cursor、VSCodeなどから直接ドキュメントを取得できます。
MCPサーバーのドキュメントを表示このページのコンテンツはAIを使用して翻訳されました。
英語の元のコンテンツの最新バージョンを見るこのドキュメントを改善するアイデアがある場合は、GitHubでプルリクエストを送信することで自由に貢献してください。
ドキュメントへのGitHubリンクドキュメントのMarkdownをクリップボードにコピー
IntlayerとTanstack Startによる国際化(i18n)入門
このガイドでは、Tanstack Startプロジェクトにおいて、ロケール対応ルーティング、TypeScriptサポート、最新の開発手法を活用しながら、Intlayerを統合してシームレスな国際化を実現する方法を示します。
Intlayerとは?
Intlayerは、最新のウェブアプリケーションにおける多言語対応を簡素化するために設計された革新的なオープンソースの国際化(i18n)ライブラリです。
Intlayerを使うことで、以下が可能になります:
- コンポーネントレベルで宣言的な辞書を使い、翻訳を簡単に管理できます。
- メタデータ、ルート、コンテンツを動的にローカライズできます。
- 自動生成される型によりTypeScriptサポートを確保し、オートコンプリートやエラー検出を向上させます。
- 動的なロケール検出や切り替えなどの高度な機能を活用できます。
- Tanstack Startのファイルベースのルーティングシステムを使ってロケール対応ルーティングを有効化します。
Tanstack StartアプリケーションでIntlayerをセットアップするステップバイステップガイド
ステップ1:プロジェクトの作成
TanStack Startの公式サイトにある新しいプロジェクトの開始ガイドに従って、新しいTanStack Startプロジェクトを作成します。
ステップ2:Intlayerパッケージのインストール
お好みのパッケージマネージャーを使って必要なパッケージをインストールします:
コードをクリップボードにコピー
npm install intlayer react-intlayernpm install vite-intlayer --save-dev
- intlayer
コアパッケージであり、設定管理、翻訳、コンテンツ宣言、トランスパイル、およびCLIコマンドのための国際化ツールを提供します。
react-intlayer
IntlayerをReactアプリケーションと統合するパッケージです。Reactの国際化のためのコンテキストプロバイダーやフックを提供します。vite-intlayer
IntlayerをViteバンドラーと統合するためのViteプラグインを含み、ユーザーの優先ロケール検出、クッキー管理、URLリダイレクト処理のためのミドルウェアも提供します。
ステップ3: プロジェクトの設定
アプリケーションの言語を設定するための設定ファイルを作成します:
コードをクリップボードにコピー
import type { IntlayerConfig } from "intlayer";import { Locales } from "intlayer";const config: IntlayerConfig = { internationalization: { defaultLocale: Locales.ENGLISH, // デフォルトのロケール locales: [ Locales.ENGLISH, // 英語 Locales.FRENCH, // フランス語 Locales.SPANISH, // スペイン語 // 他のロケールを追加 ], },};export default config;
この設定ファイルを通じて、ローカライズされたURL、ミドルウェアのリダイレクション、クッキー名、コンテンツ宣言の場所と拡張子、コンソールでのIntlayerログの無効化などを設定できます。利用可能なパラメータの完全なリストについては、設定ドキュメントを参照してください。
ステップ4: Vite設定にIntlayerを統合する
設定にintlayerプラグインを追加します:
コードをクリップボードにコピー
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [ reactRouter(), tsconfigPaths(), intlayerPlugin(), intlayerMiddlewarePlugin(), ],});
intlayerPlugin() Viteプラグインは、IntlayerをViteに統合するために使用されます。これにより、コンテンツ宣言ファイルのビルドが保証され、開発モードでの監視が行われます。また、Viteアプリケーション内でIntlayerの環境変数を定義します。さらに、パフォーマンス最適化のためのエイリアスも提供します。
ステップ5: レイアウトコンポーネントの作成
ルートレイアウトとロケール固有のレイアウトを設定します。
ルートレイアウト
コードをクリップボードにコピー
// src/routes/{-$locale}/route.tsximport { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";export const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { const { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale}> <Outlet /> </IntlayerProvider> );}
ステップ6: コンテンツを宣言する
翻訳を保存するためのコンテンツ宣言を作成および管理します:
コードをクリップボードにコピー
import type { Dictionary } from "intlayer";import { t } from "intlayer";const appContent = { content: { links: { about: t({ en: "About", es: "Acerca de", fr: "À propos", }), home: t({ en: "ホーム", es: "Inicio", fr: "Accueil", }), }, meta: { description: t({ en: "これは Intlayer と TanStack Router を使用した例です", es: "Este es un ejemplo de uso de Intlayer con TanStack Router", fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router", }), }, title: t({ en: "Intlayer + TanStack Router へようこそ", es: "Bienvenido a Intlayer + TanStack Router", fr: "Bienvenue à Intlayer + TanStack Router", }), }, key: "app",} satisfies Dictionary;export default appContent;
コンテンツ宣言は、アプリケーション内のどこにでも定義できますが、contentDir ディレクトリ(デフォルトは ./app)に含まれている必要があります。また、コンテンツ宣言ファイルの拡張子(デフォルトは .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx})に一致している必要があります。
詳細については、コンテンツ宣言のドキュメントを参照してください。
ステップ7: ロケール対応コンポーネントとフックを作成する
ロケール対応のナビゲーション用に LocalizedLink コンポーネントを作成します:
コードをクリップボードにコピー
// src/components/localized-link.tsx// eslint-disable-next-line no-restricted-importsimport { Link, type LinkProps } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedLinkProps = { to: string;} & Omit<LinkProps, "to">;export function LocalizedLink(props: LocalizedLinkProps) { const { locale } = useLocale(); const isExternal = (to: string) => { return /^(https?:)?\/\//.test(to); }; const to = isExternal(props.to) ? props.to : getLocalizedUrl(props.to, locale); return <Link {...props} to={to as LinkProps["to"]} />;}
プログラム的なナビゲーションのために useLocalizedNavigate フックを作成します:
コードをクリップボードにコピー
// src/hooks/useLocalizedNavigate.tsx// eslint-disable-next-line no-restricted-importsimport { NavigateOptions, useNavigate } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedNavigateOptions = { to: string;} & Omit<NavigateOptions, "to">;export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const isExternal = (to: string) => { return /^(https?:)?\/\//.test(to); }; const localizedNavigate = (options: LocalizedNavigateOptions) => { const to = isExternal(options.to) ? options.to : getLocalizedUrl(options.to, locale); navigate({ ...options, to: to as NavigateOptions["to"] }); }; return localizedNavigate;};
ステップ8: ページでIntlayerを活用する
アプリケーション全体でコンテンツ辞書にアクセスします:
ルートリダイレクトページ
コードをクリップボードにコピー
// src/routes/page.tsximport { useLocale } from "react-intlayer";import { Navigate } from "react-router";export default function Page() { const { locale } = useLocale(); return <Navigate replace to={locale} />;}
ローカライズされたホームページ
コードをクリップボードにコピー
import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";import { useIntlayer } from "react-intlayer";import LocaleSwitcher from "@/components/locale-switcher";import { LocalizedLink } from "@/components/localized-link";import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: ({ params }) => { const { locale } = params; const metaContent = getIntlayer("app", locale); return { meta: [ { title: metaContent.title }, { content: metaContent.meta.description, name: "description" }, ], }; },});function RouteComponent() { const content = useIntlayer("app"); const navigate = useLocalizedNavigate(); return ( <div className="grid place-items-center h-screen"> <div className="flex flex-col gap-4 items-center text-center"> {content.title} <LocaleSwitcher /> <div className="flex gap-4"> <a href="/">インデックス</a> <LocalizedLink to="/">{content.links.home}</LocalizedLink> <LocalizedLink to="/about">{content.links.about}</LocalizedLink> </div> <div className="flex gap-4"> <button onClick={() => navigate({ to: "/" })}> {content.links.home} </button> <button onClick={() => navigate({ to: "/about" })}> {content.links.about} </button> </div> </div> </div> );}
useIntlayer フックの詳細については、ドキュメントを参照してください。
ステップ9: ロケールスイッチャーコンポーネントの作成
ユーザーが言語を切り替えられるコンポーネントを作成します:
コードをクリップボードにコピー
import { useLocation } from "@tanstack/react-router";import { getHTMLTextDir, getLocaleName, getLocalizedUrl, Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";export default function LocaleSwitcher() { const { pathname, searchStr } = useLocation(); const content = useIntlayer("locale-switcher"); const { availableLocales, locale, setLocale } = useLocale({ onLocaleChange: (newLocale) => { const pathWithLocale = getLocalizedUrl(pathname + searchStr, newLocale); location.replace(pathWithLocale); }, }); return ( <select aria-label={content.label.toString()} onChange={(e) => setLocale(e.target.value)} value={locale} > {availableLocales.map((localeItem) => ( <option dir={getHTMLTextDir(localeItem)} key={localeItem} lang={localeItem} value={localeItem} > {/* 例: Français (フランス語) */} {getLocaleName(localeItem, locale)} ( {getLocaleName(localeItem, Locales.ENGLISH)}) </option> ))} </select> );}
useLocale フックの詳細については、ドキュメントを参照してください。
ステップ10: HTML属性の管理を追加(オプション)
HTMLのlangおよびdir属性を管理するフックを作成します:
コードをクリップボードにコピー
// src/hooks/useI18nHTMLAttributes.tsximport { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { document.documentElement.lang = locale; // HTMLのlang属性を設定 document.documentElement.dir = getHTMLTextDir(locale); // HTMLのdir属性を設定 }, [locale]);};
次に、ルートコンポーネントでこれを使用します:
コードをクリップボードにコピー
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // フックをインポートexport const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { useI18nHTMLAttributes(); // この行を追加 const { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale}> <Outlet /> </IntlayerProvider> );}
ステップ11: アプリケーションのビルドと実行
コンテンツ辞書をビルドし、アプリケーションを実行します:
コードをクリップボードにコピー
# Intlayerの辞書をビルドnpm run intlayer:build# 開発サーバーを起動npm run dev
ステップ12: TypeScriptの設定(任意)
Intlayerはモジュール拡張を使用してTypeScriptの利点を活かし、コードベースをより強固にします。
TypeScriptの設定に自動生成された型が含まれていることを確認してください:
コードをクリップボードにコピー
{ compilerOptions: { // ... 既存のTypeScript設定 }, include: [ // ... 既存のインクルード ".intlayer/**/*.ts", // 自動生成された型を含める ],}
Git設定
Intlayerによって生成されたファイルは無視することを推奨します。これにより、Gitリポジトリへのコミットを避けることができます。
これを行うには、.gitignoreファイルに以下の指示を追加してください:
コードをクリップボードにコピー
# Intlayerによって生成されたファイルを無視する.intlayer
ステップ13: リダイレクトの作成(オプション)
コードをクリップボードにコピー
function LayoutComponent() { useI18nHTMLAttributes(); const { locale } = Route.useParams(); const { locale: selectedLocale } = useLocale(); const { defaultLocale } = configuration.internationalization; const { prefixDefault } = configuration.middleware; // prefixDefault が true の場合、URL にロケールが存在しないときはデフォルトロケールへリダイレクトする if (selectedLocale === defaultLocale && !locale && prefixDefault) { return <Navigate replace to={defaultLocale} />; } // URL のロケールが選択されたロケールと一致しない場合は選択されたロケールへリダイレクトする if (selectedLocale !== defaultLocale && !locale) { return <Navigate replace to={selectedLocale} />; } return ( <IntlayerProvider locale={locale}> <Outlet /> </IntlayerProvider>);}
本番環境へのデプロイ
アプリケーションをデプロイする際は、以下の手順を行ってください:
アプリケーションをビルドする:
bashコードをコピーコードをクリップボードにコピー
npm run build
Intlayerの辞書をビルドする:
bashコードをコピーコードをクリップボードにコピー
npm run intlayer:build
本番環境でミドルウェアを使用する場合は、vite-intlayerを依存関係に移動する:
bashコードをコピーコードをクリップボードにコピー
npm install vite-intlayer --save
これでアプリケーションは以下をサポートします:
- URL構造: /en, /en/about, /tr, /tr/about
- ブラウザの設定に基づく自動ロケール検出
- Tanstack Startによるロケール対応ルーティング
- 自動生成された型定義によるTypeScriptサポート
- 適切なロケール処理を行うサーバーサイドレンダリング
VS Code拡張機能
Intlayerでの開発体験を向上させるために、公式のIntlayer VS Code拡張機能をインストールできます。
この拡張機能は以下を提供します:
- 翻訳キーのオートコンプリート。
- 翻訳が不足している場合のリアルタイムエラー検出。
- 翻訳されたコンテンツのインラインプレビュー。
- 翻訳の作成や更新を簡単に行うためのクイックアクション。
拡張機能の使い方の詳細については、Intlayer VS Code拡張機能のドキュメントを参照してください。
さらに進む
さらに進めるには、ビジュアルエディターを実装するか、CMSを使用してコンテンツを外部化することができます。
ドキュメント参照
この包括的なガイドは、IntlayerをTanstack Startと統合し、ロケール対応のルーティングとTypeScriptサポートを備えた完全な国際化アプリケーションを構築するために必要なすべてを提供します。
ドキュメント履歴
バージョン | 日付 | 変更内容 |
---|---|---|
5.8.1 | 2025-09-09 | Tanstack Start向けに追加 |