LingoProvider

LingoProvider는 현재 활성 로캘과 messages map을 담는 React 컨텍스트입니다. 앱의 루트에서 한 번만 감싸면 내부의 모든 컴포넌트에서 useLingo()를 호출해 문자열을 번역하거나 로캘 메타데이터를 읽을 수 있습니다.

기본 사용법#

import { LingoProvider } from "@lingo.dev/react";
import messages from "./locales/es.json";

<LingoProvider locale="es" messages={messages}>
  <App />
</LingoProvider>

Props#

Messages는 단순히 Record<string, string>이며, CLI가 locales/<locale>.json에 기록하는 것과 동일한 형태입니다.

provider 중첩#

provider는 중첩해서 사용할 수 있습니다. 중첩된 provider가 부모와 같은 로캘을 쓰는지, 아니면 다른 로캘을 쓰는지에 따라 동작 방식이 달라집니다.

같은 로캘 — messages 병합#

<LingoProvider locale="es" messages={sharedMessages}>
  {/* Route-scoped messages override shared on collision; missing keys fall through to shared. */}
  <LingoProvider locale="es" messages={dashboardMessages}>
    <Dashboard />
  </LingoProvider>
</LingoProvider>

루트에는 공통 "shell" 번역 세트를 두고, route별로 번들을 나눠 관리할 때 유용합니다.

다른 로캘 — 독립적으로 동작#

<LingoProvider locale="es" messages={esMessages}>
  <Header />
  <LingoProvider locale="ar-SA" messages={arMessages}>
    {/* This subtree is entirely Arabic; the parent's es messages are NOT visible. */}
    <ArabicEmbed />
  </LingoProvider>
</LingoProvider>

앱 전체 언어와는 별개로 특정 컴포넌트 하나를 고정된 언어로 렌더링할 때 유용합니다(인용문, embed, 미리보기 패널 등).

런타임에 로캘 전환하기#

locale를 React state처럼 다루면 됩니다. 값을 바꾸면 그 아래의 모든 useLingo() consumer가 새 로캘과 message bag으로 다시 렌더링됩니다.

function AppRoot() {
  const [locale, setLocale] = useState("en");
  const [messages, setMessages] = useState({});

  async function switchTo(next: string) {
    const next_messages = await import(`./locales/${next}.json`);
    setLocale(next);
    setMessages(next_messages.default);
  }

  return (
    <LingoProvider locale={locale} messages={messages}>
      <LocaleSwitcher current={locale} onSelect={switchTo} />
      <App />
    </LingoProvider>
  );
}

컨텍스트에서 읽을 수 있는 값#

useLingo()는 현재 활성 Lingo 객체를 반환합니다. text()와 rich() 외에도 다음 값이 포함됩니다:

• locale — 전달한 BCP-47 문자열
• direction — "ltr" 또는 "rtl", 알려진 RTL 언어 fallback 목록과 함께 Intl.Locale.textInfo를 통해 계산됩니다.
• script — 예: "Latn", "Cyrl", "Arab"
• region — 예: "US", "DE", "SA"

이 값들은 조건부 레이아웃(RTL에서 아이콘 미러링)이나 analytics 태깅에 유용하며, 별도의 파싱이 필요 없습니다.

자주 하는 실수#

• <LingoProvider>를 빼먹는 경우. useLingo()는 provider 밖에서 호출하면 오류를 던집니다. 오류 메시지에는 provider를 추가하라는 안내가 포함되어 있습니다. 테스트에서 이 오류가 보인다면 안정적인 assertions를 위해 빈 messages를 넣은 테스트용 provider로 render를 감싸세요.
• 비동기로 로드한 messages를 바로 전달하는 경우. messages는 동기 값이어야 합니다. 상위 컴포넌트에서 promise를 resolve한 뒤(Suspense 또는 state 사용) 그 결과를 내려보내세요.
• locale만 바꾸고 messages를 함께 업데이트하지 않는 경우. provider는 두 prop이 함께 전달된다고 가정합니다. 같은 useState 업데이트에서 둘 다 변경하지 않으면 잠시 동안 새 로캘에 이전 번역이 렌더링될 수 있습니다.