코드 검토에서 리액트 로컬라이제이션 점검하기
추출, 카탈로그 검사, 타입스크립트, 애플리케이션 빌드로 병합 전에 다양한 로컬라이제이션 결함을 찾아내세요.
리액트 메시지의 변경 사항은 소스 코드, 추출, 대상 카탈로그, 애플리케이션 로더를 거쳐 사용자에게 전달됩니다. 문구뿐 아니라 이 전달 과정도 함께 검토하세요. 번역이 정확해도 이전 식별자에 연결되어 있으면 표시되지 않습니다. 원문이 대신 표시되면 화면은 계속 사용할 수 있지만, 번역 누락을 알아차리지 못할 수 있습니다.
이 방법은 CLI로 추출한 JSONC 카탈로그를 사용하는 현재 리액트 패키지에 적용됩니다. CLI의 추출 검사와 함께 프로젝트 자체의 빌드 및 렌더링 검사도 실행하세요.
소스 변경 사항부터 살펴보기 #
새 소스 메시지를 사용자에게 전달하는 지시나 설명으로 읽어 보세요. 그런 다음 문맥을 살펴보세요. “버튼”은 형태를 설명하지만, “제출 전에 예약된 결제 취소”는 번역에서도 의미가 유지되어야 할 동작을 설명합니다. 원문과 문맥이 모두 식별자를 결정하므로, 문맥만 수정해도 새 대상 항목이 필요할 수 있습니다.
플레이스홀더는 용도가 일관되게 유지되어야 하는 값으로 보고 검토하세요. 번역자가 사람의 이름이나 금액의 위치를 바꾸더라도 각 값의 식별자는 바뀌지 않아야 합니다. 서식 있는 텍스트에서는 탐색과 컴포넌트 동작을 코드에 두고, 이름이 지정된 태그를 둘러싼 문장을 번역하세요. 정확한 API는 메시지와 서식 있는 텍스트에서 확인할 수 있습니다.
대상 카탈로그보다 추출 먼저 확인하기 #
CLI가 설치된 상태에서 검사할 프로젝트 디렉터리로 이동해 실행하세요.
lingo extract --check
lingo check프로젝트의 추출 명령과 동일한 --src, --source-locale, --out, --types 옵션을 사용하세요. 소스 로캘의 기본값은 en이며, 로컬라이제이션 설정을 바꿔도 이 명령의 기본값은 바뀌지 않습니다. 이어서 생성된 선언까지 포함해 저장소의 타입스크립트 검사와 프로덕션 빌드를 실행하세요.
| 로컬 검토용 테스트 데이터에 의도적으로 넣을 결함 | 검사 단계와 예상 결과 |
|---|---|
| 카탈로그나 선언을 다시 생성하지 않고 소스 메시지를 변경합니다. | extract --check은 생성된 결과물을 비교해 최신 상태가 아니면 실패합니다. |
| 추출된 메시지에서 필수 문맥을 누락합니다. | check은 추출 또는 문맥 문제를 보고합니다. 소스를 살펴보고 의미를 바로잡으세요. |
| 기존 대상 JSONC 카탈로그에서 항목을 누락하거나 비워 둡니다. | check은 검색된 카탈로그의 번역 누락을 보고합니다. |
| 생성된 선언을 최신 상태로 갱신하지 않습니다. | 추출 및 검사 과정에서 생성 결과의 불일치를 감지하고, 타입스크립트는 애플리케이션에서의 사용을 별도로 검사합니다. |
| 로캘 가져오기나 프레임워크 연동에 오류를 만듭니다. | 애플리케이션의 실제 빌드에서 연동 오류가 드러나야 합니다. |
이러한 검사를 처음 구성할 때는 로컬 테스트 데이터를 사용하세요. extract --check은 소스 파일을 찾지 못해도 성공하므로, 보고된 디렉터리에 검사하려는 코드가 있는지 확인하세요. 그렇지 않으면 검사를 통과했다는 결과가 실제로는 아무것도 검사하지 않았다는 뜻일 수 있습니다.
필수 로캘이 모두 포함되었는지 명시적으로 확인하기 #
.lingo/config.json의 files 패턴이 소스 카탈로그와 일치하면(예: locales/en.jsonc), lingo check은 설정된 모든 대상 로캘 파일도 요구합니다. lingo init --yes에서 작성하는 패턴인 locales/en.json은 .jsonc 카탈로그와 일치하지 않으므로, 이 패턴을 사용하면 리액트 검사만 실행됩니다. 이 경우 기존 JSONC 대상 카탈로그 내에서만 누락된 키를 보고합니다. 검토할 때 필수 로캘 목록을 파일 및 가져오기 구문과 비교하세요. 로컬 테스트 데이터에서 대상 항목을 잠시 제거해 원문이 대신 표시될 때 화면에 어떻게 나타나는지 확인하세요.
대표적인 원문과 번역문 쌍을 읽으며 의미를 확인하세요. 특히 사용자에게 약속하는 내용의 변경과 제품 용어를 주의 깊게 살펴보세요. JSONC 일관성 검사를 통과했다고 해서 의미까지 평가된 것은 아닙니다. ARB, 안드로이드 XML, 애플 카탈로그, 정적 문서는 이 리액트 전용 로캘 포함 여부 검사가 아니라 각 형식에 맞는 방식으로 검증해야 합니다.
검토된 결과물을 보존하며 변경 사항 정리하기 #
lingo extract으로 오래된 결과물을 다시 생성하고, 추가된 항목과 더 이상 참조되지 않는 항목을 살펴본 뒤 필요한 변경분을 번역하세요. 검토를 마친 대상 문구와 로컬라이제이션 잠금 파일은 보존하세요. 더 이상 참조되지 않는 항목을 제거하면 카탈로그가 바뀌므로, 소스 메시지 변경과 별도로 검토해야 합니다.
번역을 소스 브랜치에 반영할지, 별도의 번역 PR로 반영할지 선택하세요. CI 가이드에서는 반영 방식별 장단점과 관리형 앱의 차이점을 설명합니다. 어느 방식이든 병합 권한은 실행 권한 및 콘텐츠 승인과 분리하세요.
마지막으로 대표적인 값을 넣고 대상 로캘로 변경된 화면을 불러오세요. 서식 있는 텍스트의 링크를 열어 보고, 원문 대체 표시 동작을 확인하고, 화면에 표시된 메시지가 의도한 동작과 일치하는지 비교하세요. 프로그램의 메시지 전달 경로와 문구를 모두 살펴보아야 검토가 완료됩니다.