제품 문구는 단일 소스로 먼저 모아야 현지화 준비가 끝나요. 컴포넌트에 리터럴로 흩어진 문구는 다시 써도 현지화 가능해지지 않아요. 번역할 합의된 원문이 없기 때문이에요. 문구 다듬기, 용어집, 스타일 가이드도 모두 중요하지만, 문자열이 한 카탈로그에 모인 뒤에야 효과가 있어요. 이 글은 실제로 효과가 있는 순서를 정리했어요.
이 주제의 조언 대부분은 두 번째 단계부터 시작해요. 쉬운 말로 쓰고, 관용구를 피하고, 번역가에게 맥락을 주라는 조언이에요. 모두 맞는 말이지만, 같은 메시지가 컴포넌트마다 조금씩 다른 다섯 가지 형태로 존재하는 동안에는 하나도 실행할 수 없어요. 개념 배경과, 코드베이스가 제품 문구의 단일 소스여야 하는 이유는 코드 네이티브 제품 문구에서 다뤄요. 이 글은 실무 작업 순서를 다뤄요.
현지화 준비란 무슨 뜻인가요?
번역가나 번역 도구가 추측하지 않고도 문구를 충실하게 번역할 수 있는 상태를 뜻해요. 조건은 세 가지예요. 모든 문자열이 합의된 단 한 곳에 있고, 각 문자열이 하나의 명확한 내용만 전달하고, 번역하는 사람이 그 문자열이 어디서 어떻게 쓰이는지 알 수 있어야 해요.
세 가지를 나중에 보완하기 쉬운 정도는 서로 달라요. 문구는 문자열 하나씩 개선할 수 있고, 맥락은 노트로 덧붙일 수 있어요. 하지만 “합의된 단 한 곳”은 구조의 문제예요. 이게 없으면 나머지 둘도 기댈 안정적인 기반이 없어요. 쌍둥이 문자열이 다른 파일에 있으면 개선할 수 없고, 주소가 하나로 정해지지 않은 메시지에는 주석을 달 수 없어요.
원문이 번역 품질의 한계를 정하는 이유는 무엇인가요?
번역은 파생 작업이고, 파생 작업은 원본의 모든 결함을 물려받기 때문이에요. 번역은 원문의 모호함을 모든 대상 언어로 옮기고, 불일치도 함께 옮겨요. 원문이 한 화면에서는 “Sign in”, 다른 화면에서는 “Log in”, 또 다른 화면에서는 “Login”이라고 하면, 모든 언어에서 용어가 세 개가 되고 각각 따로 번역돼요. 어느 쪽이 의도한 표현인지 가릴 방법도 없어요.
그래서 번역문을 다듬는 흔한 해결책은 엉뚱한 쪽을 손보는 셈이에요. 언어를 추가할 때마다 고치지 않은 원문의 비용이 언어 수만큼 불어나요. 원문을 한 번 고치면 아직 추가하지 않은 언어까지 모두 해결돼요.
이 근본 문제에는 이름이 있어요. 문구 드리프트(copy drift)는 사용자에게 보이는 텍스트가 단일 소스 없이 화면마다, 시간이 지날수록 승인된 원문에서 벌어지는 현상이에요. 원인은 문구 드리프트란 무엇인가에서 다뤄요. 현지화에서 비용이 커지는 이유는 드리프트가 모든 언어로 복사되기 때문이에요.
흩어진 문구는 왜 현지화 가능한 상태로 만들 수 없나요?
넘겨줄 대상이 없기 때문이에요. 컴포넌트 안의 리터럴은 번역 단계가 집어 갈 수 있는 단위가 아니에요. 마크업과 로직이 섞여 있고, 조각을 이어 붙여 만든 문장일 수도 있고, 같은 문장이 아무도 의도하지 않은 작은 차이를 두고 여러 파일에 있을 수도 있어요.
리터럴을 제자리에서 다시 써도 이 문제는 바뀌지 않아요. 하나하나는 더 명확해져도 카탈로그가 없고, 제품이 무슨 말을 하는지 합의된 목록도 없고, 전부 찾았는지 확인할 방법도 없어요. 결과적으로 같은 흩어진 자리에 조금 더 깔끔한 텍스트가 남을 뿐이에요.
그래서 첫 단계는 편집 작업이 아니라 수집 작업이에요. 사용자에게 보이는 모든 문자열을 저장소의 카탈로그 하나, 원본 언어 하나에 모으고, 컴포넌트에서는 키로 참조하게 하세요. 문구는 바꾸지 마세요. 이 단계의 목적은 서로 모순되는 부분까지 포함해 제품이 지금 무슨 말을 하는지 파악하는 거예요.
문자열은 어떻게 모으나요?
먼저 카탈로그로 옮기고, 개선은 그다음에 하세요. 이 순서에는 두 가지 이유가 있어요. 옮기면서 문구까지 고치면 무엇이 바뀌었는지 리뷰어도 본인도 알 수 없어요. 그리고 모든 문자열이 한 파일에 모이면 중복과 거의 같은 문구가 더 이상 숨지 못해요. 서로 나란히 놓이니까 정리 작업이 파일 하나를 읽는 일로 줄어요.
실무에서는 이렇게 해요.
- 원본 언어마다 카탈로그를 저장소에 하나씩 두세요. 사람과 도구가 모두 읽을 수 있는 기준 문서예요. 구조를 잡고 키 이름을 짓는 방법은 코드베이스 전체에서 UI 문구 일관성 유지하는 방법에서 다뤄요. 같은 카탈로그이므로 그 글이 구조 레퍼런스이고, 여기서는 반복하지 않아요.
- 리터럴을 키 참조로 바꾸세요. 버튼 레이블, 오류 메시지, 빈 상태, 툴팁, 접근성 텍스트까지 사용자가 읽을 수 있는 모든 문자열이 대상이에요. 이 중 접근성 텍스트와 툴팁이 가장 자주 빠져요.
- 문장은 온전하게 유지하세요. 조각을 이어 붙여 만든 메시지라면 변수가 있는 하나의 항목으로 바꿔서, 번역가가 보는 단위와 사용자가 읽는 단위가 같게 하세요. 언어마다 어순이 달라서, 코드에서 조립한 문장은 어순에 맞게 바꿀 수 없어요.
- 아직 문구를 고치지 마세요. 참으세요. 어색한 문구는 분명 눈에 띄겠지만, 메모만 해 두고 넘어가세요.
이 목록이 큰 코드베이스에서 한 달은 걸릴 꼼꼼한 작업처럼 보인다면, 그게 이 단계의 솔직한 비용이에요. 대부분의 팀이 여기서 멈추는 이유이기도 해요.
문자열이 한 카탈로그에 모이면 그다음에는 무엇을 하나요?
이제야 익숙한 조언들이 적용할 대상을 갖게 돼요. 카탈로그가 하나면 아래 작업은 모두 여기저기 뒤지는 일이 아니라 한 번의 패스로 끝나요.
- 중복과 유사 문구를 정리하세요. 메시지마다 승인된 문구를 하나 고르고, 모든 사용처가 그걸 가리키게 하세요.
- 절대 달라지면 안 되는 용어를 고정하세요. 기능 이름, 핵심 동작에 쓰는 동사, 쓰지 않기로 한 단어 등이에요. 한 번만 적어 두세요. 이게 용어집이고, 길지 않아요.
- 쉽게 쓰세요. 능동태로 쓰고, 관용구를 피하고, 한 언어의 말장난에 기대는 농담은 넣지 마세요. 오해할 수 있는 약어는 풀어서 쓰고, 문자열 하나에는 한 가지만 담으세요.
- 번역가에게 맥락을 주세요. 문자열이 어디에 나타나는지, 변수가 무엇을 가리키는지 노트로 남기세요. “Post”나 “Order”처럼 짧은 문자열이 대표적인 함정이에요. 명사인지 동사인지에 따라 대상 언어에서 다른 단어가 필요할 수 있어요.
- 길이 변화를 고려하세요. 번역문은 원문보다 길어지는 경우가 많아요. 레이블이 길어져도 깨지지 않는 레이아웃으로 설계하세요. 길이는 미리 계산해 둘 수치가 아니라 설계 제약이에요.
모든 작업이 카탈로그 한 곳에서 이뤄지니까 각 단계가 빨리 끝나요. 카탈로그가 없으면 같은 다섯 단계가 코드베이스 곳곳을 뒤지는 보물찾기 다섯 번이 되고, 언제 끝났는지도 알 수 없어요.
번역 업체나 도구를 고르기 전에 무엇을 정해 두어야 하나요?
원문과 검토 경로. 업체나 도구는 받은 것을 그대로 번역해요. 깨끗한 카탈로그와 짧은 용어집을 주면 좋은 결과를 낼 수 있어요. 흩어진 리터럴을 주면 불일치까지 번역하느라 비용을 쓰고, 언어마다 바로잡느라 또 비용을 쓰게 돼요.
먼저 세 가지를 정하세요. 어떤 파일이 단일 소스인지, 문구 변경을 누가 승인하는지, 변경되거나 새로 생긴 문자열이 번역으로 어떻게 넘어가는지예요. 직접 넘길 수도, 스크립트로 넘길 수도, 번역이 함께 붙어 오는 PR로 넘길 수도 있어요. 마지막 방식이 번역이 원문보다 뒤처지는 문제를 막아 줘요. 이 문제는 번역 파일이 동기화되지 않는 이유에서 다뤄요.
문구가 이미 저장소에 있으면 무엇이 달라지나요?
현지화가 별도 프로젝트가 아니게 돼요. 카탈로그가 저장소에 있으면 새로 추가되거나 바뀐 문자열은 diff의 한 줄로 나타나요. 번역도 코드와 같은 PR 흐름으로 만들고 검토할 수 있고요. 스프레드시트를 내보내서 순서대로 돌아오길 바랄 필요가 없어요.
그래서 코드베이스에서는 문구 일관성을 유지하는 일과 현지화 준비를 유지하는 일이 같은 작업이에요. 둘 다 합의된 단일 소스에 의존해요. 한 번만 작업하면 둘 다 얻어요. AI 코딩 도구로 개발하는 팀은 이 문제를 더 일찍 겪어요. 카탈로그와 lint 규칙이 막아 주지 않으면 에이전트가 조용히 문구를 바꾸거나 리터럴을 다시 넣기 때문이에요. 이 경우는 AI 코딩 에이전트가 UI 문구를 멋대로 바꾸지 못하게 하는 방법에서 다뤄요.
globalize.now의 역할
globalize.now는 현지화가 내장된 코드 네이티브 문구 관리 시스템이고, 위의 단일 소스화 단계를 대신 처리해 줘요. 앱에서 GitHub 또는 GitLab 저장소를 연결하면 스캔이 현재 상태를 파악해요. 문자열이 컴포넌트 안의 리터럴이면 한 번의 변환으로 키 뒤로 옮겨 카탈로그에 담고, i18n 설정이 없으면 함께 추가해요. next-intl, react-i18next, i18next, Lingui 같은 라이브러리를 이미 쓰고 있으면 기존 구성을 그대로 활용해요. 결과는 별도 브랜치의 PR로 도착하니, 첫 카탈로그도 위에서 설명한 검토 절차를 그대로 거쳐요. 이후에 추가하는 새 원문 문자열은 푸시 작업이 번역해서 결과를 PR로 열어 줘요. 저장소가 유일한 단일 소스로 유지돼요. 이미 설정이 있을 때 스캔이 무엇을 찾는지는 기존 i18n 가이드에서 확인하세요.
마케팅 사이트, 랜딩 페이지, 제품 전반에서 하나의 소스로 같은 원칙을 지키는 방향으로 개발하고 있어요. 지금 쓸 수 있는 기능이 아니라 앞으로 가려는 방향이에요. 요금은 요금 페이지에서 확인하세요.
순서 요약
- 사용자에게 보이는 모든 문자열을 저장소의 카탈로그 하나에 모으세요. 문구는 바꾸지 마세요.
- 문장은 온전하게 유지하고, 모든 문자열을 키로 참조하세요.
- 중복을 제거하고 승인된 문구를 하나로 정하세요.
- 절대 달라지면 안 되는 용어의 짧은 용어집을 작성하세요.
- 쉬운 문장으로 다듬고, 번역가를 위한 맥락 노트를 추가하세요.
- 문구를 누가 승인하고, 변경된 문자열이 번역으로 어떻게 넘어가는지 정하세요.
- 그다음에야 번역 업체나 도구를 고르거나 바꾸세요.
첫 단계가 한 달 치 작업처럼 보인다면 저장소를 연결해서 globalize.now가 제안하는 계획을 읽고, 열어 주는 PR을 검토해 보세요.
globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.
globalize.now 무료로 시작하기