서식과 상호작용을 갖춘 메시지 현지화하기

문장은 통째로 번역하고, 링크와 컴포넌트, 값은 리액트 코드에서 계속 제어하세요.

“계속하기 전에 정책을 읽으세요”는 “정책”이 링크여도 하나의 문장입니다. 문장 전체를 하나의 번역 단위로 유지하면 다른 언어에서도 링크를 자연스러운 위치로 옮길 수 있습니다. 링크 대상은 그대로 애플리케이션 코드에서 제어합니다.

리액트 패키지의 rich 메서드는 이 링크를 이름이 지정된 슬롯으로 표현합니다. 카탈로그는 문장을 제공하고, 리액트 렌더러는 해당 슬롯에 들어갈 컴포넌트를 제공합니다.

링크가 포함된 문장을 통째로 렌더링하기 #

기존 리액트 19 애플리케이션에 @lingo.dev/react을 설치하세요. 이 로컬 예제는 설명용 스페인어 카탈로그를 사용하므로 별도로 번역을 요청할 필요가 없습니다.

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

const messages = {
  [computeKey(
    "Read the <policy>policy</policy> before continuing.",
    "Notice before account creation",
  )]: "Antes de continuar, lee la <policy>política</policy>.",
};

function ConsentNotice() {
  const l = useLingo();
  return (
    <p>
      {l.rich("Read the <policy>policy</policy> before continuing.", {
        context: "Notice before account creation",
        tags: {
          policy: (children) => <a href="/policy">{children}</a>,
        },
      })}
    </p>
  );
}

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

문단에는 “계속하기 전에 정책을 읽으세요.”라는 뜻의 스페인어 문장이 표시되어야 합니다. 번역문에서는 정책을 가리키는 부분의 위치가 바뀌지만, 링크는 여전히 /policy을 가리킵니다. 호출에 리터럴로 지정한 소스와 컨텍스트 덕분에 추출 과정에서도 메시지를 식별할 수 있습니다. computeKey은 임의로 만든 해시에 의존하지 않고 테스트 데이터의 실제 식별자를 구성합니다.

패키지에는 리액트 18과 19가 피어 의존성으로 선언되어 있지만, 프로바이더는 현재 리액트 19의 컨텍스트 문법을 사용합니다. 리액트 18에서는 별도로 검증하세요. 프로바이더 설정과 첫 카탈로그에 관한 설명은 리액트 빠른 시작을 참고하세요.

값과 동작은 코드에서 관리하기 #

policy이라는 이름은 번역자가 제공하는 에이치티엠엘 요소가 아니라 슬롯을 식별합니다. 링크 대상과 동작은 해당 렌더러가 관리합니다. 로캘별 링크 대상은 코드에 정의된 경로 매핑으로 결정하세요. 이벤트 핸들러와 임의의 에이치티엠엘 속성은 카탈로그에 넣지 마세요.

변하는 값에는 이름이 지정된 플레이스홀더를 사용하세요.

tsx
const greeting = l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

const countLabel = l.plural(
  count,
  { one: "# item", other: "# items" },
  { context: "Number of items in the cart" },
);

const roleLabel = l.select(
  role,
  { admin: "Administrator", other: "Member" },
  { context: "Account role label" },
);

이 호출들은 const l = useLingo()을 사용할 수 있고 name, count, role에 사용할 애플리케이션 값이 있는 컴포넌트 안에 작성해야 합니다. text은 일반 텍스트를 반환하고, plural은 개수에 따른 문법을 처리하며, select은 선택자와 정확히 일치하는 항목을 찾되 일치하는 항목이 없으면 other을 사용합니다. 서식 있는 텍스트 처리 경로는 이름이 지정된 태그와 단순한 값 보간을 지원하지만, 일반 텍스트 처리 경로의 복합 아이시유 포매터는 실행하지 않습니다. 이러한 런타임 처리는 복수형, 날짜, 숫자를 참고하세요.

소스는 정적으로 유지하세요. 소스 문자열에 사람의 이름을 넣으면 사람마다 소스 텍스트가 달라져 안정적으로 추출할 수 없습니다. 소스와 컨텍스트가 함께 식별자를 결정하므로, 컨텍스트에는 “계정 역할 레이블”처럼 용도를 설명하세요. 번역이 만들어진 뒤에는 컨텍스트를 신중하게 변경하세요.

로컬 테스트 데이터를 추출한 카탈로그로 교체하기 #

현재 버전의 CLI 설치 후 다음을 실행하세요.

sh
lingo extract --src src --source-locale en

경로를 따로 지정하지 않으면 locales/en.jsonc과 lingo.d.ts가 생성됩니다. 추출된 소스, 컨텍스트, 키를 확인하세요. 애플리케이션의 타입스크립트 설정에 선언을 포함하세요. 추출 기능은 인식 가능한 메시지 호출을 지원하지만, 임의로 동적 생성된 소스 문자열까지 찾아내지는 않습니다.

CLI 빠른 시작에 따라 인증하고 로컬라이제이션 엔진을 연결한 다음, .lingo/config.json에서 이 실제 locales/en.jsonc 소스와 필요한 대상 로캘을 선택하세요. 해당 파일 워크플로를 통해 카탈로그를 번역하고 가져오세요. 카탈로그 로딩 절차에 따라 제이슨시를 파싱하고, 일치하는 소스 리비전에서 활성 키를 선택한 뒤, 프로바이더에 대상 문자열을 제공하세요. 일반 파일 번역기는 번역 결과에 소스 카탈로그의 주석을 보존하지 않습니다.

가져온 스페인어 카탈로그로 같은 안내 문구를 불러오세요. 누락되거나 비어 있는 항목은 소스 텍스트로 대체되므로, 화면에 보이는 결과뿐 아니라 필요한 대상 키도 비교하세요.

상호작용과 잘못된 형식의 사례 테스트하기 #

키보드로 정책 링크를 열어 보고 접근성 이름을 확인하세요. 링크 위치가 바뀐 뒤에는 주변 문장 부호도 읽어 보세요. 완전한 번역은 문장의 의미와 독자가 수행할 수 있는 동작을 모두 보존해야 합니다.

로컬 카탈로그 테스트 데이터에서 태그 핸들러를 제거하고, 알 수 없는 태그를 추가하고, 태그 하나를 닫지 않은 상태로 두세요. 현재 렌더러는 알 수 없거나 짝이 맞지 않는 마크업을 텍스트로 남겨 둡니다. 같은 이름의 태그를 중첩할 때는 짝을 맞추는 동작에 제약이 있습니다. 이 렌더러는 임의의 에이치티엠엘을 렌더링하는 도구도, 형식이 잘못된 모든 메시지를 거부하는 검증기도 아닙니다.

일반 텍스트에서는 누락된 값과 형식이 잘못된 복합 아이시유 메시지를 확인하세요. 값이 채워지지 않은 플레이스홀더나 서식이 적용되지 않은 템플릿이 그대로 표시될 수 있으며, 개발 환경에서는 진단 정보도 제공됩니다. 개수와 역할 메시지에서는 대상 언어의 복수형 범주와 알 수 없는 역할을 테스트하세요. 이러한 확인 항목의 정확한 동작은 서식 있는 텍스트 레퍼런스와 리액트 테스트 지침을 참고하세요.