로캘과 텍스트 방향

런타임의 로캘 메타데이터로 문서와 현지화된 하위 트리의 언어 및 방향을 설정하세요.

번역된 텍스트와 문서의 방향은 일치해야 합니다. 아랍어 카탈로그를 제공하면 메시지는 바뀌지만, 브라우저가 의도한 읽기 방향에 맞게 페이지를 배치하려면 dir="rtl"도 필요합니다. 프로바이더와 문서 속성에 모두 최종 결정된 로캘을 사용하세요.

언어와 방향을 함께 설정하기 #

프레임워크의 문서 또는 셸 컴포넌트에서 해당 요청에 선택된 로캘을 바탕으로 속성을 설정하세요:

tsx
import type { ReactNode } from "react";
import { createLingo, LingoProvider, type Messages } from "@lingo.dev/react";

export function LocalizedDocument({ locale, messages, children }: {
  locale: string;
  messages: Messages;
  children: ReactNode;
}) {
  const l = createLingo(locale);
  return (
    <html lang={l.locale} dir={l.direction}>
      <body>
        <LingoProvider locale={locale} messages={messages}>
          {children}
        </LingoProvider>
      </body>
    </html>
  );
}

이 패턴을 적용할 때도 프레임워크에 필요한 헤드, 스크립트, 하이드레이션 컴포넌트는 그대로 유지하세요. 다른 언어로 된 페이지 안에 현지화된 하위 트리가 있다면, 해당 하위 트리의 useLingo() 결과를 사용해 이를 감싸는 요소에 lang과 dir를 설정하세요. 특정 구역의 속성이 문서 전체의 언어를 대체하지는 않습니다.

가능하면 초기 HTML에 속성을 적용하세요. 하이드레이션 이후에 방향을 업데이트하면 페이지가 처음에는 잘못된 레이아웃으로 표시될 수 있습니다.

메타데이터를 정확히 이해하기 #

멤버의미
locale: string입력된 로캘을 그대로 유지한 값입니다.
direction: "ltr" | "rtl"사용 가능한 경우 네이티브 Intl.Locale.textInfo 방향이며, 그렇지 않으면 런타임이 언어를 기준으로 정하는 대체 방향입니다.
script: string | undefinedIntl.Locale로 로캘을 최대화해 추정한 문자 체계입니다.
region: string | undefined같은 최대화 과정에서 추정한 지역입니다.

예를 들어 createLingo("en")는 Latn와 US를 추론할 수 있습니다. 이는 로캘 하위 태그를 가능성이 높은 값으로 채울 뿐, 사용자의 위치를 파악하거나 청구 국가를 확정하지는 않습니다. 애플리케이션에 이런 정보가 필요하다면 실제 계정 또는 위치 데이터를 사용하세요.

Intl.Locale를 사용할 수 없거나 태그가 유효하지 않으면 문자 체계와 지역이 정의되지 않을 수 있으며, 방향은 대체 언어 목록을 기준으로 정해집니다. 다른 네이티브 포맷터는 여전히 유효하지 않은 태그를 거부할 수 있습니다. 렌더링 전에 애플리케이션이 지원하는 로캘 집합을 기준으로 로캘을 결정하세요.

읽기 방향에 맞춰 레이아웃 구성하기 #

텍스트 방향에 맞게 간격이 조정되도록 margin-inline-start과 padding-inline-end 같은 논리적 CSS 속성을 사용하세요. 아이콘은 하나씩 확인하세요. 탐색 화살표는 방향을 뒤집어야 할 수 있지만, 실제 사물을 나타내는 이미지는 그럴 필요가 없을 수 있습니다. 로캘 메타데이터는 방향을 제공하고, 컴포넌트 설계는 그 방향을 인터페이스에 어떻게 반영할지 결정합니다.

프로바이더는 언어를 협상하거나 메시지를 가져오지 않습니다. 로캘 라우터는 URL과 환경설정에 관한 정책을 제공합니다. 넥스트 페이지 래퍼는 방향을 동기화하지만 문서의 lang 설정은 애플리케이션에 맡깁니다. 탠스택 셸은 요청 컨텍스트를 바탕으로 두 가지를 모두 설정합니다.

언어를 전환한 후에는 문서 속성과 로드된 카탈로그를 함께 확인하세요. 서버 렌더링에서는 동일한 로캘, 메시지, 서식 지정 입력값이 하이드레이션에도 전달되어야 하는 이유를 설명합니다.