다국어 번역 키 관리 프로세스 개선하기

다국어 번역을 운영하면서 번역 키를 관리하는 일이 점점 어려워졌다. 서비스에서는 한국어를 기준으로 일본어와 영어 번역을 함께 관리하고 있었는데, 번역 문구는 Google Sheet에서 관리했고, 실제 코드에서는 react-i18next와 언어별 JSON 파일을 사용하고 있었다.
처음에는 한국어 문장을 그대로 i18n 키로 사용하고 있었다. 하지만 운영이 이어질수록 이 구조만으로는 관리하기 어려운 케이스가 늘어났다.
먼저 문맥에 따라 번역이 달라지는 문제가 있었다.
같은 한국어 문장이라도 화면에 따라 다른 번역이 필요한 경우가 생겼다. 예를 들어 한국어로는 같은 확인이어도, 어떤 화면에서는 단순히 모달을 닫는 의미일 수 있고, 다른 화면에서는 사용자가 특정 작업을 완료했다는 의미일 수 있다. 문제는 이 차이가 키 구조에서 드러나지 않는다는 점이었다. 한국어 문장을 그대로 i18n 키로 사용하고 있었기 때문에 코드에서는 둘 다 같은 확인 키를 바라본다. 반면 시트에서는 화면별로 다른 번역값이 들어갈 수 있다. 이때 개발 입장에서는 이 변경이 기존 확인 키를 수정해야 하는 것인지, 특정 화면을 위한 별도 키로 분리해야 하는 것인지 바로 판단하기 어려웠다.
결국 같은 한국어 문장이라도 번역값이 달라질 수 있는데, 그 차이를 안정적으로 추적할 기준이 부족했다. 이 때문에 번역이 변경될 때마다 해당 문구를 기존 키에 반영해도 되는지, 별도 키로 나눠야 하는지 확인해야 했다.
시트와 JSON의 표현 방식 차이도 있었다.
시트에서는 줄바꿈으로 관리되는 문구가, JSON에서는 i18next의 <1/>, <2> 같은 태그를 포함한 형태로 들어가기도 했다. 화면에 표시되는 내용은 같지만, 문자열 기준으로는 다른 값처럼 보였다. 또한 시트가 업데이트되면서 기존에 개발팀과 맞춰져 있던 문구 구조도 일부 달라졌다. 기존에는 하나의 JSON 키와 시트의 한 행이 어느 정도 대응되는 구조였지만, 시트가 개편되면서 화면상 줄이 나뉘는 문구가 여러 행으로 분리되는 경우가 생겼다.
결국 고민해야 할 문제는 세 가지였다.

같은 한국어 키를 계속 그대로 사용해도 되는가?
시트와 JSON이 실제로 같은 상태인지 어떻게 확인할 것인가?
문맥에 따라 달라지는 번역을 어떻게 안전하게 분리할 것인가?

이 문제들이 겹치면서 다국어 문구 관리가 점점 불안정해졌다. 그래서 이번에는 번역 키와 JSON 구조를 한 번 안정화하기로 했다. 처음부터 번역 관리 흐름 전체를 바꾸기보다는, 현재 구조 안에서 반복되는 확인 비용을 줄이고 문맥별 키 분리를 안전하게 진행할 수 있는 도구를 먼저 만들기로 했다.

왜 완전 자동화부터 하지 않았나

처음부터 모든 과정을 자동화하는 방법도 생각할 수 있었다. 예를 들어 시트 값을 기준으로 JSON을 자동 갱신하고, 코드의 t() 호출도 자동으로 바꾸고, 새로 필요한 번역값까지 자동으로 채우는 방식이다.
하지만 지금 당장 그 방향으로 바로 가기는 어려웠는데, 우선 일정상 여유가 많지 않았다. 번역 정합성 문제는 이미 작업 과정에서 계속 발생하고 있었고, 당장 PR 리뷰나 배포 전 확인에서 사용할 수 있는 방법이 필요했다.
또한 번역 프로세스는 다른 팀과의 일하는 방식도 함께 얽혀 있었다. Google Sheet를 어떤 기준으로 관리할지, 같은 한국어에 다른 번역이 필요한 경우 어떤 규칙으로 관리할지 등은 다른 팀과도 논의가 필요한 영역이었다. 하지만 이 논의를 위한 일정을 당장 잡기도 어려웠다.
그렇다고 논의가 끝날 때까지 기존 방식대로 계속 수동 확인을 하기에는 비효율이 컸다. 그래서 시트 운영 방식 자체를 바꾸거나 다른 팀의 작업 방식을 강제하기보다는, 지금 내가 통제할 수 있는 영역부터 정리해 보기로 했다. 
기준은 아래와 같이 정했다.

