Intlayerを使用したAstro + Reactサイトの翻訳

目次

代替手段ではなく Interlayer を使用する理由

「astro-i18n」や「i18next」などの主要なソリューションと比較して、Intlayer は次のような統合された最適化を備えたソリューションです。

Astro + ReactへのIntlayer設定ステップバイステップガイド

GitHubでアプリケーションテンプレートを表示。

1. 1

   依存関係のインストール

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

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   npx intlayer init --interactive
   

   --interactive フラグはオプションです。AI エージェントの場合は intlayer-cli init を使用してください。

   このコマンドは環境を検出し、必要なパッケージをインストールします。例えば：

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   npm install intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
   

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

   • astro-intlayer Intlayer を Vite バンドラー と統合する Astro 統合プラグイン、各リクエストのロケールを Astro.locals.intlayer に解決するミドルウェア、および useIntlayer / useDictionary / useLocale フックが含まれています。同じインポートパスが .astro フロントマターのサーバー実装と <script> ブロック内のクライアント実装（vanilla-intlayer ベース）に解決されます。

   • react, react-dom ブラウザでReactコンポーネントをレンダリングするために必要なコアReactパッケージ。

   • react-intlayer IntlayerをReactアプリケーションと統合するパッケージ。Reactにおける国際化のための IntlayerProvider、useIntlayer および useLocale フックを提供します。

   • @astrojs/react Reactコンポーネントアイランドの使用を可能にする公式のAstro統合。

2. 2

   プロジェクトの設定

   アーキテクチャ

   このアーキテクチャでは、astro.config.ts に登録された intlayer() 統合が辞書をビルドし、各リクエストのロケールを解決して Astro.locals.intlayer に公開するミドルウェアを追加します。ページは src/pages/[...locale]/ レストセグメントの下に配置されるため、デフォルトロケールはプレフィックスなしで提供され、他のすべてのロケールには専用の URL が割り当てられます。.astro ファイルはサーバーレンダリング用に astro-intlayer の useIntlayer / useLocale フックを使用してコンテンツを読み取り、React アイランド (src/components/react/ReactIsland.tsx) はサーバーで検出されたロケールを prop として受け取り、インタラクティブ部分のために react-intlayer に渡します。コンテンツ宣言は src/ 内のコンポーネントと一緒に配置されます。

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   .
   ├── src
   │   ├── app.content.tsx               # App content declaration
   │   ├── components
   │   │   └── react
   │   │       ├── LocaleSwitcher.tsx    # Locale switcher rendered inside the island
   │   │       └── ReactIsland.tsx       # React island wrapping the tree in IntlayerProvider
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page mounting the island
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() and react() integrations
   ├── intlayer.config.ts
   ├── package.json
   └── tsconfig.json
   

   設定

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

   intlayer.config.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // その他のロケール
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   この設定ファイルを使用して、ローカライズされたURL、ミドルウェアのリダイレクト、クッキー名、コンテンツ宣言の場所と拡張子、コンソールでのIntlayerログの無効化などを設定できます。利用可能なパラメータの全リストについては、設定ドキュメントを参照してください。

   設定ドキュメント
3. 3

   Astro設定へのIntlayerの統合

   Astroの設定にintlayerプラグインとReact統合を追加します。

   astro.config.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import react from "@astrojs/react";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer(), react()],
   });
   

   Astro統合プラグイン intlayer() は、IntlayerをAstroと統合するために使用されます。コンテンツ宣言ファイルの構築を確実にし、開発モードで監視します。Astroアプリケーション内でIntlayerの環境変数を定義し、パフォーマンス最適化のためのエイリアスを提供します。

   react() 統合により、client:only="react" を通じてReactコンポーネントアイランドを使用できるようになります。

4. 4

   コンテンツの宣言

   翻訳を保存するためのコンテンツ宣言を作成・管理します：

   src/app.content.tsx

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { t, type Dictionary } from "intlayer";
   import type { ReactNode } from "react";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
         ja: "こんにちは世界",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   コンテンツ宣言は、contentDir（デフォルトは ./src）に含まれ、コンテンツ宣言ファイルの拡張子（デフォルトは .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）と一致していれば、アプリケーション内のどこにでも定義できます。

   詳細については、コンテンツ宣言のドキュメントを参照してください。

   コンテンツ宣言のドキュメント
