Intlayerの今後のリリースに関する通知を受け取る
    著者: AydinTheFirst
    作成:2025-09-09最終更新:2025-09-09

    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パッケージのインストール

    お好みのパッケージマネージャーを使って必要なパッケージをインストールします:

    bash
    npm install intlayer react-intlayernpm install vite-intlayer --save-dev
    • intlayer

    コアパッケージであり、設定管理、翻訳、コンテンツ宣言、トランスパイル、およびCLIコマンドのための国際化ツールを提供します。

    • react-intlayer
      IntlayerをReactアプリケーションと統合するパッケージです。Reactの国際化のためのコンテキストプロバイダーやフックを提供します。

    • vite-intlayer
      IntlayerをViteバンドラーと統合するためのViteプラグインを含み、ユーザーの優先ロケール検出、クッキー管理、URLリダイレクト処理のためのミドルウェアも提供します。

    ステップ3: プロジェクトの設定

    アプリケーションの言語を設定するための設定ファイルを作成します:

    intlayer.config.ts
    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プラグインを追加します:

    vite.config.ts
    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.tsx
    // 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: コンテンツを宣言する

    翻訳を保存するためのコンテンツ宣言を作成および管理します:

    src/contents/page.content.ts
    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
    // 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
    // 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.tsx
    // 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} />;}

    ローカライズされたホームページ

    src/routes/{-$locale}/index.tsx
    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: ロケールスイッチャーコンポーネントの作成

    ユーザーが言語を切り替えられるコンポーネントを作成します:

    src/components/locale-switcher.tsx
    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.tsx
    // 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]);};

    次に、ルートコンポーネントでこれを使用します:

    src/routes/{-$locale}/index.tsx
    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: アプリケーションのビルドと実行

    コンテンツ辞書をビルドし、アプリケーションを実行します:

    bash
    # Intlayerの辞書をビルドnpm run intlayer:build# 開発サーバーを起動npm run dev

    ステップ12: TypeScriptの設定(任意)

    Intlayerはモジュール拡張を使用してTypeScriptの利点を活かし、コードベースをより強固にします。

    TypeScriptの設定に自動生成された型が含まれていることを確認してください:

    tsconfig.json
    {  compilerOptions: {    // ... 既存のTypeScript設定  },  include: [    // ... 既存のインクルード    ".intlayer/**/*.ts", // 自動生成された型を含める  ],}

    Git設定

    Intlayerによって生成されたファイルは無視することを推奨します。これにより、Gitリポジトリへのコミットを避けることができます。

    これを行うには、.gitignoreファイルに以下の指示を追加してください:

    .gitignore
    # Intlayerによって生成されたファイルを無視する.intlayer

    ステップ13: リダイレクトの作成(オプション)

    src/routes/{-$locale}/rotue.tsx
    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>);}

    本番環境へのデプロイ

    アプリケーションをデプロイする際は、以下の手順を行ってください:

    1. アプリケーションをビルドする:

      bash
      npm run build
    2. Intlayerの辞書をビルドする:

      bash
      npm run intlayer:build
    3. 本番環境でミドルウェアを使用する場合は、vite-intlayerを依存関係に移動する:

      bash
      npm install vite-intlayer --save

    これでアプリケーションは以下をサポートします:

    • URL構造: /en, /en/about, /tr, /tr/about
    • ブラウザの設定に基づく自動ロケール検出
    • Tanstack Startによるロケール対応ルーティング
    • 自動生成された型定義によるTypeScriptサポート
    • 適切なロケール処理を行うサーバーサイドレンダリング

    VS Code拡張機能

    Intlayerでの開発体験を向上させるために、公式のIntlayer VS Code拡張機能をインストールできます。

    VS Codeマーケットプレイスからインストール

    この拡張機能は以下を提供します:

    • 翻訳キーのオートコンプリート
    • 翻訳が不足している場合のリアルタイムエラー検出
    • 翻訳されたコンテンツのインラインプレビュー
    • 翻訳の作成や更新を簡単に行うためのクイックアクション

    拡張機能の使い方の詳細については、Intlayer VS Code拡張機能のドキュメントを参照してください。


    さらに進む

    さらに進めるには、ビジュアルエディターを実装するか、CMSを使用してコンテンツを外部化することができます。


    ドキュメント参照

    この包括的なガイドは、IntlayerをTanstack Startと統合し、ロケール対応のルーティングとTypeScriptサポートを備えた完全な国際化アプリケーションを構築するために必要なすべてを提供します。

    ドキュメント履歴

    バージョン 日付 変更内容
    5.8.1 2025-09-09 Tanstack Start向けに追加
    Intlayerの今後のリリースに関する通知を受け取る