useLingo

useLingo()는 컴포넌트가 런타임에 접근하는 방법입니다. 가장 가까운 <LingoProvider>를 읽어 활성 Lingo 객체를 반환합니다. 컴포넌트마다 한 번만 호출해 참조를 보관한 뒤, 필요한 메서드를 사용하면 됩니다.

tsx

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

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}

provider 밖에서 호출하면 예외가 발생하므로, 테스트 환경에서는 렌더링을 반드시 provider로 감싸야 합니다. 테스트에서 번역이 중요하지 않더라도 messages: {}로 감싸야 하는 건 동일합니다.

`l.text(source, options)` — 일반 문자열#

가장 기본적으로 쓰는 호출입니다. 번역된 문자열을 반환하고, 현재 로캘에 해당하는 번역이 없으면 원문을 그대로 반환합니다.

tsx

l.text("Save", { context: "Form button" });
// → "Speichern" (de) / "Save" (en, fallback)

보간#

{placeholder} 세그먼트는 options.values의 값으로 치환됩니다.

tsx

l.text("Welcome back, {name}!", {
  values: { name: user.firstName },
  context: "Dashboard greeting",
});

값이 빠지면 {name}가 그대로 렌더링됩니다. 개발 중 버그를 찾기엔 유용하지만, 빈 값이 그대로 통과하지 않도록 테스트에서는 실제 렌더링 결과를 기준으로 검증해야 합니다.

원문에 ICU 구문이 들어 있는 경우#

원문 문자열에 복수형 / select / 숫자 / 날짜 마커가 들어 있으면 런타임이 자동으로 상위 기능으로 전환합니다. 별도의 API는 필요하지 않습니다. 더 간편한 래퍼는 복수형 및 select를 참고하세요.

`l.rich(source, options)` — React 서브트리#

번역된 텍스트에 React 컴포넌트(링크, 볼드 텍스트, <Icon/> 등)가 포함되어 있다면 l.rich를 사용하세요. 번역 문자열에는 <link>...</link> 같은 플레이스홀더 태그가 들어가며, 각 태그를 렌더러에 매핑하면 됩니다.

tsx

l.rich("Click <link>here</link> for {topic}", {
  tags: {
    link: (children) => <a href="/help">{children}</a>,
  },
  values: { topic: "details" },
  context: "Footer help link",
});
// → <>Click <a href="/help">here</a> for details</>

self-closing 태그도 지원합니다:

tsx

l.rich("Loading <spinner/>...", {
  tags: { spinner: () => <Spinner /> },
  context: "Inline loading state",
});

렌더러가 없는 태그는 원문 텍스트로 폴백됩니다. 그래서 누락된 태그가 조용히 사라지지 않고, 개발 중에 바로 눈에 띕니다.

번역 문자열 안에 마크업을 직접 넣지 마세요. l.rich가 있는 이유는 번역자가 <a href="...">를 그대로 보존해야 하는 대신, 중립적인 플레이스홀더(<link>)를 보게 하기 위해서입니다. 마크업은 그대로 유지해야 해서 자주 깨지기 때문입니다. 렌더러는 로캘 파일이 아니라 코드에서 정의하세요.

`l`의 로캘 메타데이터#

번역 기능 외에도 이 객체는 다음을 제공합니다:

속성	타입	참고
`l.locale`	`string`	`LingoProvider`에 전달한 값입니다. BCP-47 형식입니다.
`l.direction`	`"ltr"` \| `"rtl"`	`Intl.Locale.textInfo`와 폴백 RTL 언어 목록을 기준으로 계산됩니다.
`l.script`	`string` \| `undefined`	가능한 경우 추론됩니다(`"Latn"`, `"Cyrl"`, `"Arab"`, …).
`l.region`	`string` \| `undefined`	BCP-47을 기준으로 추론됩니다(`"US"`, `"DE"`, `"SA"`, …).

레이아웃을 결정할 때 유용합니다:

tsx

const l = useLingo();
return <div dir={l.direction}>...</div>;

l에는 num, currency, percent, date, time, datetime, relative, list, displayName, sort, segment, fileSize, compact, unit도 포함되어 있습니다. 전체 내용은 Formatting에서 확인하세요. 모두 l.locale에 맞춰진 기본 Intl.* 포매터를 감싼 가벼운 래퍼입니다.

React 외부에서 사용하기#

useLingo는 컴포넌트 내부에서만 사용할 수 있습니다. 유틸리티, 라우트 로더, 서버 코드에서는 같은 객체를 직접 생성하세요:

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

const l = createLingo("es", messages);
l.text("Hello", { context: "Email subject" });

provider 없이도 동일한 Lingo 형태를 만들 수 있습니다. LingoProvider 자체도 내부적으로 createLingo를 사용합니다.

tsx

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

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}