5. 5

   Astroでのコンテンツの使用

   astro-intlayer がエクスポートするフックを使用して、.astro ファイルで辞書を利用します。これらは react-intlayer と同じシグネチャを共有しており、useIntlayer("key") は辞書の内容を返し、useLocale() は現在のロケールを引数なしで返します。

   ロケールは astro-intlayer ミドルウェアから取得されます。このミドルウェアは独自の src/middleware.ts の前に登録され、各リクエストについて URL プレフィックス、クライアントが保持するロケール（Cookie またはヘッダー）、Accept-Language の順に解決し、Astro.locals.intlayer に保存します。事前レンダリングされたページは訪問者ごとに一度だけレンダリングされるため、URL のみを使用します。

   また、各ページにhreflangや正規リンクなどのSEOメタデータを追加し、クライアントサイドのインタラクティブなコンテンツのためにReactアイランドを組み込む必要があります。

   src/pages/[...locale]/index.astro

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     getPrefix,
     localeMap,
     defaultLocale,
     getHTMLTextDir,
   } from "intlayer";
   import { ReactIsland } from "../../components/react/ReactIsland";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   // ミドルウェアによって解決されたロケール（例: /ja/about -> 'ja'）
   const { locale } = useLocale();
   
   // そのロケールの 'app' 辞書の内容
   const { title } = useIntlayer("app");
   ---
   
   <!doctype html>
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{title}</title>
   
       <!-- 正規リンク: このページのプライマリバージョンであることを検索エンジンに伝えます -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: すべてのローカライズされたバージョンについてGoogleに伝えます -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: 言語が一致しないユーザー向けのフォールバックオプション -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <!-- Reactアイランドは言語切り替えを含むすべてのインタラクティブなコンテンツをレンダリングします -->
       <ReactIsland locale={locale} client:only="react" />
     </body>
   </html>
   

   alt、title、href、aria-label などの 文字列 属性でコンテンツを使用したい場合は、次のように関数の値を使用できます。

   tsx

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   <img src={content.image.src.value} alt={content.image.value} />
   <img src={content.image.src.toString()} alt={content.image.toString()} />
   <img src={String(content.image.src)} alt={String(content.image)} />
   

   Astro.locals.intlayer は、独自のミドルウェアやエンドポイントにも locale、defaultLocale、availableLocales を公開します。第2引数としてロケールまたはセレクターを渡すことで（useIntlayer("app", "fr")、useIntlayer("faq", { item: 2 })）、1回の呼び出しに対してリクエストロケールを上書きできます。

   ルーティング設定に関する注意: 使用するディレクトリ構造は、intlayer.config.ts の middleware.routing 設定によります：

   • prefix-no-default（デフォルト）: ルート（プレフィックスなし）にデフォルト言語を保持し、他の言語にはプレフィックスを付けます。すべてのケースをキャッチするために [...locale] を使用します。
   • prefix-all: すべてのURLに言語プレフィックスが付きます。ルートを個別に処理する必要がない場合は、標準の [locale] を使用できます。
   • search-param または no-prefix: ロケールフォルダは不要です。ロケールは検索パラメータまたはクッキーを通じて処理されます。

6. 6

   Reactアイランドコンポーネントの作成

   Reactアプリケーションをラップし、サーバーによって検出されたロケールを受け取るアイランドコンポーネントを作成します：

   src/components/react/ReactIsland.tsx

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   /** @jsxImportSource react */
   import { IntlayerProvider, useIntlayer } from "react-intlayer";
   import { type LocalesValues } from "intlayer";
   import { LocaleSwitcher } from "./LocaleSwitcher";
   
   function App() {
     const { title } = useIntlayer("app");
   
     return (
       <div>
         <h1>{title}</h1>
         <LocaleSwitcher />
       </div>
     );
   }
   
   export function ReactIsland({ locale }: { locale: LocalesValues }) {
     return (
       <IntlayerProvider locale={locale}>
         <App />
       </IntlayerProvider>
     );
   }
   

   locale プロップはAstroページ（サーバー検出）から IntlayerProvider に渡され、ツリー内のすべてのReactフックの初期ロケールとなります。

7. 7

   言語切り替え機能の追加

   利用可能なロケールを読み取り、ユーザーが新しい言語を選択したときにローカライズされたURLに移動するReactコンポーネント LocaleSwitcher を作成します：

   src/components/react/LocaleSwitcher.tsx

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   /** @jsxImportSource react */
   import { useLocale } from "react-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   export function LocaleSwitcher() {
     const { locale, availableLocales, setLocale } = useLocale({
       onLocaleChange: (newLocale: LocalesValues) => {
         // 言語変更時にローカライズされたURLに移動
         window.location.href = getLocalizedUrl(
           window.location.pathname,
           newLocale
         );
       },
     });
   
     return (
       <div className="locale-switcher">
         <span className="switcher-label">言語を切り替える:</span>
         <div className="locale-buttons">
           {availableLocales.map((localeItem) => (
             <button
               key={localeItem}
               onClick={() => setLocale(localeItem)}
               className={`locale-btn ${localeItem === locale ? "active" : ""}`}
               disabled={localeItem === locale}
             >
               <span className="ls-own-name">{getLocaleName(localeItem)}</span>
               <span className="ls-current-name">
                 {getLocaleName(localeItem, locale)}
               </span>
               <span class="ls-code">{localeItem.toUpperCase()}</span>
             </button>
           ))}
         </div>
       </div>
     );
   }
   

   固定の維持に関する注意: window.location.href を介したリダイレクトのために onLocaleChange を使用することで、新しい言語のURLが確実に訪問され、Intlayerミドルウェアが言語クッキーを設定して、将来の訪問時にユーザーの好みが記憶されるようになります。

   LocaleSwitcher は IntlayerProvider 内でレンダリングされる必要があります。アイランドコンポーネント内で使用してください（ステップ6参照）。

