React Router v7에서 문서 언어를 설정하는 방법

문제

웹 페이지는 브라우저와 보조 기술에 기본 언어를 선언해야 합니다. 명시적인 언어 선언이 없으면 스크린 리더는 사용자의 시스템 언어를 기본값으로 사용하며, 콘텐츠 언어가 다를 경우 잘못된 발음이 생성될 수 있습니다. 브라우저는 소스 언어를 추측해야 하므로 정확한 번역 기능을 제공할 수 없습니다. 검색 엔진은 올바른 언어 대상에 대해 페이지를 확실하게 색인할 수 없어 해당 언어로 검색하는 사용자의 검색 가능성이 감소합니다.

해결 방법

루트 <html> 요소에 lang 속성을 설정하여 문서의 기본 언어를 선언하세요. 이 속성은 브라우저, 스크린 리더 및 검색 엔진에 콘텐츠가 사용하는 언어를 알려주는 유효한 언어 코드를 받습니다. 언어가 명시적으로 선언되면 보조 기술은 올바른 발음 규칙을 적용할 수 있고, 브라우저는 적절한 번역 옵션을 제공할 수 있으며, 검색 엔진은 올바른 언어 대상을 위해 페이지를 색인할 수 있습니다.

단계

1. 현재 로케일 확인

app/root.tsx의 루트 라우트는 루트 HTML 문서를 렌더링하는 역할을 합니다. 애플리케이션이 로케일 기반 라우팅(예: /:locale/... 패턴)을 사용하는 경우 라우트 매개변수에서 로케일을 추출하세요. 그렇지 않으면 기본 로케일을 사용하세요.

import { useParams } from "react-router";

export default function Root() {
  const params = useParams();
  const locale = params.locale || "en";

  return (
    <html lang={locale}>
      <head>
        <meta charSet="utf-8" />
      </head>
      <body>
        <h1>Content</h1>
      </body>
    </html>
  );
}

이 코드는 URL에서 로케일을 읽고, 로케일 매개변수가 없을 경우 영어로 대체합니다.

2. 로케일 코드를 언어 태그에 매핑

애플리케이션이 표준 언어 태그와 다른 사용자 정의 로케일 식별자를 사용하는 경우, 이를 유효한 BCP 47 언어 코드로 변환하는 매핑 함수를 생성합니다.

function getLanguageTag(locale: string): string {
  const languageMap: Record<string, string> = {
    en: "en",
    "en-US": "en-US",
    es: "es",
    fr: "fr",
    de: "de",
    ja: "ja",
    "zh-CN": "zh-Hans",
    "zh-TW": "zh-Hant",
  };

  return languageMap[locale] || "en";
}

이렇게 하면 라우팅이 단순화된 로케일 코드를 사용하는 경우에도 lang 속성이 유효한 언어 태그를 받을 수 있습니다.

3. HTML 요소에 언어 태그 적용

루트 컴포넌트의 <html> 요소에서 lang 속성의 값으로 매핑된 언어 태그를 사용하세요.

import { useParams } from "react-router";

function getLanguageTag(locale: string): string {
  const languageMap: Record<string, string> = {
    en: "en",
    es: "es",
    fr: "fr",
    de: "de",
  };
  return languageMap[locale] || "en";
}

export default function Root() {
  const params = useParams();
  const locale = params.locale || "en";
  const lang = getLanguageTag(locale);

  return (
    <html lang={lang}>
      <head>
        <meta charSet="utf-8" />
      </head>
      <body>
        <h1>Content</h1>
      </body>
    </html>
  );
}

lang 속성은 이제 현재 로케일을 반영하며, 사용자가 언어별 라우트 간을 탐색할 때 자동으로 업데이트됩니다.