- 자동으로 비교할 수 있는 부분은 자동화한다.
- 사람이 판단해야 하는 부분은 도구가 후보만 제공한다.
- 검수가 필요한 값은 조용히 넘어가지 않도록 표시한다.
- 기존 협업 구조는 크게 바꾸지 않는다.

이번 작업은 처음부터 완전 자동화가 아니라, 운영 중인 구조 안에서 안전하게 쓸 수 있는 반자동 도구를 목표로 했다.

문제 1. 같은 한국어 키가 문맥을 표현하지 못했다

가장 먼저 해결하고 싶었던 것은 같은 한국어 키가 여러 문맥에서 사용되는 문제였다. 한국어 문장을 그대로 i18n 키로 사용하면 처음에는 관리가 쉽다.

{
  "확인": "OK"
}

하지만 같은 확인이라도 화면에 따라 의미가 달라질 수 있다. 어떤 화면에서는 단순히 닫는 버튼일 수 있고, 다른 화면에서는 작업 완료를 의미할 수 있다. 이 구조에서는 확인이라는 키가 하나뿐이기 때문에 화면마다 다른 번역을 줄 수 없다. 기존 코드에도 이미 이런 문제를 피하기 위해 suffix가 붙은 키들이 있었다. 하지만 규칙이 명확하지 않아서, 나중에 봤을 때 왜 이 키가 나뉘었는지 알기 어려웠다. 그래서 키를 나누는 기준이 필요했다.

{한국어}_{context}
{namespace}:{한국어}
{한국어}-{ComponentName}
{한국어}-{screen}-{기능명}

i18next의 context 기능을 쓰는 방법도 있었고, namespace를 나누는 방법도 있었다. 하지만 기존 코드 구조와 맞지 않거나, 지금 당장 적용하기에는 비용이 컸다. 처음에는 컴포넌트 이름을 suffix로 붙이는 방식도 괜찮아 보였다.

확인-ConfirmModal
다시시도-ErrorModal

개발자 입장에서는 작성하기 쉽지만, 시트와 맞춰보면 애매한 부분이 있었다. 번역 시트는 컴포넌트가 아니라 화면 단위로 정리되어 있었다. 같은 컴포넌트가 여러 화면에서 재사용될 수도 있고, 컴포넌트 이름만으로는 번역 문맥을 충분히 설명하기 어려웠다.
이 고민을 정리해서 팀원에게 컨벤션 논의를 요청했고, 최종적으로는 화면과 기능명을 함께 붙이는 방식으로 정했다.

{한국어}-{screen}-{기능명}

예를 들면 이런 형태다.

확인-설정-저장버튼
확인-알림-읽음처리

조금 길어지긴 하지만, 시트의 screen 값과 연결하기 쉽고 나중에 봤을 때 어떤 화면의 어떤 기능에서 쓰는 문구인지 추적하기 쉽다고 판단했다.

문제 2. 시트와 JSON을 사람 눈으로 비교하기 어려웠다

문맥별 키 분리를 하려면, 먼저 현재 시트와 JSON이 어떤 상태인지 확인할 수 있어야 했다. 번역의 기준은 Google Sheet였지만, 실제 서비스에서 사용하는 값은 JSON 파일에 있었다. 두 값이 맞는지 확인하려면 결국 사람이 직접 비교해야 했다. 문제는 단순히 양이 많다는 것만은 아니었다. 같은 의미의 문장이라도 표현 방식이 다를 수 있었다. 예를 들어 시트에는 아래와 같은 값이 있다고 하자.

첫 번째 줄입니다.
두 번째 줄입니다.

JSON에는 같은 문장이 이런 형태로 들어 있을 수 있다. 

{
  "안내 문구": "첫 번째 줄입니다.<1/>두 번째 줄입니다."
}

화면에 표시되는 내용은 같지만, 문자열 기준으로는 다른 값처럼 보인다. 그래서 단순 비교만으로는 실제 문제가 아닌 항목까지 불일치로 잡혔고, 이를 줄이는 것이 먼저 필요했다. 처음에는 시트의 번역값과 JSON의 번역값을 그대로 비교했다. 예상대로 실제 문제가 아닌 값들이 불일치로 많이 잡혔다. 그래서 비교 전에 문자열을 정규화했다.

function stripTags(s) {
  return String(s || '')
    .replace(/<[^>]*>/g, '')
    .replace(/\s+/g, '');
}

