기존 서비스 국제화(i18n) 작업을 쉽게 덜어내는 t 함수 자동 래핑 스크립트 만들기

글로벌 서비스 출시를 앞두고 기존 React/Next.js 코드에 i18n을 빠르게 입히기 위해, Babel AST 기반 자동화 스크립트를 만들었다.

먼저 언어 자원 키 컨벤션을 세 가지로 검토한 뒤, 개발 속도와 팀 생산성을 우선해 한글 키 방식을 최종 선택했다. 직관적이고 빠르게 적용할 수 있다는 점이 가장 큰 이유였지만, 텍스트 변경 시 키를 함께 수정해야 하고 중복 관리 이슈가 있다는 한계도 함께 정리했다.

핵심은 두 개의 도구로 나뉜다.

• T Wrapper: 기존 코드 안의 한글 텍스트를 찾아 자동으로 t(...)로 감싼다.
• Extractor: 코드 전체에서 번역 대상 한글을 모아 언어 자원 JSON 파일을 생성한다.

T Wrapper는 @babel/parser, @babel/traverse, @babel/generator를 이용해 동작한다. 우선 FunctionLike 노드 중에서 JSX가 있거나 커스텀 훅처럼 보이는 대상만 골라 처리하고, 화살표 함수의 암시적 반환은 훅을 넣을 수 있도록 블록문과 명시적 return으로 바꾼다.

그다음 문자열 리터럴, JSXText, 조건식, 템플릿 리터럴을 순회하며 한글을 t로 래핑한다. 템플릿 리터럴은 interpolation을 위해 동적 값도 2번째 인자로 넘기되, 속성 이름은 코드에서 사용한 그대로 유지했다.

useTranslation은 최상위 함수에서만 삽입되도록 제한했고, 실제로 t가 사용되는 경우에만 import를 추가했다. 여기에 i18n-automation.config.yaml을 도입해 runOn, targetPaths, ignorePaths를 프로젝트별로 조정할 수 있게 만들었다. 이를 통해 React면 react-i18next, Next.js면 next-i18next를 자동으로 맞춰 import할 수 있었다.

Extractor는 범위를 더 넓게 잡아 프로젝트 전체를 대상으로 StringLiteral, JSXText, JSXAttribute, TemplateLiteral을 훑는다. 컴포넌트 내부뿐 아니라 상수와 변수에 들어간 한글까지 모아 각 언어 폴더의 JSON으로 만들고, 한국어 키와 값은 동일하게 두어 이후 번역 작업의 기준점으로 삼았다.