TanStack Start v1에서 문서 언어를 설정하는 방법

문제

웹 페이지는 다양한 사용자 에이전트에서 올바르게 작동하기 위해 기본 언어를 선언해야 합니다. 루트 HTML 요소에 명시적인 언어 선언이 없으면 브라우저는 콘텐츠의 언어를 판단할 수 없어 추측해야 합니다. 이로 인해 스크린 리더는 사용자의 시스템 언어를 기본값으로 사용하게 되며, 콘텐츠 언어가 다를 경우 잘못된 발음이 발생합니다. 브라우저는 소스 언어 정보가 없어 정확한 번역 기능을 제공할 수 없습니다. 검색 엔진은 적절한 언어 대상을 위해 콘텐츠를 확실하게 색인할 수 없어, 해당 언어로 검색하는 사용자의 검색 가능성이 감소합니다.

해결 방법

페이지의 기본 언어를 설정하려면 html 태그에 lang 속성을 추가하세요. TanStack Start에서 HTML 셸은 루트 라우트의 shellComponent에 정의되어 있으며, 이는 <html> 요소를 포함한 문서 구조를 렌더링합니다. 이 요소에 적절한 언어 코드와 함께 lang 속성을 추가하면 브라우저, 보조 기술 및 검색 엔진에 콘텐츠의 언어를 알려 올바르게 처리하고 표시할 수 있도록 합니다.

단계

1. 현재 로케일 식별

루트 라우트의 shellComponent 속성은 모든 라우트 콘텐츠를 감싸는 HTML 셸을 정의하며 항상 서버 측에서 렌더링됩니다. 라우트 매개변수, 쿠키 또는 헤더와 같은 애플리케이션의 로케일 감지 메커니즘에서 현재 로케일을 확인하세요.

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 속성 추가

로케일 값을 사용하여 <html> 요소에 lang 속성을 설정하세요. 콘텐츠의 언어와 일치하는 유효한 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 속성이 항상 현재 콘텐츠 언어를 반영하도록 합니다.