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 속성은 현재 로케일을 반영하며, 사용자가 언어별 경로 간에 이동할 때 자동으로 업데이트됩니다.