8. 8

   サイトマップとRobots.txt

   Intlayerは、動的にローカライズされたサイトマップとrobots.txtファイルを生成するためのユーティリティを提供します。

   サイトマップ

   Intlayer には、アプリケーションのサイトマップを簡単に作成できるサイトマップ ジェネレーターが組み込まれています。ローカライズされたルートを処理し、検索エンジンに必要なメタデータを追加します。

   Intlayer によって生成されたサイトマップは、xhtml:link 名前空間 (Hreflang XML Extensions) をサポートしています。生の URL のみを表示するデフォルトのサイトマップ ジェネレーターとは異なり、Intlayer はページのすべての言語バージョン (例: /about、/about?lang=fr、/about?lang=es) 間に必要な双方向リンクを自動的に作成します。これにより、検索エンジンが正しい言語バージョンを正しい対象者に正しくインデックス付けして提供できるようになります。

   すべてのローカライズされたルートを含むサイトマップを生成するために、src/pages/sitemap.xml.ts を作成します。

   src/pages/sitemap.xml.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import type { APIRoute } from "astro";
   import { generateSitemap, type SitemapUrlEntry } from "intlayer";
   
   const pathList: SitemapUrlEntry[] = [
     { path: "/", changefreq: "daily", priority: 1.0 },
     { path: "/about", changefreq: "monthly", priority: 0.7 },
   ];
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, {
       siteUrl: "https://example.com",
     });
   
     return new Response(xmlOutput, {
       headers: { "Content-Type": "application/xml" },
     });
   };
   

   Robots.txt

   検索エンジンのクロールを制御するために src/pages/robots.txt.ts を作成します。

   src/pages/robots.txt.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import type { APIRoute } from "astro";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
   
   export const GET: APIRoute = ({ site }) => {
     const robotsTxt = [
       "User-agent: *",
       "Allow: /",
       ...disallowedPaths.map((path) => `Disallow: ${path}`),
       "",
       `Sitemap: ${new URL("/sitemap.xml", site).href}`,
     ].join("\n");
   
     return new Response(robotsTxt, {
       headers: { "Content-Type": "text/plain" },
     });
   };
   

9. 15

   Extract the content of your components

   オプション

   If you have an existing codebase, transforming thousands of files can be time-consuming.

   To ease this process, Intlayer propose a compiler / extractor to transform your components and extract the content.

   compiler

   extractor

   To set it up, you can add a compiler section in your intlayer.config.ts file:

   intlayer.config.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     // ... Rest of your config
     compiler: {
       /**
        * Indicates if the compiler should be enabled.
        */
       enabled: true,
   
       /**
        * Defines the output files path
        */
       output: ({ fileName, extension }) => `./${fileName}${extension}`,
   
       /**
        * Indicates if the components should be saved after being transformed.
        *
        * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.
        *
        * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.
        */
       saveComponents: false,
   
       /**
        * Dictionary key prefix
        */
       dictionaryKeyPrefix: "",
     },
   };
   
   export default config;
   

   Extract commandBabel compiler

   Run the extractor to transform your components and extract the content

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   npx intlayer extract
   

   アプリケーションをビルドしてコンポーネントを変換し、コンテンツを抽出します。

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   npm run build # Or npm run dev
   

TypeScriptの設定

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

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

{
  // ... 既存のTypeScript設定
  include: [
    // ... 既存のTypeScript設定
    ".intlayer/**/*.ts", // 自動生成された型を含める
  ],
}

Gitの設定

Intlayerによって生成されたファイルを無視することをお勧めします。これにより、それらをGitリポジトリにコミットすることを避けることができます。

そのためには、.gitignoreファイルに以下の指示を追加してください：

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

VS Code拡張機能

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

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

• 翻訳キーのオートコンプリート。
• 欠落している翻訳のリアルタイムエラー検出。
• 翻訳されたコンテンツのインラインプレビュー。
• 翻訳を簡単に作成・更新するためのクイックアクション。

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

さらに詳しく

さらに詳しく知りたい場合は、ビジュアルエディターを実装したり、CMSを使用してコンテンツを外部化したりすることもできます。

よくある質問