TanStack Start v1でドキュメント言語を設定する方法

問題

Webページは、異なるユーザーエージェント間で正しく機能するために、主要言語を宣言する必要があります。ルートHTML要素に明示的な言語宣言がない場合、ブラウザはコンテンツの言語を判断できず、推測する必要があります。これにより、スクリーンリーダーはユーザーのシステム言語にデフォルト設定され、コンテンツ言語が異なる場合に誤った発音が生じます。ブラウザは、ソース言語情報がないため、正確な翻訳機能を提供できません。検索エンジンは、適切な言語オーディエンス向けにコンテンツを確実にインデックス化することが困難になり、その言語で検索するユーザーの発見可能性が低下します。

解決策

htmlタグにlang属性を追加して、ページのデフォルト言語を設定します。TanStack Startでは、HTMLシェルはルートルートのshellComponentで定義され、<html>要素を含むドキュメント構造をレンダリングします。この要素に適切な言語コードを持つlang属性を追加することで、ブラウザ、支援技術、検索エンジンにコンテンツの言語を通知し、正しく処理および表示できるようにします。

手順

1. 現在のロケールを特定する

ルートルートのshellComponentプロパティは、すべてのルートコンテンツをラップするHTMLシェルを定義し、常にサーバーサイドでレンダリングされます。ルートパラメータ、Cookie、ヘッダーなど、アプリケーションのロケール検出メカニズムから現在のロケールを決定します。

import type { ReactNode } from "react";
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";

export const Route = createRootRoute({
  shellComponent: RootDocument,
  component: RootComponent,
});

function RootComponent() {
  return <Outlet />;
}

function RootDocument({ children }: { children: ReactNode }) {
  const locale = "en";

  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

これにより、言語属性を追加するシェル構造が確立されます。

2. html要素にlang属性を追加する

lang要素の<html>属性をロケール値を使用して設定します。コンテンツの言語に一致する有効なBCP 47言語タグを使用してください。

function RootDocument({ children }: { children: ReactNode }) {
  const locale = "en";

  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

lang属性がドキュメントの言語を宣言することで、ブラウザと支援技術がコンテンツを適切に処理できるようになります。

3. 動的なロケール値を使用する

アプリケーションが複数のロケールをサポートしている場合は、ルーティングまたは状態管理システムから現在のロケールを取得し、シェルコンポーネントに渡します。

function RootDocument({ children }: { children: ReactNode }) {
  const locale = getCurrentLocale();

  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

function getCurrentLocale(): string {
  return "en";
}

ドキュメントの言語がアクティブなロケールに基づいて更新されるようになり、lang属性が常に現在のコンテンツの言語を反映するようになります。