i18next-parser 사용해서 번역 프로세스 개선하기

도입 배경

회사에서 react-i18next로 다국어를 적용하고 있는데, 문제는 모든 문구가 키 기반으로만 관리되고 있었다.
컴포넌트에서는 t("SOME_KEY") 형태로만 쓰이다 보니, 실제 텍스트를 확인하려면 키를 검색해 JSON 파일에서 값을 찾아야 했다. 코드만 보고는 어떤 문구인지 바로 알 수 없었고, 맥락을 파악하는 데 불필요한 비용이 계속 발생했다. 또, 새로운 문구를 추가할 때마다 각 언어별 JSON에 키를 만들고 직접 값을 입력해야 하는 번거로움도 있었다. 온보딩 이후 맡은 리액트 네이티브 관련 에픽에서도 같은 불편이 있었고, 앞으로 번역 문구가 늘어나면 팀 전체가 겪을 문제라고 판단했다. 그래서 빠르게 적용할 수 있는 대안을 찾아 팀에 제안하게 되었다.

i18next-parser 도입

모노레포 환경에서의 사용

현재 여러 앱이 있는 모노레포 구조를 쓰고 있는데, i18next-parser는 CLI로 실행하기 때문에 앱별로 독립 설정을 두고, 필요한 워크스페이스에서만 실행할 수 있다. (특별히 복잡한 파이프라인 설정 없이도 바로 적용할 수 있음!)

기존 로케일 구조 유지

기존에 쓰던 로케일 구조는 그대로 두고 자동화를 추가할 수 있다.

src/utils/i18n/locales/
├── ko-KR/ko-KR.json
└── ja-JP/ja-JP.json

설정에서 출력 경로만 맞춰주면 된다.

점진적 마이그레이션 가능

keepRemoved: true 로 설정해 주면 기존 키는 유지되고, 새 문자열은 자동으로 추가되기 때문에, 점진적으로 마이그레이션이 가능하다.

// 기존
t("BUTTON_SUBMIT")

// 새로운
t("제출하기")

++ 유사 도구인 i18next-scanner는 Gulp 등 파이프라인에 얹기 좋고, i18next-parser는 CLI로 단순하게 카탈로그를 관리하기 좋다고 한다. 우리 환경에서는 빌드 체인 결합이 필요 없어서 parser가 더 적합해 보였다.

설정

// i18next-parser.config.cjs
module.exports = {
  input: ['src/**/*.{ts,tsx,js,jsx}', '!src/utils/i18n/locales/**'],
  output: // 파일 경로,
  locales: ['ko-KR', 'ja-JP'],
  defaultNamespace: 'translation',
  keySeparator: false,
  namespaceSeparator: false,
  defaultValue: (locale, _ns, key) =>
    locale === 'ko-KR' ? key : `[번역필요] ${key}`,
  keepRemoved: true, 
  sort: false,   
  ...
};

자동화 시 한국어가 아닌 경우에는 [번역필요] prefix를 붙여, 번역되지 않은 부분을 한눈에 확인할 수 있도록 했다. 이제는 한국어 원문을 그대로 코드에 작성하고 yarn i18n:extract만 실행하면 자동 반영된다.

사용 방식

t('로그인')
t('저장 {{value}}회', { value })
t('저장되었습니다')

<Trans i18nKey="greeting">
  안녕하세요, <strong>{{name}}</strong>님!
</Trans>

파서가 문자열을 추출해 ko-KR/translation.json, ja-JP/translation.json에 반영하게 되고, 아래와 같이 추가된다.

{
  "로그인": "[번역필요] 로그인",
  "저장 {{value}}회": "[번역필요] 저장 {{value}}회",
  "저장되었습니다": "[번역필요] 저장되었습니다"
}

++ 개선 방향을 정리해서 팀원분들께 공유드렸고, 다행히 현재의 불편함에 다들 공감해 주셔서 도입할 수 있게 되었다!