Intlayerの今後のリリースに関する通知を受け取る
    作成:2024-03-07最終更新:2024-03-07

    ViteとReactアプリケーションでIntlayerをセットアップするステップバイステップガイド

    ステップ1: 依存関係のインストール

    npmを使って必要なパッケージをインストールします:

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

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

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

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

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

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

    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: Vite設定にIntlayerを統合する

    設定にintlayerプラグインを追加します。

    vite.config.ts
    import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayerPlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayerPlugin()],});

    intlayerPlugin() Viteプラグインは、IntlayerをViteと統合するために使用されます。これにより、コンテンツ宣言ファイルのビルドが保証され、開発モードで監視されます。また、Viteアプリケーション内でIntlayerの環境変数を定義します。さらに、パフォーマンスを最適化するためのエイリアスも提供します。

    ステップ4: コンテンツを宣言する

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

    src/app.content.tsx
    import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = {  key: "app",  content: {    viteLogo: t({      en: "Vite logo",      fr: "Logo Vite",      es: "Logo Vite",    }),    reactLogo: t({      en: "React logo",      fr: "Logo React",      es: "Logo React",    }),    title: "Vite + React",    count: t({      en: "count is ",      fr: "le compte est ",      es: "el recuento es ",    }),    edit: t<ReactNode>({      en: (        <>          <code>src/App.tsx</code> を編集して保存し、HMRをテストします        </>      ),      fr: (        <>          <code>src/App.tsx</code> を編集して保存し、HMRをテストします        </>      ),      es: (        <>          <code>src/App.tsx</code> を編集して保存し、HMRをテストします        </>      ),    }),    readTheDocs: t({      en: "Click on the Vite and React logos to learn more",      fr: "Cliquez sur les logos Vite et React pour en savoir plus",      es: "Haga clic en los logotipos de Vite y React para obtener más información",    }),  },} satisfies Dictionary;export default appContent;

    あなたのコンテンツ宣言は、contentDirディレクトリ(デフォルトは./src)に含まれた時点で、アプリケーションのどこにでも定義できます。そして、コンテンツ宣言ファイルの拡張子(デフォルトは.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx})に一致する必要があります。

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

    コンテンツファイルにTSXコードが含まれている場合は、import React from "react";をコンテンツファイルにインポートすることを検討してください。

    ステップ5: コード内でIntlayerを利用する

    アプリケーション全体でコンテンツ辞書にアクセスします:

    src/App.tsx
    import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => {  const [count, setCount] = useState(0);  const content = useIntlayer("app");  return (    <>      <div>        <a href="https://vitejs.dev" target="_blank">          <img src={viteLogo} className="logo" alt={content.viteLogo.value} />        </a>        <a href="https://react.dev" target="_blank">          <img            src={reactLogo}            className="logo react"            alt={content.reactLogo.value}          />        </a>      </div>      <h1>{content.title}</h1>      <div className="card">        <button onClick={() => setCount((count) => count + 1)}>          {content.count}          {count}        </button>        <p>{content.edit}</p>      </div>      <p className="read-the-docs">{content.readTheDocs}</p>    </>  );};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

    もし alttitlehrefaria-label などの string 属性でコンテンツを使用したい場合は、関数の値を呼び出す必要があります。例えば:

    jsx
    <img src={content.image.src.value} alt={content.image.value} />

    useIntlayer フックの詳細については、ドキュメントを参照してください。

    (オプション)ステップ6: コンテンツの言語を変更する

    コンテンツの言語を変更するには、useLocale フックが提供する setLocale 関数を使用します。この関数を使うことで、アプリケーションのロケールを設定し、それに応じてコンテンツを更新できます。

    src/components/LocaleSwitcher.tsx
    import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>英語に言語を変更</button>  );};

    useLocale フックの詳細については、ドキュメントを参照してください。

    (オプション)ステップ7:アプリケーションにローカライズされたルーティングを追加する

    このステップの目的は、各言語ごとにユニークなルートを作成することです。これはSEOやSEOに適したURLに役立ちます。 例:

    plaintext
    - https://example.com/about- https://example.com/es/about- https://example.com/fr/about

    デフォルトでは、ルートはデフォルトロケールに対してプレフィックスが付きません。デフォルトロケールにもプレフィックスを付けたい場合は、設定の middleware.prefixDefault オプションを true に設定できます。詳細は設定ドキュメントを参照してください。

    アプリケーションにローカライズされたルーティングを追加するには、アプリケーションのルートをラップし、ロケールベースのルーティングを処理する LocaleRouter コンポーネントを作成できます。以下は React Router を使用した例です。

    src/components/LocaleRouter.tsx
    // 必要な依存関係と関数のインポートimport { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // 'intlayer'からのユーティリティ関数と型import type { FC, PropsWithChildren } from "react"; // 関数コンポーネントとプロパティのReact型import { IntlayerProvider } from "react-intlayer"; // 国際化コンテキストのプロバイダーimport {  BrowserRouter,  Routes,  Route,  Navigate,  useLocation,} from "react-router-dom"; // ナビゲーション管理用のルーターコンポーネント// Intlayerから設定を分割代入const { internationalization, middleware } = configuration;const { locales, defaultLocale } = internationalization;/** * ローカリゼーションを処理し、子要素を適切なロケールコンテキストでラップするコンポーネント。 * URLベースのロケール検出と検証を管理します。 */const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({  children,  locale,}) => {  const { pathname, search } = useLocation(); // 現在のURLパスを取得  // 現在のロケールを決定し、指定がなければデフォルトロケールを使用  const currentLocale = locale ?? defaultLocale;  // パスからロケールのプレフィックスを取り除き、ベースパスを構築  const pathWithoutLocale = getPathWithoutLocale(    pathname // 現在のURLパス  );  /**   * middleware.prefixDefaultがtrueの場合、デフォルトロケールには常にプレフィックスを付ける必要があります。   */  if (middleware.prefixDefault) {    // ロケールの検証    if (!locale || !locales.includes(locale)) {      // 更新されたパスでデフォルトロケールへリダイレクト      return (        <Navigate          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}          replace // 現在の履歴エントリを新しいものに置き換える        />      );    }    // IntlayerProviderで子要素をラップし、現在のロケールを設定する    return (      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>    );  } else {    /**     * middleware.prefixDefaultがfalseの場合、デフォルトロケールはプレフィックスされません。     * 現在のロケールが有効であり、デフォルトロケールでないことを確認します。     */    if (      currentLocale.toString() !== defaultLocale.toString() &&      !locales        .filter(          (locale) => locale.toString() !== defaultLocale.toString() // デフォルトロケールを除外        )        .includes(currentLocale) // 現在のロケールが有効なロケールのリストに含まれているかをチェック    ) {      // ロケールのプレフィックスなしのパスへリダイレクト      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;    }    // IntlayerProviderで子要素をラップし、現在のロケールを設定    return (      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>    );  }};/** * ロケール固有のルートを設定するルーターコンポーネント。 * React Routerを使用してナビゲーションを管理し、ローカライズされたコンポーネントをレンダリングします。 */export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (  <BrowserRouter>    <Routes>      {locales        .filter(          (locale) => middleware.prefixDefault || locale !== defaultLocale        )        .map((locale) => (          <Route            // ロケールをキャプチャするルートパターン(例: /en/, /fr/)およびそれに続くすべてのパスにマッチ            path={`/${locale}/*`}            key={locale}            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // ロケール管理で子要素をラップ          />        ))}      {        // デフォルトロケールのプレフィックスが無効の場合、ルートパスで直接子要素をレンダリング        !middleware.prefixDefault && (          <Route            path="*"            element={              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>            } // ロケール管理で子要素をラップ          />        )      }    </Routes>  </BrowserRouter>);

    次に、アプリケーションで LocaleRouter コンポーネントを使用できます:

    src/App.tsx
    import { LocaleRouter } from "./components/LocaleRouter";import type { FC } from "react";// ... あなたの AppContent コンポーネントconst App: FC = () => (  <LocaleRouter>    <AppContent />  </LocaleRouter>);

    並行して、intLayerMiddlewarePlugin を使用してアプリケーションにサーバーサイドルーティングを追加することもできます。このプラグインは、URL に基づいて現在のロケールを自動的に検出し、適切なロケールクッキーを設定します。ロケールが指定されていない場合、プラグインはユーザーのブラウザの言語設定に基づいて最も適切なロケールを判断します。ロケールが検出されない場合は、デフォルトのロケールにリダイレクトします。

    vite.config.ts
    import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayerPlugin(), intLayerMiddlewarePlugin()],});

    (オプション)ステップ8:ロケールが変更されたときにURLを変更する

    ロケールが変更されたときにURLを変更するには、useLocaleフックが提供するonLocaleChangeプロパティを使用できます。同時に、react-router-domuseLocationuseNavigateフックを使用してURLパスを更新できます。

    src/components/LocaleSwitcher.tsx
    import { useLocation, useNavigate } from "react-router-dom";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "react-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => {  const { pathname, search } = useLocation(); // 現在のURLパスを取得。例: /fr/about?foo=bar  const navigate = useNavigate();  const { locale, availableLocales, setLocale } = useLocale({    onLocaleChange: (locale) => {      // 更新されたロケールでURLを構築する      // 例: /es/about?foo=bar      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);      // URLパスを更新する      navigate(pathWithLocale);    },  });  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <a            href={getLocalizedUrl(location.pathname, localeItem)}            hrefLang={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={(e) => {              e.preventDefault();              setLocale(localeItem);            }}            key={localeItem}          >            <span>              {/* ロケール - 例: FR */}              {localeItem}            </span>            <span>              {/* 自身のロケールでの言語名 - 例: Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* 現在のロケールでの言語名 - 例: Francés(現在のロケールがLocales.SPANISHの場合) */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* 英語での言語名 - 例: French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </a>        ))}      </div>    </div>  );};

    ドキュメント参照:

    以下は、説明を追加しコード例を洗練させた更新版のステップ9です。


    (オプション)ステップ9: HTMLの言語属性と方向属性を切り替える

    アプリケーションが複数の言語をサポートしている場合、<html>タグのlang属性とdir属性を現在のロケールに合わせて更新することが非常に重要です。これにより、以下が保証されます:

    • アクセシビリティ:スクリーンリーダーや支援技術は、正しいlang属性に依存してコンテンツを正確に発音・解釈します。
    • テキストのレンダリングdir(方向)属性は、テキストが適切な順序(例:英語は左から右、アラビア語やヘブライ語は右から左)で表示されることを保証し、読みやすさに不可欠です。
    • SEO:検索エンジンはlang属性を使用してページの言語を判別し、適切なローカライズされたコンテンツを検索結果に提供します。

    ロケールが変更されるたびにこれらの属性を動的に更新することで、すべての対応言語において一貫性がありアクセシブルなユーザー体験を保証します。

    フックの実装

    HTML属性を管理するカスタムフックを作成します。このフックはロケールの変更を監視し、それに応じて属性を更新します。

    src/hooks/useI18nHTMLAttributes.tsx
    import { useEffect } from "react";import { useLocale } from "react-intlayer";import { getHTMLTextDir } from "intlayer";/** * 現在のロケールに基づいてHTMLの<html>要素の`lang`および`dir`属性を更新します。 * - `lang`: ブラウザや検索エンジンにページの言語を通知します。 * - `dir`: 正しい読み順を保証します(例:英語は'ltr'、アラビア語は'rtl')。 * * この動的な更新は、適切なテキストレンダリング、アクセシビリティ、およびSEOに不可欠です。 */export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    // 現在のロケールに言語属性を更新します。    document.documentElement.lang = locale;    // 現在のロケールに基づいてテキストの方向を設定します。    document.documentElement.dir = getHTMLTextDir(locale);  }, [locale]);};

    アプリケーションでのフックの使用方法

    ロケールが変更されるたびにHTML属性が更新されるように、メインコンポーネントにフックを統合します:

    src/App.tsx
    import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";import "./App.css";const AppContent: FC = () => {  // ロケールに基づいて<html>タグのlangとdir属性を更新するためにフックを適用します。  useI18nHTMLAttributes();  // ... コンポーネントの残りの部分};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

    アプリケーションでのフックの使用

    フックをメインコンポーネントに統合し、ロケールが変更されるたびにHTML属性が更新されるようにします:

    src/App.tsx
    import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";import "./App.css";const AppContent: FC = () => {  // ロケールに基づいて<html>タグのlangとdir属性を更新するためにフックを適用します。  useI18nHTMLAttributes();  // ... コンポーネントの残りの部分};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

    これらの変更を適用することで、アプリケーションは以下を実現します:

    • 現在のロケールを正確に反映する言語lang)属性を確実に設定し、SEOやブラウザの動作に重要な役割を果たします。
    • ロケールに応じてテキストの方向dir)を調整し、異なる読み順の言語に対して読みやすさと使いやすさを向上させます。
    • これらの属性に依存する支援技術のために、よりアクセシブルな体験を提供します。

    (オプション)ステップ10:ローカライズされたリンクコンポーネントの作成

    これらの変更を適用することで、アプリケーションは以下を実現します:

    • 言語lang)属性が現在のロケールを正確に反映し、SEOやブラウザの動作に重要な役割を果たします。
    • ロケールに応じてテキストの方向dir)を調整し、異なる読み方向の言語に対して読みやすさと使いやすさを向上させます。
    • 支援技術がこれらの属性に依存して最適に機能するため、よりアクセシブルな体験を提供します。

    (オプション)ステップ10:ローカライズされたリンクコンポーネントの作成

    アプリケーションのナビゲーションが現在のロケールを尊重するようにするために、カスタムの Link コンポーネントを作成できます。このコンポーネントは内部のURLに自動的に現在の言語をプレフィックスとして付加します。例えば、フランス語を話すユーザーが「About」ページへのリンクをクリックすると、/about ではなく /fr/about にリダイレクトされます。

    この動作は以下の理由で有用です:

    • SEOとユーザー体験:ローカライズされたURLは、検索エンジンが言語別のページを正しくインデックスし、ユーザーに好みの言語でコンテンツを提供するのに役立ちます。
    • 一貫性:アプリケーション全体でローカライズされたリンクを使用することで、ナビゲーションが現在のロケール内に留まり、予期しない言語の切り替えを防ぎます。
    • 保守性: ローカリゼーションのロジックを単一のコンポーネントに集約することで、URLの管理が簡素化され、アプリケーションの成長に伴いコードベースの保守や拡張が容易になります。

    以下は、TypeScriptで実装されたローカライズされた Link コンポーネントの例です。

    src/components/Link.tsx
    import { getLocalizedUrl } from "intlayer";import {  forwardRef,  type DetailedHTMLProps,  type AnchorHTMLAttributes,} from "react";import { useLocale } from "react-intlayer";export interface LinkProps  extends DetailedHTMLProps<    AnchorHTMLAttributes<HTMLAnchorElement>,    HTMLAnchorElement  > {}/** * 指定されたURLが外部リンクかどうかを判定するユーティリティ関数。 * URLが http:// または https:// で始まる場合、外部リンクとみなされます。 */export const checkIsExternalLink = (href?: string): boolean =>  /^https?:\/\//.test(href ?? "");/** * 現在のロケールに基づいてhref属性を適応するカスタムLinkコンポーネント。 * 内部リンクの場合、`getLocalizedUrl`を使用してURLの先頭にロケールを付加します(例:/fr/about)。 * これにより、ナビゲーションが同じロケールコンテキスト内に留まることを保証します。 */export const Link = forwardRef<HTMLAnchorElement, LinkProps>(  ({ href, children, ...props }, ref) => {    const { locale } = useLocale();    const isExternalLink = checkIsExternalLink(href);    // リンクが内部リンクで有効なhrefが提供されている場合、ローカライズされたURLを取得します。    const hrefI18n =      href && !isExternalLink ? getLocalizedUrl(href, locale) : href;    return (      <a href={hrefI18n} ref={ref} {...props}>        {children}      </a>    );  });Link.displayName = "Link";

    動作の仕組み

    • 外部リンクの検出:
      ヘルパー関数 checkIsExternalLink は、URLが外部リンクかどうかを判定します。外部リンクはローカライズの必要がないため、そのままにされます。

    • 現在のロケールの取得:
      useLocale フックは現在のロケール(例:フランス語の場合は fr)を提供します。

    • URLのローカライズ:
      内部リンク(すなわち外部リンクでない場合)には、getLocalizedUrl が使用され、URLの先頭に現在のロケールを自動的に付加します。例えば、ユーザーがフランス語環境にいる場合、href/about を渡すと /fr/about に変換されます。

    • リンクの返却:
      コンポーネントはローカライズされたURLを持つ <a> 要素を返し、ナビゲーションがロケールに一貫して対応するようにします。

    この Link コンポーネントをアプリケーション全体に統合することで、一貫性のある言語対応のユーザー体験を維持しつつ、SEOや使いやすさの向上も実現できます。

    TypeScript の設定

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

    alt text

    alt text

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

    コンポーネントはローカライズされたURLを持つ<a>要素を返し、ナビゲーションがロケールに沿って一貫して行われることを保証します。

    このLinkコンポーネントをアプリケーション全体に統合することで、一貫性のある言語対応のユーザー体験を維持しつつ、SEOや使いやすさの向上も期待できます。

    TypeScriptの設定

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

    alt text

    alt text

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

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

    Gitの設定

    Intlayerによって生成されたファイルはGitリポジトリにコミットしないように無視することを推奨します。

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

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

    VS Code拡張機能

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

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

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

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

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


    さらに進むために

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


    ドキュメント履歴

    • 5.5.10 - 2025-06-29: 履歴の初期化
    Intlayerの今後のリリースに関する通知を受け取る