사용자에게 보이는 모든 문자열을 저장소의 카탈로그 하나에 두고, 키로 참조하고, 리뷰를 거친 diff로만 바꾸면 UI 카피가 일관돼요. 로직에 이미 적용하고 있는 규율을 문구에도 똑같이 적용하는 거예요. 이 페이지의 나머지는 이 규율을 습관으로 만드는 방법이에요.

이 글은 실무 가이드예요. 배경이 되는 아키텍처와, 코드베이스가 제품 카피의 단일 진실 공급원(source of truth)이어야 하는 이유는 코드 네이티브 제품 카피에서 다뤄요. 이유가 궁금하다면 그 글을, 방법이 궁금하다면 계속 읽어 주세요.

UI 카피는 어디에 둬야 하나요?

소스 언어마다 카탈로그 파일 하나를, 저장소 안에서 해당 화면을 렌더링하는 코드 가까이에 두세요. 스프레드시트도, 디자인 파일도, 3월에는 맞았던 위키 페이지도 안 돼요. 화면에 무슨 문구가 있는지 알고 싶을 때 개발자, 리뷰어, 번역가, 코딩 에이전트가 모두 찾아보는 곳이 바로 카탈로그예요.

여기서 나오는 실무 규칙은 이래요.

  • 카탈로그 하나, 소스 로케일 하나. en.json(또는 .po, .ftl, .strings 등 i18n 라이브러리가 읽는 파일) 하나가 카피의 기준본이에요. 모노레포에 앱이 여러 개라면 앱마다 하나씩 두고, 공용 문자열은 양쪽이 import하는 공용 카탈로그에 두세요. 같은 메시지를 담을 수 있는 파일이 둘이 되는 상황만 피하면 돼요.
  • 컴포넌트 단위가 아니라 화면이나 기능 단위로 묶으세요. checkout.summary.total 같은 키가 SummaryCard.totalLabel보다 오래 가요. 컴포넌트는 이름이 바뀌고 쪼개지지만, 화면과 메시지는 그대로이기 때문이에요.
  • 키는 문구가 아니라 메시지 기준으로 지으세요. checkout.submit는 "주문하기"가 "바로 구매"로 바뀌어도 그대로 쓸 수 있어요. checkout.placeOrderButton는 그렇지 않고, 키와 텍스트가 어긋나면 나중에 리뷰어가 서로 다른 문자열이라고 착각하게 돼요.
  • 카탈로그는 그 문자열을 쓰는 코드와 같은 PR에 담으세요. 문자열은 한 PR에, 그 문자열을 쓰는 컴포넌트는 다른 PR에 넣으면 문자열이 누락되거나 잊히거나 중복돼요.

문자열이 아직 컴포넌트 안에 리터럴로 박혀 있다면 가장 먼저 카탈로그부터 만들어야 해요. 이걸 손으로 하면 그 자체가 하나의 프로젝트가 돼요. 그래서 뒤에서 다룰 저장소를 연결해 변환을 맡기는 방식이 필요해요.

리터럴을 검색하는 것보다 키로 참조하는 게 나은 이유가 뭔가요?

키는 문자열 하나로만 연결되지만, 리터럴은 개발자 수만큼 다양하게 입력될 수 있기 때문이에요. "Sign in", "Sign In", "Log in", "Login"은 검색 도구에게는 문자열 네 개이고, 사용자에게는 하나의 의도예요. 모든 컴포넌트가 t("auth.signIn")를 호출하면 어떤 문구가 맞는지는 한 곳에서 한 번만 정해지고, 그 답이 키를 쓰는 모든 곳에 적용돼요.

이를 유지하려면 두 가지 습관이 필요해요.

  • 추가하기 전에 재사용부터 하세요. 키를 만들기 전에 카탈로그에서 같은 메시지가 있는지 검색하세요. common.cancel가 이미 있는데 텍스트가 같은 dialog.cancelButton를 새로 만들면 무해한 중복이 아니라 불일치의 시작이에요. 둘 중 하나를 고치는 순간 두 키는 따로 놀기 시작해요.
  • 문자열을 이어 붙이지 마세요. t("cart.items") + " " + count는 카탈로그 어디에도 없는 텍스트를 만들어요. 라이브러리의 보간(interpolation)과 복수형 기능을 써서 문장 전체를 리뷰 가능한 하나의 단위로 만드세요.

