첫 번역 메시지 렌더링하기

로컬 카탈로그로 스페인어 인사말을 표시하고, 이름을 대입하고, 번역이 없을 때 원문이 표시되는지 확인하세요.

영어 원문 메시지를 바탕으로 올라, 아나.를 렌더링합니다. 이 예제에는 스페인어 번역이 준비되어 있어 컴포넌트, 카탈로그, 프로바이더가 어떻게 함께 작동하는지 정확히 확인할 수 있습니다. Lingo.dev 계정이나 API 키는 필요하지 않습니다.

React 19 애플리케이션에 설치하기 #

sh
npm install @lingo.dev/react@1.17.1

이 예제를 따라 하려면 기존 React 19 애플리케이션을 사용하세요. 패키지는 React 18과 19를 피어 의존성으로 선언하고 있지만, 프로바이더는 React 19의 컨텍스트 프로바이더 축약 문법을 사용합니다. React 18 프로젝트에 패키지가 설치된다고 해서 해당 환경에서 렌더링도 가능하다는 뜻은 아닙니다.

인사말과 카탈로그 추가하기 #

이 컴포넌트를 src/App.tsx에 넣고 애플리케이션의 기존 진입점을 통해 렌더링하세요:

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

const messages = {
  [computeKey("Hello, {name}.", "Greeting on the account dashboard")]:
    "Hola, {name}.",
};

function Greeting() {
  const l = useLingo();
  return (
    <h1>
      {l.text("Hello, {name}.", {
        context: "Greeting on the account dashboard",
        values: { name: "Ana" },
      })}
    </h1>
  );
}

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

애플리케이션의 개발 명령을 실행하고 페이지를 여세요. 제목에 올라, 아나.가 표시됩니다. 런타임은 원문과 컨텍스트를 바탕으로 동일한 키를 계산하고, 스페인어 템플릿을 찾은 다음, {name}을 Ana 값으로 바꿉니다.

카탈로그에는 문장 전체가 들어 있으므로 번역할 때 어순을 바꿀 수 있습니다. 이름은 키의 일부가 아닌 값이므로 이름이 달라져도 같은 카탈로그 항목을 사용합니다. 나중에 추출기가 찾을 수 있도록 l.text 호출 안의 원문과 컨텍스트는 리터럴로 유지하세요.

번역이 없을 때의 동작 확인하기 #

프로바이더에 임시로 messages={{}}을 전달하세요. 이제 제목에 헬로, 아나.가 표시됩니다. 원문이 대체 템플릿으로 사용되며 값 대입도 그대로 이루어집니다. 항목의 값이 ""인 경우에도 원문이 사용됩니다.

messages을 원래대로 되돌린 다음, 호출의 컨텍스트만 "Greeting on the profile page"로 바꾸세요. 그러면 다른 메시지로 식별되므로 기존 번역이 더 이상 일치하지 않습니다. 컨텍스트를 원래대로 되돌리면 다시 올라, 아나.가 표시됩니다. 이 과정을 통해 카탈로그가 없는 경우와 요청한 메시지가 번역된 메시지와 일치하지 않는 경우를 구분할 수 있습니다.

로컬 맵을 추출된 카탈로그로 바꾸기 #

이제 컴포넌트에서 메시지를 추출할 준비가 되었습니다. 카탈로그 추출 및 로드에서는 locales/en.jsonc을 생성하고, CLI 설정에서 선택하고, 스페인어 대상 번역을 가져와 안전하게 로드하는 방법을 안내합니다. 다음 단계에서는 이 작업을 처음부터 끝까지 진행합니다. 위의 로컬 예제는 이후에도 렌더링 테스트에 활용할 수 있습니다.

라우팅을 사용하는 애플리케이션이라면 Next.js Pages 또는 TanStack Start로 이어서 진행하세요. 로캘을 전환할 때는 새 로캘과 해당 메시지를 함께 적용해야 인터페이스에서 한 언어의 텍스트와 다른 언어의 서식이 섞이지 않습니다.