프로바이더와 훅

로캘과 카탈로그를 제공하고, 공통 메시지와 페이지 메시지를 결합하고, 렌더링 입력이 뒤섞이지 않게 언어를 전환하세요.

LingoProvider는 컴포넌트 하위 트리에 하나의 로캘과 카탈로그를 제공합니다. useLingo()는 가장 가까운 프로바이더를 읽어 해당 입력에 맞는 메시지 및 서식 지정 메서드를 반환합니다.

이 렌더링 예제를 실행하려면 리액트 19가 필요합니다. 프로바이더를 사용하기 전에 리액트 빠른 시작의 설치 안내를 따르세요.

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

function SaveButton() {
  const l = useLingo();
  return (
    <button type="submit">
      {l.text("Save", { context: "Submit changes to account settings" })}
    </button>
  );
}

export function Settings({ messages }: { messages: Messages }) {
  return (
    <LingoProvider locale="fr" messages={messages}>
      <SaveButton />
    </LingoProvider>
  );
}

Settings를 렌더링하기 전에 프랑스어 메시지를 불러오세요. 프로바이더는 파일 경로, 프로미스, 파싱된 JSONC 항목 목록이 아니라 Record<string, string> 형태의 Messages를 받습니다. 이 맵은 카탈로그 불러오기 과정에서 생성됩니다.

프로바이더 입력 #

속성규약
locale메시지 조회 진단, 문법, 서식 지정에 쓰이는 필수 문자열입니다.
messages해시를 키로 사용하는 선택 사항인 문자열 맵입니다. 기본값은 {}입니다.
children필수 ReactNode 하위 트리입니다.

카탈로그가 비어 있어도 하위 트리에서는 로캘에 맞는 서식 지정을 사용할 수 있으며, 메시지 호출 시에는 원문 템플릿이 사용됩니다. 프로바이더 자체는 문서의 언어나 텍스트 방향을 설정하지 않습니다.

프로바이더 하위의 컴포넌트에서 useLingo를 호출하세요. 프로바이더 밖에서 호출하면 예외가 발생합니다. 같은 컴포넌트에서 프로바이더를 반환하더라도 해당 컴포넌트의 훅이 그 프로바이더 하위에 놓이지는 않습니다. 따라서 프로바이더 래퍼와 훅을 읽는 컴포넌트를 분리하세요.

공통 메시지와 페이지 메시지 결합 #

로캘 문자열이 같은 중첩 프로바이더는 각자의 맵을 병합합니다. 자식 항목은 키가 일치하는 부모 항목을 덮어쓰고, 나머지 부모 항목은 그대로 사용할 수 있습니다. 따라서 라우트에서 공통 탐색 메시지를 중복으로 정의하지 않고도 페이지 메시지를 추가할 수 있습니다.

tsx
<LingoProvider locale="fr" messages={sharedMessages}>
  <LingoProvider locale="fr" messages={pageMessages}>
    <SettingsPage />
  </LingoProvider>
</LingoProvider>

여기서 sharedMessages와 pageMessages는 이미 불러온 프랑스어 맵입니다. 내부 로캘을 es로 바꾸면 내부 프로바이더는 독립적으로 동작합니다. 스페인어 메시지가 없으면 프랑스어 텍스트를 가져오는 대신 원문을 대체 값으로 사용합니다. 로캘 문자열을 있는 그대로 비교하므로 애플리케이션 전체에서 로캘 표기를 일관되게 유지하세요.

로캘과 카탈로그를 함께 전환 #

렌더링 입력은 { locale: "fr", messages: frenchMessages }처럼 한 쌍으로 저장하세요. 다음 맵을 불러온 뒤 한 번의 상태 업데이트로 이 쌍을 교체하세요. 로캘만 바꾸면 텍스트는 프랑스어로 표시되는데 숫자에는 스페인어 서식이 적용될 수 있습니다.

다음 카탈로그를 불러오는 동안에는 애플리케이션의 상호작용 설계에 따라 이전 쌍을 계속 표시하거나 로딩 상태를 보여 주세요. 라우팅을 사용하는 애플리케이션에서는 해당하는 넥스트 페이지 또는 탠스택 구현 예제를 따르세요. 각 예제의 전환기는 새 입력을 서로 다른 방식으로 불러옵니다.

훅 없이 링고 객체 만들기 #

리액트 컴포넌트 밖의 함수에서 문자열이 필요하다면 createLingo(locale: string, messages?: Messages): Lingo를 사용하세요.

ts
import { createLingo } from "@lingo.dev/react";

const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });

이 코드는 Account settings를 반환하고, 해당 로캘에 맞춰 비율을 12.5% 형식으로 표시합니다. 번역 요청을 보내거나 프로바이더를 구독하지 않습니다. 로캘이나 메시지가 바뀌면 새 객체를 만드세요.

createLingo와 useLingo는 모두 locale, direction, script, region를 제공합니다. 로캘 메타데이터를 사용해 문서 속성을 적용하고, 하이드레이션 중에는 동일한 입력을 유지하세요.