흔히 나오는 예외 논리가 "이 문자열은 한 번만 쓰이니까 리터럴이어도 괜찮다"예요. 지금은 한 번만 쓰여요. 하지만 컴포넌트는 복사되고, 화면에는 비슷한 화면이 생기고, 리터럴도 같이 따라가다가 결국 달라져요.

PR에서 카피 변경은 어떻게 리뷰하나요?

카탈로그의 변경된 줄은 함수 시그니처가 바뀐 것과 똑같이 다루세요. 리뷰어가 읽고, 질문하고, 승인해야 하는 대상이에요. 이 습관이 일관성을 기억력 문제에서 리뷰 문제로 바꿔 줘요. 리뷰는 누군가 확실하게 주의를 기울이는 거의 유일한 순간이에요.

카탈로그 리뷰가 잘 돌아가려면 이런 조건이 필요해요.

  • 문구 변경은 diff에서 독립된 한 줄이어야 해요. 문자열이 카탈로그에 있을 때만 가능해요. 컴포넌트 안에서 바꾼 문구도 diff에 나오긴 하지만 로직 변경에 묻혀서 "그냥 텍스트"로 넘어가기 쉬워요.
  • 카탈로그 변경은 카피 담당자에게 보내세요. 카탈로그 경로에 CODEOWNERS 항목을 두면, 문구를 책임지는 사람이 변경 때마다 리뷰어로 지정돼요. 제품 담당자든, 콘텐츠 디자이너든, 문구에 가장 신경 쓰는 개발자든 상관없어요. PR의 나머지는 평소대로 리뷰하면 돼요.
  • 변경된 줄마다 세 가지를 물어보세요. 이 대상에 승인된 용어가 맞나요? 주변 문자열과 어조, 대소문자가 맞나요? 키 이름이 여전히 메시지를 설명하나요? 이 세 가지만 물어도 스타일 가이드가 막으려는 문제 대부분을 잡아낼 수 있어요.
  • 설명 없는 조용한 이름 변경은 거절하세요. auth.signIn를 "Sign in"에서 "Log in"으로 바꾸면서 아무 설명도 없는 PR은, 마침 그 파일을 수정하던 사람이 내린 카피 결정이에요. PR 설명에 이유를 한 줄 적게 하거나, 아니면 되돌려야 해요.

이렇게 막으려는 문제에는 이름이 있어요. 카피 드리프트는 사용자에게 보이는 텍스트가 여러 화면과 시간에 걸쳐 승인된 원본에서 벗어나는 현상이고, 기준이 될 단일 진실 공급원 자체가 없을 때 생겨요. 원인은 카피 드리프트란 무엇인가에서 다루고, diff에서 하는 카탈로그 리뷰는 그 원인 대부분을 막는 방법이에요.

새로운 하드코딩된 문자열이 들어오는 걸 어떻게 막나요?

새 리터럴이 빌드를 실패시키게 만드세요. 규칙과 리뷰는 사람이 신경 써서 찾아보는 것만 잡아내요. 나머지는 린트 규칙이 모든 PR에서, 아무도 기억하지 않아도 잡아내요.

설정은 간단해요.

  • no-literal-string 규칙을 켜세요. eslint-plugin-i18next에 JavaScript와 TypeScript 프로젝트용 규칙이 있어요. 적용 범위는 JSX 텍스트와 입력 힌트, title, aria-label, alt 같은 사용자 대면 속성으로 한정하고, 테스트 파일과 Storybook 스토리는 예외로 두세요. 그래야 규칙의 신뢰도가 유지돼요.
  • 머지가 일어나는 곳에서 실행하세요. pre-commit 훅은 편하지만 진짜 효력이 있는 건 CI 단계예요. 작성자의 에디터 설정과 상관없이 PR마다 실행되기 때문이에요.
  • 미사용 키와 누락된 키를 확인하는 검사를 추가하세요. 대부분의 i18n 라이브러리에는 코드에서 참조하지만 카탈로그에 없는 키와, 카탈로그에는 있지만 어디서도 참조하지 않는 키를 찾아 주는 도구가 있어요. 이것도 CI에서 돌리세요. 낡은 문구는 미사용 키에 숨어 있어요.
  • 처음엔 엄격하게 시작하고, 예외는 주석으로 허용하세요. components/ 폴더 전체에서 꺼 둔 규칙은 규칙이 아니에요. 한 줄만 이유와 함께 꺼 둔 규칙은 문서가 돼요.