이 함수는 HTML이나 i18next 태그를 제거하고, 줄바꿈을 포함한 공백도 제거한다. 이 도구의 목적은 코드 포맷을 검사하는 것이 아니라, 시트의 번역 내용과 JSON의 번역 내용이 같은지를 확인하는 것이었다. 그래서 태그와 공백 차이는 비교에서 제외했다.

단순 불일치 목록으로는 부족했다

처음에는 불일치 항목을 하나의 목록으로 보여줬다. 그런데 직접 확인해 보니 불일치에도 종류가 있었다. 어떤 값은 JSON 값만 수정하면 끝났다. 반면 어떤 값은 같은 한국어가 여러 곳에서 사용되고 있어서, 단순히 값을 수정하면 다른 화면에 영향을 줄 수 있었다. 그래서 리포트를 카테고리별로 나누었다.

- 키 분리가 필요한 값
- 시트에는 있지만 JSON에는 없는 값
- 값이 다른 값 / 사용 위치 1개
- 값이 다른 값 / 사용 위치 여러 개
- 시트에서 여러 행으로 나뉘어 있을 가능성이 있는 값

이렇게 나누니 어떤 유형의 문제인지 먼저 보고 대응할 수 있었다. 특히 같은 한국어가 여러 위치에서 사용되는 경우는 따로 봐야 했다. 이 경우에는 번역값만 수정하는 것이 아니라, 키 자체를 화면이나 기능 단위로 나누는 작업이 필요했기 때문이다.

check, plan, apply로 단계를 나눴다.

도구는 크게 세 단계로 나누었다.

pnpm i18n:check
pnpm i18n:plan
pnpm i18n:apply

각 명령어의 역할은 다음과 같았다.

check: 시트와 JSON의 차이를 확인한다.
plan: 키 분리가 필요한 항목의 후보를 만든다.
apply: 사람이 확정한 매핑만 코드와 JSON에 적용한다.

처음부터 하나의 명령어로 모든 것을 처리할 수도 있었다. 하지만 그렇게 하면 사람이 판단해야 하는 부분까지 도구가 추측하게 된다.
그래서 도구가 할 수 있는 일은 자동화하고, 문맥 판단이 필요한 부분은 사람이 결정하도록 남겨두었다.

i18n:check

i18n:check는 Google Sheet와 JSON 파일을 비교하는 명령어다. Google Sheet의 CSV 데이터를 가져와서 언어별 JSON과 비교한다. 비교 과정에서는 태그와 공백을 정규화하고, 결과를 유형별로 나누어 리포트한다. 시트 구조가 업데이트되면서 새로 생긴 차이도 있었다. 기존에는 개발팀에서 사용하는 JSON 키와 시트의 문구 행이 어느 정도 맞춰져 있었는데, 시트가 개편되면서 화면상 줄이 나뉘는 문구가 시트에서도 여러 행으로 분리되기 시작했다. 개발 코드에서는 여전히 하나의 t() 키로 묶어 쓰고 있는데, 시트에서는 여러 행으로 나뉘어 있는 경우가 생긴 것이다. 그래서 단순 비교만 하면 JSON에는 있는데 시트에는 없는 값처럼 잡혔다. 이 케이스를 줄이기 위해 같은 screen/property 그룹 안에서 연속된 행을 이어 붙여 비교하는 로직을 추가했다.

for (let start = 0; start < rows.length; start++) {
  let acc = '';

  for (let len = 1; len <= MERGE_WINDOW_MAX && start + len <= rows.length; len++) {
    acc += normalizeForMatch(rows[start + len - 1].ko);

    if (len === 1) continue;
    if (acc.length > targetNorm.length) break;

    if (acc === targetNorm) {
      candidates.push({
        window: rows.slice(start, start + len),
      });
      break;
    }
  }
}

다만 이 방식도 모든 케이스에 그대로 적용하기는 어려웠다. 짧은 문구는 여러 곳에서 후보로 잡혔고, 후보가 많아지면 리포트가 오히려 시끄러워졌다. 그래서 너무 짧은 문구는 병합 후보에서 제외하고, 운영해보니 볼 필요가 적은 섹션은 제거했다. 리포트는 많이 보여주는 것보다 확인할 항목만 남기는 쪽이 더 유용했다.

i18n:plan

i18n:plan은 키 분리가 필요한 항목을 찾아서 매핑 초안을 만드는 명령어다.
흐름은 이렇다.

