기존 리액트 메시지 마이그레이션
플레이스홀더, 복수형 동작, 승인된 번역을 그대로 유지하면서 소규모 리액트 메시지 테스트 구성을 명시적인 원문·컨텍스트 기반 메시지로 이전하세요.
기존 리액트 카탈로그에는 조회 식별자, 보간 규칙, 복수형 동작, 검토를 거친 번역 등 유용한 결정 사항이 이미 담겨 있습니다. 원문·컨텍스트 기반 메시지로 이전할 때도 이 작업의 결과를 보존해야 합니다. 먼저 컴포넌트 하나를 완전히 변환하고, 승인된 번역을 새 식별자에 매핑하세요. 그런 다음 렌더링 결과를 비교한 뒤 마이그레이션 범위를 넓히세요.
식별자를 바꾸기 전에 기존 동작 기록하기 #
레이블, 변수, 링크, 개수, 조건부 메시지가 포함된 컴포넌트를 선택하세요. 기존 키, 원문과 번역문, 보간 구문, 네임스페이스, 프로바이더 로캘을 저장하세요. 고정된 값으로 원문 언어와 대상 언어 하나에서 렌더링하세요. 이렇게 하면 마이그레이션 후에도 유지해야 할 구체적인 결과를 확보할 수 있습니다.
예를 들어 기존 i18next 방식의 호출은 다음과 같을 수 있습니다.
t("account.greeting", { name });원문 카탈로그에는 Welcome, {{name}}이 포함되어 있을 수 있습니다. 이 보간 구문을 새 메시지 규약에 그대로 복사하지 마세요. 명시적인 리액트 메시지는 이름이 지정된 {name} 변수를 사용합니다.
l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});여기에 나온 구분자 변경은 해당 원본 라이브러리 설정에만 적용됩니다. 다른 메시지를 변환하기 전에 설치된 라이브러리를 확인하세요. 사용자 지정 보간 구분자와 복수형 규칙에 따라 변환 방식이 달라질 수 있습니다.
메서드 이름뿐 아니라 메시지 동작까지 매핑하기 #
값이 포함된 일반 메시지에는 text, 이름이 지정된 컴포넌트 슬롯에는 rich, 개수에 따라 달라지는 형식에는 plural, other 대체 항목을 갖춘 정확한 값별 분기에는 select를 사용하세요. 리치 대화형 메시지에서 네 가지를 모두 사용하는 전체 예제를 확인할 수 있습니다.
기존 리치 메시지 컴포넌트는 링크를 인덱스로 표현할 수 있습니다. 이 인덱스를 의미 있는 이름의 슬롯으로 바꾸되, 링크 대상은 코드에 유지하세요. 변수 이름과 타입, 의미상 역할도 보존하세요. 기존 복수형 카탈로그는 접미사가 붙은 키를 저장할 수 있지만, 새 런타임은 각 형식을 바탕으로 복수형 메시지를 구성합니다. 접미사가 붙은 키를 기계적으로 바꾸지 말고 대상 언어에서 어떻게 동작하는지 확인하세요.
메시지의 용도를 설명하는 컨텍스트를 선택하세요. 새 식별자는 account.greeting이 아니라 원문 표현과 컨텍스트를 바탕으로 만들어집니다. 기존 키, 로캘, 추출된 새 키, 구문 변환 내용을 마이그레이션 표에 기록해 두세요. 인사말에 해당하는 행에는 {{name}} 구문을 {name} 구문으로 변환한 내용을 기록합니다. 이 매핑을 통해 검토자는 승인된 표현이 새 카탈로그로 어떻게 옮겨졌는지 추적하고, 아직 매핑되지 않은 메시지도 확인할 수 있습니다.
소규모 카탈로그를 신중하게 추출하고 가져오기 #
리액트 빠른 시작에 따라 @lingo.dev/react을 설치하고 LingoProvider를 구성하세요. 현재 프로바이더 구현에는 리액트 19를 사용하세요. 리액트 18이 피어 의존성 범위에 명시되어 있더라도 이전 버전의 애플리케이션에서 테스트하는 과정을 대신할 수는 없습니다. 컴포넌트를 변환한 뒤 설치된 CLI를 실행하세요.
lingo extract --src src --source-locale en경로를 재정의하지 않았다면 locales/en.jsonc과 lingo.d.ts를 살펴보세요. 각 원문 메시지와 컨텍스트를 찾은 다음, 실제로 추출된 키를 마이그레이션 표에 복사하세요. 기존 키를 유지하거나 임의로 해시를 만들면 번역문이 런타임 조회와 연결되지 않습니다.
승인된 각 번역문을 매핑된 새 키 아래에 배치하세요. 의미를 유지하면서 플레이스홀더, 리치 슬롯, 복수형 구문을 신중하게 변환하세요. 카탈로그 로딩 워크플로에 따라 해시를 문자열에 매핑하는 번역 맵을 불러오세요. 번역 메타데이터가 없다면 대응하는 원문의 활성 키를 사용하세요. 매핑되지 않은 항목은 더 이상 사용하지 않는 항목으로 분류하지 말고, 남은 작업으로 계속 표시하세요.
요청된 로캘과 해당 번역 메시지를 LingoProvider에 함께 전달하세요. 점진적으로 마이그레이션하는 동안 기존 프로바이더와 새 프로바이더가 각각 해당 호출부를 감싸도록 유지하세요. 프로바이더 규약에서는 같은 로캘의 병합과 서로 다른 로캘의 격리를 설명합니다. 중첩된 화면을 마이그레이션할 때 이 동작을 확인하세요.
누락과 잘못된 형식 확인하기 #
마이그레이션 전에 사용한 값과 동일한 값으로 테스트 구성을 렌더링하세요. 화면에 표시되는 의미, 변수 위치, 링크 동작, 복수형 출력, 대체 항목 선택을 비교하세요. 개수가 0, 1, 그보다 큰 경우와 긴 변수 값, 알 수 없는 선택 값도 포함하세요.
로컬 테스트 구성에서 번역 항목 하나를 제거하고 원문으로 대체되는지 확인하세요. 메시지가 누락되거나 비어 있으면 원문이 렌더링될 수 있으므로, 화면이 정상적으로 보인다고 해서 번역이 모두 갖춰졌다고 볼 수는 없습니다. 생성된 선언을 포함해 추출 일관성 검사와 타입스크립트 검사를 수행한 다음, 애플리케이션의 기존 렌더링 테스트를 실행하세요. 타입이 보장하는 것은 호출 호환성이지 번역 품질이 아닙니다.
형식이 잘못된 리치 태그나 ICU 메시지의 출력과 진단 정보를 살펴보세요. 새 런타임에서는 마크업이 문자 그대로 표시되거나 서식이 적용되지 않은 템플릿이 그대로 드러날 수 있습니다. 기존 런타임을 제거하기 전에 이 동작이 애플리케이션 요구 사항에 맞는지 확인하세요. 이러한 제약은 리액트 문제 해결에 설명되어 있습니다.
에이전트의 작업도 검토를 거쳐 활용하기 #
에이전트에게 기존 라이브러리를 살펴보고, 키 매핑을 보존하고, 지원되지 않는 패턴을 파악하고, 원문 수정과 카탈로그 가져오기를 분리하도록 요청하세요. 에이전트가 제안한 원문 및 카탈로그 변경 사항은 적용하기 전에 검토하세요.
테스트 구성이 렌더링 검사와 네이티브 검사를 통과하면 컴포넌트 또는 네임스페이스 단위로 범위를 넓히세요. 모든 호출부와 승인된 번역문의 이전 대상이 검증될 때까지 두 카탈로그를 모두 유지하세요. 기존 프로바이더와 의존성은 이를 사용하는 코드가 더 이상 없을 때만 제거하세요. API 클라이언트와 라우터 어댑터는 각각 별도의 역할을 담당합니다. 메시지 런타임을 바꾼다고 해서 이들이 대체되지는 않습니다.