리액트 메시지 문제 해결
추출부터 렌더링까지, 메시지의 번역, 값, 태그 또는 로캘이 어디서 누락되는지 확인하세요.
실제로 화면에 표시되는 메시지를 따라가 보세요. 원문과 컨텍스트에 따라 키가 선택되고, 가장 가까운 프로바이더가 카탈로그를 제공하며, 선택된 템플릿에 호출 시 전달된 값으로 서식이 적용됩니다. 대개 이 입력값들을 살펴보면 생성된 키를 직접 수정하지 않고도 문제의 원인을 찾을 수 있습니다.
프로바이더 밖에서 useLingo 호출 시 오류 발생 #
테스트와 독립적인 미리보기에서도 훅을 호출하는 컴포넌트보다 위에 LingoProvider를 배치하세요. 같은 컴포넌트에서 반환하는 프로바이더는 해당 훅보다 아래에 놓입니다. 훅을 자식 컴포넌트로 옮기거나, 리액트 컨텍스트를 통해 렌더링하지 않는 함수에서는 createLingo(locale, messages)를 사용하세요.
현재 프로바이더 구현에는 리액트 19를 사용하세요. 패키지에 명시된 피어 의존성 범위가 더 넓더라도, 이 구현에서 사용하는 리액트 19의 컨텍스트 축약 문법이 리액트 18과 호환되는 것은 아닙니다.
번역 대신 원문이 표시됨 #
- 가장 가까운 프로바이더의 실제
locale와messages를 확인하세요. 메시지는 해시를 문자열에 매핑하는 맵이어야 합니다. 파일 URL이나 프로미스,LocaleFile는 사용할 수 없습니다. - 실제 호출을 정확히 기준으로 삼아
computeKey(source, context)를 계산하고, 제공된 맵에서 해당 키를 찾아보세요. 문장 부호, 공백, 컨텍스트가 바뀌면 별개의 메시지로 식별될 수 있습니다. - 추출 결과에 키가 없다면
l.text(...)처럼 지원되는 수신 객체를 사용하고, 원문과 컨텍스트를 리터럴로 지정한 뒤 다시 추출하세요. 동적으로 계산되는 호출은 실행 시 렌더링되더라도 추출되지 않을 수 있습니다. - 원문 카탈로그에는 키가 있지만 대상 언어 카탈로그에는 없다면, 완료된 번역을 가져와 맵을 다시 불러오세요. 제출만으로 파일이 애플리케이션에 추가되지는 않습니다.
- 파일에는 키가 있지만 프로바이더에는 없다면, 로더의 경로와 라우트 선택을 확인하세요. 번역된 JSONC에서 메타데이터가 사라졌을 때 필요한 원문 키 결합 방법은 카탈로그 불러오기에서 확인할 수 있습니다.
값이 누락되거나 빈 문자열이면 모두 원문을 대신 표시합니다. 개발 환경에서는 경고를 통해 두 경우를 구분하며, 키와 로캘이 같으면 경고를 중복으로 표시하지 않습니다. 프로덕션 환경에서는 이러한 진단 메시지를 표시하지 않으므로, 콘솔이 비어 있다고 해서 카탈로그가 완전하다고 볼 수는 없습니다.
넥스트 로더는 파일이 없으면 {}를 반환하지만, JSONC 형식이 잘못되면 오류를 발생시킬 수 있습니다. 탠스택의 내장 카탈로그는 파일 누락, 불러오기 실패, 파싱 실패를 모두 {}로 처리하고 그 결과를 캐시합니다. 어느 경우든 원문이 대신 표시되어 페이지를 읽을 수는 있지만, 불러오기 문제가 드러나지 않을 수 있습니다.
플레이스홀더나 ICU 표현식이 그대로 표시됨 #
호출에 전달되는 values 객체를 확인하세요. 단순 치환 값이 누락되면 {name}가 그대로 표시됩니다. 값 객체가 없으면 런타임은 선택된 템플릿에 서식을 적용하지 않고 그대로 반환합니다.
복잡한 ICU 메시지라면 선택된 대상 언어 템플릿의 문법, 인수 이름, 값의 자료형을 확인하세요. 파싱이나 서식 지정 중 오류가 발생하면 해당 템플릿을 그대로 반환하고, 개발 환경에서는 중복을 제거한 오류 메시지를 출력합니다. 따라서 영어 원문 대신 잘못된 번역이 표시될 수 있습니다. 템플릿을 수정하거나 누락된 인수를 전달한 뒤 해당 경우를 다시 렌더링하세요.
생성된 선언은 원문에서 감지된 인수에 관한 오류를 잡아내지만, 대상 언어 템플릿의 문법을 검증하거나 ICU 분기 안에 중첩된 모든 플레이스홀더를 찾아내지는 않습니다. 실제 값을 넣어 문제가 발생한 분기를 실행해 보세요.
링크가 사라지거나 태그가 텍스트로 표시됨 #
서식 있는 메시지는 tags.link처럼 이름이 지정된 콜백을 사용합니다. 콜백 이름은 번역된 태그 이름과 정확히 일치해야 하며, 링크 대상은 콜백 안에 유지해야 합니다. 알 수 없는 태그 쌍, 자체 닫힘 태그, 닫는 태그가 없는 여는 태그는 그대로 텍스트로 남습니다.
중첩된 요소에는 서로 다른 이름을 사용하세요. 같은 이름을 반복해서 중첩하는 구조는 파서가 지원하지 않습니다. 서식 있는 메시지는 전체 ICU 문법이 아닌 단순 플레이스홀더를 지원합니다. ICU 문법이 필요하면 텍스트 문법 도우미를 사용하세요. 지원되는 형식은 서식 있는 텍스트에서 확인할 수 있습니다.
URL은 바뀌지만 언어는 바뀌지 않음 #
로캘과 카탈로그를 함께 교체하세요. 로캘만 변경하면 프랑스어 텍스트에 스페인어 규칙으로 서식이 적용될 수 있습니다. 중첩된 프로바이더도 확인하세요. 로캘이 다른 자식 프로바이더는 독립적으로 동작하며 부모의 카탈로그를 상속하지 않습니다.
선택한 어댑터의 전환 방식을 따르세요. 넥스트 페이지는 라우터 탐색과 로캘 쿠키를 사용합니다. 탠스택은 새 요청으로 새 카탈로그를 불러올 수 있도록 일반 앵커를 사용합니다.
하이드레이션 중 텍스트, 방향 또는 날짜가 바뀜 #
서버와 클라이언트의 입력값인 카탈로그 리비전, 로캘, 값, 타임스탬프, 시간대, 상대 시간의 기준을 비교하세요. 프레임워크 셸에서 문서의 lang와 dir를 설정하세요. 기본 프로바이더는 이 속성들을 변경하지 않습니다. 그런 다음 서버 렌더링 점검 목록에 따라 초기 HTML과 하이드레이션이 완료된 페이지를 테스트하세요.