Next.js(Pages Router) v16에서 문서 언어를 설정하는 방법

브라우저와 스크린 리더를 위한 페이지 언어 선언

문제

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

해결 방법

루트 <html> 요소에 lang 속성을 설정하여 페이지의 기본 언어를 선언합니다. Next.js Pages Router에서는 애플리케이션의 HTML 구조를 래핑하는 커스텀 Document 컴포넌트를 생성하여 이를 수행합니다. lang 속성은 브라우저, 보조 기술 및 검색 엔진에 콘텐츠가 사용하는 언어를 알려주는 표준 언어 코드를 허용하여 올바른 발음, 적절한 번역 제안 및 정확한 인덱싱을 가능하게 합니다.

단계

1. 사용자 정의 document 파일 생성

pages 디렉토리에 _document.js(또는 TypeScript의 경우 _document.tsx)라는 파일을 생성합니다. 이 파일을 사용하면 애플리케이션의 모든 페이지를 래핑하는 HTML 문서 구조를 커스터마이징할 수 있습니다.

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

next/document의 Html 컴포넌트는 루트 HTML 요소에 언어 속성을 설정하는 lang prop을 허용합니다. "en"을 콘텐츠의 언어 코드로 교체합니다.

2. 적절한 언어 코드 사용

언어 코드는 UTS Locale Identifiers 표준 형식인 language-region-script를 따르며, 여기서 region과 script는 선택 사항입니다. 대부분의 경우 두 글자 ISO 639-1 언어 코드를 사용합니다.

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="fr">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

일반적인 예로는 영어의 경우 "en", 스페인어의 경우 "es", 프랑스어의 경우 "fr", 독일어의 경우 "de", 일본어의 경우 "ja"가 있습니다. 필요한 경우 "en-US" 또는 "en-GB"와 같은 지역 변형을 포함할 수 있습니다.

3. 로케일에 따라 동적으로 언어 설정

애플리케이션이 Next.js i18n 라우팅을 통해 여러 로케일을 지원하는 경우, 라우터 컨텍스트에서 현재 로케일에 액세스하여 언어를 동적으로 설정합니다.

import Document, {
  Html,
  Head,
  Main,
  NextScript,
  DocumentContext,
  DocumentInitialProps,
} from "next/document";

export default class MyDocument extends Document {
  static async getInitialProps(
    ctx: DocumentContext,
  ): Promise<DocumentInitialProps> {
    const initialProps = await Document.getInitialProps(ctx);
    return initialProps;
  }

  render() {
    return (
      <Html lang={this.props.locale}>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

Next.js의 내장 i18n 구성을 사용하는 경우, 프레임워크가 자동으로 locale을 제공하고 lang 속성을 업데이트합니다. next.config.js에서 i18n이 구성된 경우 Document 컴포넌트에서 locale prop을 사용할 수 있습니다.