1. 시트에서 같은 한국어지만 번역값이 여러 개인 항목을 찾는다.
2. 코드에서 해당 한국어 키가 사용된 위치를 찾는다.
3. 사용 위치와 screen 후보를 CSV로 출력한다.
4. 사람이 기능명을 채우고 action을 apply로 바꾼다.

다만 도구가 최종 키 이름까지 결정하지는 않았다. 사용 위치와 screen 후보만 제공하고, 어떤 기능명으로 나눌지는 사람이 결정하도록 했다. 그리고 매핑 파일 형식은 CSV로 만들었다. UTF-8 BOM을 붙이고, VSCode에서 CSV를 표처럼 편집할 수 있는 확장 도구를 사용하는 방식으로 정리했다.

i18n:apply

i18n:apply는 사람이 편집한 CSV를 기준으로 실제 코드와 JSON을 변경하는 명령어다. CSV에서 action=apply로 표시한 행만 처리한다. 예를 들어 이런 매핑이 있다면, 

ko,screen,function_name,action
확인,설정,저장버튼,apply

기존 코드는

t('확인')

에서

t('확인-설정-저장버튼')

로 변경된다.

새로 만든 번역값에는 검수 마커를 붙였다.

키를 나누면 새로운 키가 생긴다. 문제는 새 키의 일본어와 영어 번역값을 처음부터 정확히 알 수 없다는 점이다. 대부분은 기존 키의 번역값을 복제해서 시작하게 된다. 

{
  "확인": "OK",
  "확인-설정-저장버튼": "OK",
  "확인-알림-읽음처리": "OK"
}

하지만 실제로는 두 새 키가 서로 다른 번역을 가져야 할 수도 있다. 기존 값을 그대로 복사하면 빌드는 통과하지만, 잘못된 번역이 검수 없이 남을 수 있다. 이 문제를 막기 위해 자동으로 복제된 ja/en 값에는 검수 마커를 붙였다.

const REVIEW_MARK = ' 💥[확인필요]';

if (lang !== 'ko' && typeof baseVal === 'string') {
  newVal = baseVal.includes(REVIEW_MARK)
    ? baseVal
    : baseVal + REVIEW_MARK;
}

예를 들면 이런 식이다.

{
  "확인-알림-읽음처리": "OK 💥[확인필요]"
}

이 마커는 화면에 그대로 노출된다. 또한 💥[확인필요]로 검색하면 아직 확인하지 않은 키를 쉽게 찾을 수 있다. 번역 검수가 끝나면 사람이 정확한 번역값으로 바꾸면서 마커를 제거하도록 만들었다.

적용 후 달라진 점

이 작업 이후에는 번역 키를 확인하는 방식이 달라졌다. 이전에는 시트와 JSON을 직접 열고 사람이 비교해야 했다. 이제는 `i18n:check` 결과를 먼저 보고, 실제로 확인해야 할 항목을 좁힐 수 있게 되었다. 같은 한국어가 여러 문맥에서 사용되는 경우에도, 어떤 문구가 여러 화면이나 기능에서 쓰이고 있는지 먼저 파악할 수 있었다. 이후 기준 없이 suffix를 붙이는 대신, 화면과 기능명을 기준으로 키를 분리했다. 매핑은 CSV에서 확인하고 적용할 수 있도록 했다. 

{한국어}-{screen}-{기능명}

또한 키 분리가 필요한 경우에도 한 번에 코드와 JSON을 수정하는 것이 아니라, plan → 사람이 확인 → apply 흐름으로 적용할 수 있게 되었다.

회고

이번 작업에서 가장 많이 고민한 부분은 어디까지 자동화할지였다. 시트와 JSON을 비교하거나 코드에서 사용 위치를 찾는 일은 자동화할 수 있었다. 반면 어떤 문맥으로 키를 나눌지는 도구가 정확히 판단하기 어려웠다. 그래서 도구는 후보를 만들고, 최종 기능명은 사람이 채우는 방식으로 정리했다. 리포트도 가능한 많은 정보를 보여주기보다, 실제로 확인할 가치가 있는 항목만 남기는 방향이 더 유용했다. 태그와 공백 차이를 정규화하고, 운영상 가치가 낮은 섹션을 제거한 것도 이 때문이다. 결과적으로 이번 작업은 단순히 번역 JSON을 정리한 작업이라기보다, 번역을 확인하고 수정하는 흐름을 안정화한 작업에 가까웠다. 팀원분도 바로 좋다고 해주셔서, 혼자 고민했던 방향이 크게 틀리지 않았다는 생각이 들었다.