AI 코딩 도구로 만드는 팀은 이 문제를 더 심하게 겪어요. 도구가 로컬 컨텍스트만 보고 컴포넌트를 다시 생성하면서 리터럴을 도로 끌고 오기 때문이에요. Cursor AI가 하드코딩된 문자열을 계속 추가하는 이유에서 규칙 파일, 린터, CI로 이루어진 3단계 구성을 포함해 이 린트 규칙을 자세히 다뤄요.

개발자용 카피 스타일 가이드에는 무엇이 들어가야 하나요?

한 화면에 들어올 만큼 짧은 파일을 저장소에 두고, 톤을 정하고, 용어를 고정하고, 문자열을 어디에 두는지 적으세요. 긴 스타일 가이드는 위키에 올라가서 한 번 읽히고 끝나요. 짧은 가이드는 코드 옆에 있고, 문자열을 추가할 때마다 사람과 도구가 읽어요.

제대로 동작하는 COPY.md(또는 기존 기여 가이드의 한 섹션)에는 이런 내용이 들어가요.

  1. 톤은 세 문장으로. 제품이 누구처럼 말하는지, 얼마나 격식을 차리는지, "당신"이라고 하는지 "사용자"라고 하는지를 적어요. 대부분의 논쟁은 이 정도면 정리돼요.
  2. 절대 달라지면 안 되는 용어. 기능마다 쓰는 제품 용어, 핵심 동작의 동사("저장"인가 "업데이트"인가? "삭제"인가 "제거"인가?), 쓰지 않기로 한 단어를 적어요.
  3. 대소문자와 문장부호 규칙. 버튼과 제목에 문장형 대소문자를 쓸지 제목형 대소문자를 쓸지, 툴팁에 마침표를 찍을지, 숫자와 날짜를 어떻게 표기할지를 정해요.
  4. 문자열을 어디에 두고 키를 어떻게 짓는지. 카탈로그 경로, 그룹화 규칙, 키 이름 규칙, 그리고 "추가하기 전에 검색하기"를 적어요.
  5. 확신이 없을 때 할 일. 누구에게 물어볼지, 그동안 어떤 키를 재사용할지를 적어요.

저장소에 두세요. 그래야 규칙 파일이 이 가이드를 가리키고, 리뷰어가 코멘트에서 링크하고, 코딩 에이전트가 레이블을 쓰기 전에 읽을 수 있어요.

AI 코딩 에이전트가 일관성을 깨뜨리지 않게 하려면 어떻게 하나요?

에이전트가 읽을 단일 진실 공급원을 주고, 읽지 않았을 때 잡아내는 게이트를 두세요. 폼을 생성하는 에이전트는 한 화면에는 "Submit"을, 다음 화면에는 "Send"를 아무렇지 않게 써요. 각각의 자리에서 가장 그럴듯한 단어였기 때문이에요. 부주의해서가 아니라, 맞춰야 할 기준이 없어서 그래요.

대부분은 두 가지로 해결돼요. 첫째, 규칙 파일(AGENTS.md, .cursor/rules, CLAUDE.md 중 도구가 읽는 것)에 이렇게 적으세요. 사용자에게 보이는 텍스트는 카탈로그에 넣고, 기존 키를 재사용하고, 레이블을 쓰기 전에 COPY.md를 읽을 것. 둘째, 앞 섹션의 린트 규칙이에요. 규칙 파일은 추측을 줄여 주고, 린트 규칙은 빠져나간 추측을 잡아내요.

