리액트 메시지

소스 텍스트와 맥락을 컴포넌트에 함께 두고, 값과 문법, 리액트 요소를 반영해 번역 카탈로그를 렌더링하세요.

컴포넌트의 메시지는 설명하려는 동작과 함께 있어야 합니다. 폼에서 “저장”은 변경 사항을 제출하는 동작이고, 기사에서 “저장”은 북마크를 만드는 동작입니다. 소스 텍스트와 의미를 함께 두면 번역자는 이 차이를 파악할 수 있고, 개발자도 다른 파일에서 키를 찾아볼 필요 없이 컴포넌트를 이해할 수 있습니다.

@lingo.dev/react는 명시적인 메시지 호출을 사용합니다:

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

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

소스 텍스트와 맥락은 카탈로그에서 메시지를 식별하는 기준이 됩니다. 카탈로그는 키와 번역 문자열을 연결한 맵입니다. 프로바이더는 이 카탈로그와 현재 활성화된 로캘을 제공합니다. 컴포넌트는 번역된 텍스트를 받으며, 해당 항목이 없거나 비어 있으면 소스 텍스트를 받습니다.

컴포넌트에서 다른 언어로 #

먼저 로컬에서 번역을 렌더링해 보세요. 작은 카탈로그를 사용하면 계정을 만들거나 네트워크 요청을 보내지 않고도 조회 과정을 확인할 수 있습니다.

애플리케이션 워크플로에서는 lingo extract가 인식할 수 있는 호출을 소스 JSONC 카탈로그에 모으고 타입스크립트 선언을 생성합니다. CLI는 이 파일을 번역용으로 전송하고 번역된 대상 파일을 가져옵니다. 로더는 이 파일을 프로바이더가 사용하는 문자열 맵으로 변환합니다. 카탈로그 추출 및 로딩에서는 번역된 JSONC에서 메타데이터 주석이 사라졌을 때 활성 메시지를 유지하는 방법까지 이 과정 전체를 다룹니다.

렌더링은 로컬에서 이루어집니다. 런타임은 로컬라이제이션 엔진에 접속하지 않으며 API 키도 포함하지 않습니다. 서버 측 번역은 API 통합에서 처리하고, 결과 카탈로그는 애플리케이션의 일반적인 빌드 과정이나 요청 시 로딩 과정을 통해 전달하세요.

독자에게 필요한 메시지 작성하기 #

따로 번역한 문장 조각을 이어 붙이는 대신, 플레이스홀더를 넣은 완전한 문장을 사용하세요. 언어에 따라 이름, 개수, 링크가 문장 안에서 다른 위치에 올 수 있습니다.

메시지에 필요한 요소사용할 기능
값이 포함된 일반 텍스트l.text.
링크, 강조 또는 다른 리액트 요소l.rich와 이름이 지정된 렌더 콜백.
수량에 따른 문법 변화 또는 범주별 선택l.plural과 l.select.
숫자, 날짜, 목록 또는 로캘을 고려한 텍스트 연산내장 Intl를 사용하는 서식 지정 메서드.

프로바이더와 훅 레퍼런스에서는 중첩 카탈로그와 컴포넌트 외부 코드에서 사용하는 createLingo를 설명합니다. 로캘 메타데이터는 문서와 레이아웃을 적절히 구성하는 데 필요한 쓰기 방향, 문자 체계, 지역 정보를 제공합니다.

메시지를 중심으로 애플리케이션 연결하기 #

Next.js Pages와 TanStack Start 어댑터는 카탈로그를 각 프레임워크의 라우팅 시스템에 연결합니다. 다른 환경에서는 렌더링 전에 로캘과 메시지를 로드하고, 서버 렌더링과 하이드레이션 과정에서도 두 항목의 조합을 유지하세요.

생성된 타입을 사용해 편집 중에 소스 텍스트, 맥락, 값의 오류를 찾아내세요. 렌더링 테스트로 실제로 로드된 템플릿을 확인하세요. 번역이 표시되지 않으면 문제 해결 안내에 따라 컴포넌트에서 카탈로그까지 조회 과정을 살펴보세요.

내보내기 #

루트에서는 LingoProvider, useLingo, createLingo, computeKey와 함께 LingoProviderProps, Lingo, Messages, LingoMessages, MessageKey, TextOptions, RichOptions, PluralForms, SelectForms, FormatMethods 타입을 내보냅니다. 별도의 @lingo.dev/react/testing 진입점에서는 withLingo와 renderStatic를 내보냅니다.