이 가이드에서는 AI가 생성한 앱을 국제화하고 현지화하는 방법을 설명해요. 키, 로케일 파일, 문자열 추출, 용어집, 그리고 UI가 빠르게 바뀌어도 유지되는 자동화까지 다뤄요. globalize.now는 AI 기반 현지화 인프라로, 푸시할 때마다 Git과 카탈로그를 맞춰줘요. 한 번만 설정해 두면 푸시마다 자동으로 동기화되고, 파일을 수동으로 주고받을 필요도 없어요. AI 중심 코드베이스가 i18n 계층을 건너뛰는 이유는 AI Code Broke Localization and Nobody Fixed It에서 확인하세요. 도구 세대별 업계 맥락은 3 Stages of Localization Development (And Why AI Changes Everything)에서 볼 수 있어요. 저장소가 아직 정돈되지 않았을 때 어떤 순서로 도구를 도입할지는 globalize.now vs Lokalise vs Crowdin에서, 실제 적용 과정은 How to Globalize Your App with globalize.now에서 다뤄요.
“AI가 생성한 앱을 현지화한다”는 건 정확히 무슨 뜻인가요?
**현지화(l10n)**는 사용자가 실제로 보는 결과예요. 로케일에 맞는 언어, 복수형, 날짜, 통화, 레이아웃을 말해요.
**국제화(i18n)**는 엔지니어가 먼저 하는 작업이에요. 사용자에게 보이는 텍스트를 참조할 수 있고, 반복해서 쓸 수 있고, 대규모로 번역해도 안전하게 만드는 일이에요.
“아직 현지화할 수 없다”는 걸림돌 대부분은 i18n 문제예요. 구조를 한 번만 제대로 잡으면 현지화는 고고학 프로젝트가 아니라 운영 문제로 바뀌어요.
도구를 고르기 전에 i18n 아키텍처 체크리스트에는 무엇이 있어야 하나요?
번역 관리 소프트웨어나 번역 업체를 고르기 전에 아래 구성 요소가 갖춰져 있는지 확인하세요. 없다면 이 순서대로 도입하세요:
- 런타임 i18n 라이브러리: 스택(React, Next.js, Rails 등)에 맞고, UI 문자열을 다루는 방식이 하나로 통일되어 있어야 해요.
- 안정적인 번역 키: 영어 문장을 ID로 쓰지 말고, 네임스페이스와 계층 구조를 가진 키를 사용하세요.
- 로케일 리소스 파일(JSON, PO, YAML): 저장소에 커밋하거나 CI에서 생성해요.
- ICU 방식의 복수형과 변수:
"{count} items"같은 동적 문구에서 번역가가 문법에 맞게 어순을 바꿀 수 있어요. - 문자열 추출 파이프라인: 새 UI가 카탈로그를 조용히 건너뛰지 않게 해요.
| 계층 | 담당 영역 | 흔한 실패 유형 |
|---|---|---|
| UI 코드 | t("…")만 호출 | 컴포넌트에 하드코딩된 영어 |
| 카탈로그 | 키, 설명, 최대 길이 | 중복 키, 누락된 문맥 |
| 로케일 | 언어별 메시지 | 손으로 고친 JSON이 원본과 어긋남 |
| 번역 관리 / MT | 사람의 작업 흐름, MT 엔진 | 잘못된 키나 누락된 문자열이 입력됨 |
개발 속도를 잃지 않고 문자열을 추출하려면 어떻게 해야 하나요?
AI가 생성한 저장소는 “저장”, “취소”, “자세히 보기” 같은 라벨을 수십 개 파일에 반복해서 써요. 추출 단계에서는 다음을 해야 해요:
- 사용자에게 보이는 리터럴을 찾아내세요. 컴포넌트, 라우트, 공용 UI 요소에서 찾되, 기술적인 문자열(CSS 클래스, 분석 ID, 사용자에게 노출되지 않는 URL)은 제외해요.
- 중복을 정리해서 참조를 가진 키 하나로 합치세요. 번역가는 같은 의미 단위를 한 번만 보게 돼요.
- 소스 로케일(보통 영어)을 새 키마다 기준 값으로 생성해요.
- 호출 지점을 다시 작성하세요. 팀에서 합의한 i18n API를 쓰도록 기계적으로 바꾸면 diff를 리뷰하기 쉬워요.
React 스타일 코드로 변경 전후를 간단히 보여 주면 이렇게 돼요:
<button>Submit order</button>
추출하고 키를 붙인 뒤에는 이렇게 돼요:
<button>{t("checkout.submit_order")}</button>
// locales/en.json
{
"checkout.submit_order": "Submit order"
}
언어를 늘리기 전에 용어집과 스타일 가이드가 왜 중요한가요?
기계 번역은 빠르지만, 기준이 없으면 화면마다 다른 제품처럼 들리기 쉬워요. 언어를 늘리기 전에 다음을 정리해 두세요:
- 번역하면 안 되는 브랜드 용어(제품명, 기능명).
- 오역 위험이 큰 단어(“contact”, “trial”, “billing”, “workspace”)의 권장 번역.
- 톤: 격식체인지 대화체인지, 2인칭을 쓸지 중립적으로 쓸지.
이 용어집을 번역 관리 도구나 MT 프로필에 연결하면 자동 번역 초안이 팀이 이미 내린 결정과 어긋나지 않아요.
번역 QA 루프의 중심에는 자동 검사를 어떻게 두어야 하나요?
키가 로케일 파일로 들어오고 나면, 요즘 방식의 루프는 이렇게 돌아가요. MT 초안 → 린터 검사(길이, 플레이스홀더, 금지 용어) → 영향이 큰 화면의 자동 회귀 검사 → 배포 → 측정. 자동화는 시간을 아껴 주고, 린터는 깨진 플레이스홀더가 배포되는 걸 막아 줘요.
CLI 스타일 도구를 쓰면 저장소에 남은 작업량을 바로 확인할 수 있어요. 예를 들면 이런 식이에요.
✔ Scanned 312 files
✔ Found 1,284 user-visible literals
✔ Proposed 920 translation keys (364 duplicates merged)
✔ Wrote locales/en.json
Next: sync translation-ready keys to your coordination tool or run an MT batch with glossary v1
현지화 리팩터링을 리뷰하기 쉽게 만드는 에이전트 프롬프트는 무엇인가요?
이 프롬프트는 테스트와 코드 리뷰가 갖춰진 저장소에서 작업한다고 가정해요. 믿고 확인할 수 있는 diff를 만들기 위한 것이지, 조용히 넓은 범위를 리팩터링하려는 게 아니에요.
리팩터링 전에 UI 문자열 목록은 어떻게 만드나요?
You are analyzing a TypeScript React codebase for localization readiness.
Task: List every pattern where user-visible English might appear (JSX text, string props that render to the DOM, template literals interpolated into UI, aria-label/title/placeholder, toasts, empty states). Exclude className values, internal IDs, and URLs that are not shown to users.
Output: a table with columns: file path, line range, example string, recommended next step (extract key / ignore / needs product decision).
최소한의 타입 지정 t() API는 어떻게 안전하게 도입하나요?
Add a minimal i18n helper used across the app: a typed t(key, vars?) function backed by JSON locale files in /locales. Do not translate yet; only wire English as the source locale.
Constraints:
- Keys use dot namespaces: "section.component.purpose"
- Support ICU-style pluralization for keys that need counts
- Add a dev-only warning when t() is called with a missing key
Show the file tree you created and example usage in two existing components.
리터럴을 네임스페이스 키로 기계적으로 추출하려면 어떻게 하나요?
Refactor the following files to replace user-visible string literals with t("…") keys.
Rules:
- Prefer stable semantic keys, not English sentences as keys
- Deduplicate identical UI strings to one key
- Keep string interpolation correct using ICU message patterns
- Do not change layout/styling except where required by the refactor
After edits, print a JSON object mapping each new key to its English source string for translators.
번역가가 믿고 쓸 수 있는 용어집 CSV는 어떻게 작성하나요?
From locales/en.json and the product marketing pages in this repo, propose a glossary CSV with columns: term_en, part_of_speech, definition_for_translators, do_not_translate (true/false), allowed_synonyms, notes_for_de.
Flag terms that are legally sensitive (pricing, trials, refunds) and terms that are ambiguous in software ("session", "organization", "member").
새로운 하드코딩 영어 문자열이 머지되는 걸 막는 CI 가드레일은 무엇인가요?
Add a CI script that fails if new user-visible English literals appear in JSX outside of tests/fixtures.
Implementation guidance:
- Use the repo's existing package manager and test runner
- Provide a small allowlist file for exceptions (brand strings, intentional English)
- Print actionable file/line references on failure
Include README notes for how engineers should add exceptions responsibly.
이 프롬프트들을 여전히 직접 붙여 넣어야 하나요?
점점 그럴 필요가 없어져요. 이 가이드를 처음 쓸 때는 프롬프트를 복사해서 에이전트에 붙여 넣는 게 루프를 돌리는 현실적인 방법이었어요. 그 후로 도구가 에이전트 안으로 들어왔어요. 이제 코딩 에이전트는 MCP 서버를 통해 현지화를 직접 호출할 수 있고, 추출, 키 생성, 번역 동기화는 프롬프트를 붙여 넣는 작업이 아니라 에이전트가 실행하는 도구 호출이 돼요. 설정 방법은 globalize.now MCP 소개에서, 이 변화가 아키텍처 관점에서 왜 중요한지는 현지화는 SDK가 아니라 에이전트 Skill이 되고 있어요에서 확인하세요.
위 프롬프트는 리뷰 체크리스트로도 쓸 수 있어요. 사람이 붙여 넣든 에이전트 Skill에 담겨 있든, 에이전트가 주도하는 i18n 리팩터링이 갖춰야 할 조건을 정리한 것이거든요. 자동화된 리팩터링은 모두 같은 기준으로 평가하세요. 리뷰 가능한 diff, 안정적인 키, ICU에 안전한 보간, 그리고 회귀를 막는 CI 가드레일이 기준이에요.
AI로 만든 제품을 현지화할 때 장기적으로 기억해야 할 제약은 무엇인가요?
현지화는 스프린트 한 번으로 끝나는 일이 아니에요. 미래의 나와 맺는 약속이죠. 키, 카탈로그, 자동화에 한 번 투자해 두면 AI가 생성하는 새 화면을 전 세계에 배포하는 비용이 계속 줄어들어요.
globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.
globalize.now 무료로 시작하기