에이전트에 관해서는 여기까지가 이 페이지의 전부예요. 에이전트가 이미 있던 문자열을 마음대로 고쳐 쓰는 문제, 그리고 그 수정이 조용히 넘어가지 않고 눈에 보이게 만드는 방법은 별도의 주제예요. AI 코딩 에이전트가 UI 카피를 덮어쓰지 못하게 하는 방법을 참고하세요.

현지화는 어디에 들어가나요?

일관성과 현지화는 합의된 원본이라는 같은 기반 위에 서 있어요. 그래서 하나를 만들어 주는 카탈로그가 다른 하나도 만들어 줘요. 세 가지 표현 중 어느 것이 승인된 표현인지 말하지 못하는 팀은 그중 어느 것도 제대로 번역할 수 없어요. 원본을 바로잡으면 번역은 별도의 진실을 가진 독립 프로젝트가 아니라 카탈로그에서 파생된 산출물이 돼요.

실제로는 일관성을 위해 만든 카탈로그가 이미 번역가나 번역 도구가 작업하는 파일이 된다는 뜻이에요. 키마다 모든 대상 언어의 대응 문자열이 붙고, 같은 키 이름이 그대로 쓰이고, 소스 카탈로그의 문구 변경은 번역이 따라가야 할 변경으로 눈에 보여요. 번역이 원본을 따라가지 못하고 뒤처지면 번역 파일이 동기화되지 않는 이유에서 설명하는 부류의 문제가 생겨요. 해법도 똑같은 규율이에요. 카탈로그 하나, 키, diff로 보는 변경이에요.

globalize.now의 역할

globalize.now는 현지화가 내장된 코드 네이티브 카피 관리 시스템이고, 이 페이지에 나오는 모든 관행은 globalize.now가 저장소에 대해 전제하는 것들이에요. 앱에서 GitHub나 GitLab 저장소를 연결하면 스캔이 현재 상태를 파악해요. 문자열이 컴포넌트 안에 리터럴로 있다면 한 번의 변환으로 키 뒤로 옮겨 카탈로그에 담고, i18n 설정이 없으면 함께 추가해요. next-intl, react-i18next, i18next, Lingui를 이미 쓰고 있다면 그대로 맞춰서 동작해요. 결과는 별도 브랜치의 PR로 도착하기 때문에 첫 카탈로그도 위에서 설명한 리뷰를 그대로 거쳐요. 그 뒤로는 새로 추가한 소스 문자열을 푸시 작업이 번역하고, 결과를 PR로 열어 줘요. 저장소가 계속 단일 진실 공급원으로 남아요.

우리는 마케팅 사이트, 랜딩 페이지, 제품 전반에서 하나의 원본으로 같은 원칙을 지켜 나가는 방향으로 만들고 있어요. 사용자가 어디서 만나든 기능이 똑같이 설명되도록 하기 위해서예요. 아직 그 방향으로 나아가는 중이고, 오늘 구매할 수 있는 기능은 아니에요. 요금은 요금 페이지에서 확인하세요.

이번 주에 바로 도입할 수 있는 체크리스트

  1. 소스 언어마다 카탈로그를 저장소에 하나씩 만들고, 키 이름 규칙을 정하세요.
  2. 가장 자주 손대는 화면의 문자열부터 카탈로그로 옮기고, 키로 참조하세요.
  3. 사용자에게 보이는 텍스트로 범위를 한정한 no-literal-string 린트 규칙을 켜고 CI에서 실행하세요.
  4. 카탈로그 경로에 CODEOWNERS 항목을 추가하세요.
  5. COPY.md를 작성하세요. 톤, 고정 용어, 대소문자 규칙, 문자열을 두는 위치를 한 화면에 담으면 돼요.
  6. 에이전트 규칙 파일이 카탈로그와 COPY.md를 가리키게 하세요.
  7. PR 설명에 이유가 없는 문구 변경은 리뷰에서 거절하세요.

두 번째 단계가 한 달짜리 작업처럼 보인다면 저장소를 연결하고, 제안된 계획을 읽고, 열린 PR을 리뷰해 보세요.

globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.

globalize.now 무료로 시작하기