🛠️ i18n 영어 번역시 트러블슈팅

키값이 그대로 노출되는 문제 완벽 해결법

다국어 웹 서비스를 개발하다 보면, 영어 번역을 추가할 때 번역 키값이 그대로 화면에 노출되는 황당한 경험을 하게 됩니다. 예를 들어,
t('leads.dashboard.period')를 호출했는데 화면에 leads.dashboard.period가 그대로 뜨는 현상입니다.
이 글에서는 왜 이런 일이 발생하는지,
한 번만 세팅하면 앞으로 다시는 이런 문제가 생기지 않게 만드는 방법을
실전 코드와 함께 정리합니다.

1. 문제의 원인

i18next(react-i18next)에서 번역 키가 번역 파일에 없을 때,
기본적으로 키값 자체를 반환합니다.

영어 번역 파일(en/translation.json)에 "leads.dashboard.period": "Period"가 없으면
t('leads.dashboard.period') 호출 시
화면에 leads.dashboard.period가 그대로 노출됨

이 현상은 번역 파일 관리가 조금만 소홀해도 자주 발생합니다.

2. 근본적인 해결책

(1) i18n 설정에서 키값 노출 방지 옵션 추가
i18n 초기화 시 아래 옵션을 추가하세요.

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    lng: 'ko',
    returnNull: false,         // 키가 없을 때 null 반환 방지
    returnEmptyString: false,  // 키가 없을 때 빈 문자열 반환 방지
    saveMissing: process.env.NODE_ENV === 'development', // 개발환경에서 누락 키 추적
    // ...기타 설정...
  })

returnNull: false, returnEmptyString: false
→ 키가 없을 때 null/빈문자열이 아닌 fallback 언어(예: 한국어)로 자동 대체
→ 키값이 그대로 노출되는 현상 방지
saveMissing: true
→ 개발 환경에서 누락된 키를 자동으로 기록(콘솔, 서버, 파일 등)
→ 번역 누락을 빠르게 추적 가능

(2) 번역 파일 자동 동기화(권장)
모든 언어의 번역 파일에 동일한 키가 항상 존재하도록
자동화 스크립트(i18next-scanner, custom node script 등)로 관리
새 키가 추가되면 모든 언어 파일에 자동으로 추가(미번역은 빈 문자열 또는 "TODO" 등으로 표시)
CI(빌드) 단계에서 누락된 키가 있으면 에러로 처리

3. 실전 적용 예시

• i18n.ts 설정 예시

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    lng: 'ko',
    returnNull: false,
    returnEmptyString: false,
    saveMissing: process.env.NODE_ENV === 'development',
    // ...기타 설정...
  })

• 번역 파일 예시 (en/translation.json)

{
  "leads": {
    "dashboard": {
      "period": "Period"
    }
  }
}

4. 앞으로의 번역 관리 팁

번역 파일에 키가 없을 때 화면에 키값이 그대로 뜨는 문제는 위 설정만 하면 더 이상 발생하지 않습니다.
개발 환경에서는 누락된 키를 자동으로 추적할 수 있어, 번역 누락도 빠르게 보완할 수 있습니다.
번역 파일만 잘 관리하면, 추가 작업 없이 안전하게 다국어 지원이 가능합니다.

5. 결론

i18n의 옵션 몇 줄만 추가해도,
영어 번역 추가 시 키값이 그대로 노출되는 문제를 완벽하게 예방할 수 있습니다.
한 번만 세팅해두면,
앞으로는 번역 파일만 잘 관리하면 되고,
키값 노출로 인한 당황스러운 상황이 반복되는 걸 방지할 수 있습니다.