빠른 시작

npm install @lingo.dev/react

Next.js를 사용 중이라면 @lingo.dev/react-next도 함께 설치하세요. 같은 런타임을 기반으로 라우터를 인식하는 헬퍼를 추가해 줍니다.

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

export function App() {
  return (
    <LingoProvider locale="es" messages={esMessages}>
      <Page />
    </LingoProvider>
  );
}

messages는 콘텐츠 해시를 키로 사용하는 객체로, CLI가 locales/<locale>.json에 출력하는 형식과 정확히 같습니다. 처음 실행할 때는 비어 있어도 괜찮습니다. 번역되지 않은 문자열은 원본 텍스트가 그대로 표시됩니다.

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

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

l.text(source, { context })가 기본 호출 방식입니다. context는 필수입니다. 영어에서는 같은 문자열이라도 다른 언어에서는 의미가 달라질 수 있기 때문에("Save" 동사 vs. "Save" 명사), 번역자가 이를 정확히 구분할 수 있게 해줍니다.

lingo extract

이 단계에서는 소스 코드를 스캔하고, "Hello" + 컨텍스트에 대한 안정적인 해시를 계산한 뒤, 이를 소스 로캘 파일(기본값은 locales/en.jsonc)에 기록합니다. 변경 사항이 생길 때마다 다시 실행하세요. 추출은 멱등적으로 동작합니다.

lingo push --backfill-missing

CLI는 소스 파일을 업로드하고, 엔진에 설정된 대상 로캘로 번역을 요청한 다음, 결과를 locales/<locale>.json로 다시 내려받습니다. 이후부터는 푸시할 때마다 변경된 내용만 전송됩니다.

앱이 현재 렌더링하는 로캘의 JSON 파일을 가져오거나(또는 사용자에 따라 동적으로 선택해) 이를 LingoProvider에 전달하세요. 3단계에서 사용한 훅 호출은 그대로 유지됩니다. 이제 해시가 내려받은 값과 일치하므로 l.text("Hello", ...)가 번역된 값을 반환합니다.