i18n 설정이 에이전트가 보는 코드가 아니라 개발자의 머릿속과 설정 파일에 있기 때문이에요. Cursor는 눈앞의 컨텍스트로 컴포넌트를 다시 생성하고, 가장 빨리 동작하는 건 JSX에 텍스트를 그대로 쓰는 방식이에요. 저장소는 아무 문제도 제기하지 않으니 리터럴이 그대로 배포돼요. globalize.now는 이 루프를 닫는 AI 기반 현지화 인프라예요. 새 문자열을 추출하고, 키를 생성하고, Git push마다 번역을 동기화해요.
아무도 알려주지 않는 실패 패턴이에요. i18n 설정은 오후 한나절이면 끝나요. 진짜 문제는 에이전트가 하루에 두 번씩 컴포넌트를 다시 쓰는 와중에 그 설정을 유지하는 일이에요.
i18n을 설정했는데 Cursor는 왜 계속 하드코딩된 문자열을 추가하나요?
세 가지 사실이 동시에 성립하고, 이게 합쳐져서 누수가 생겨요.
에이전트는 컨벤션이 아니라 파일을 봐요. Cursor에 설정 패널을 추가해 달라고 하면, 수정 중인 컴포넌트와 인접한 파일 한두 개 정도만 읽어요. 로케일 디렉터리, 네임스페이스 규칙, 사용자에게 보이는 모든 문자열은 번역 함수를 거쳐야 한다는 규칙은 직접 컨텍스트에 넣어주지 않으면 그 창 안에 없어요.
번역되지 않은 텍스트가 통계적 기본값이에요. 어떤 모델의 학습 데이터든 대부분의 React 코드는 문자열을 인라인으로 써요. 에이전트가 버튼 레이블의 다음 토큰을 고를 때, 빈도만 놓고 보면 Save changes가 t('settings.save')를 이겨요. 덜 흔한 패턴을 매번 고르게 하면서, 틀려도 피드백은 주지 않는 셈이에요.
깨지는 게 없어요. 이게 결정적이에요. 하드코딩된 문자열도 타입 검사를 통과하고, 빌드되고, 렌더링되고, 테스트도 통과해요. 독일 사용자가 영어 토스트를 보게 된다고 알려주는 빨간 표시는 파이프라인 어디에도 없어요. 누군가 로케일을 바꿔서 화면을 넘겨 보기 전까지는 보이지 않는 결함이에요.
누락된 import나 잘못된 prop 타입과 비교해 보세요. 이런 건 에이전트가 몇 초 안에 바로잡아요. 번역되지 않은 텍스트는 툴체인이 조용히 받아들이는 유일한 버그라서, 유일하게 계속 쌓이는 버그이기도 해요.
어떤 문자열이 가장 자주 새나요?
가장 늦게, 가장 덜 꼼꼼히 확인하고 추가한 것들이에요.
다국어로 시작한 AI 보조 코드베이스를 훑어보면, 남아 있는 영어는 예측 가능한 곳에 있어요.
- 에러·성공 토스트, 특히 상관없는 버그를 고치다가 추가한 것들
- 한 번 쓰고 다시 리뷰하지 않는 빈 상태 화면과 로딩 텍스트
- 스키마 안에서 인라인으로 생성되는 경우가 많은 폼 유효성 검사 메시지
- 접근성 속성:
aria-label,alt,title - 확인 다이얼로그와 되돌릴 수 없는 작업의 안내 문구
catch블록 안에 있는 모든 것
패턴은 일정해요. 주요 플로우는 직접 보니까 번역되고, 가장자리는 아무도 다른 로케일로 열어보지 않아서 하드코딩으로 남아요.
2차 문제도 있어요. 에이전트가 이미 번역된 코드 옆에 리터럴을 추가하면서 “친절하게” 네임스페이스 규칙과 맞지 않는 키를 만들어내기도 해요. 그러면 한 파일에는 errors.saveFailed, 다른 파일에는 settings_save_error처럼 되어서, 번역되지 않은 문자열과 흩어진 키 공간이 함께 생겨요. 아직 초기 단계라면 AI로 생성한 앱 현지화하기 가이드에서 첫 정리 방법을 다뤄요.
.cursor/rules나 AGENTS.md로 막을 수 있나요?
도움은 되니까 꼭 작성하세요. 다만 가이드일 뿐 강제는 아니에요.
지침 파일 레이어는 최근 표준화됐어요. AGENTS.md는 2025년에 벤더 중립적인 컨벤션으로 시작했고, 지금은 Linux Foundation 산하 Agentic AI Foundation이 관리해요. Cursor, Codex, Copilot, Gemini CLI, Aider, Windsurf, Zed가 기본으로 읽기 때문에, 저장소 루트에 파일 하나만 두면 팀이 쓰는 모든 에이전트에 닿아요. Cursor는 .cursor/rules/ 아래의 .mdc 파일로 범위를 지정한 프로젝트 규칙도 지원해요. frontmatter로 설명, 파일 globs, 항상 적용할지 여부를 제어하죠. 2026년 기준 실용적인 구성은 이식성을 위한 루트의 AGENTS.md에, 자동 첨부가 필요한 곳에 범위를 지정한 Cursor 규칙을 더하는 거예요.
쓸 만한 i18n 블록은 이렇게 생겼어요.
## Internationalization
- Never write user-facing text as a literal in JSX or in a string passed to a UI component.
- All user-facing text goes through the translation function from `next-intl`.
- Keys follow `feature.element.state` in lowerCamelCase, e.g. `settings.save.error`.
- Add the English value to `messages/en.json` only. Never hand-edit other locale files.
- This includes toasts, empty states, validation messages, `aria-label`, `alt` and `title`.
이것만으로도 누수 빈도는 눈에 띄게 줄어요. 하지만 0까지 내려가진 않아요. 규칙 파일은 컨텍스트 창 안에서 다른 모든 내용과 주의를 다투고, 긴 에이전트 세션에서는 지침에서 점점 벗어나기도 하니까요. 이 레이어는 빈도를 낮추는 장치로 보고, 보장으로 기대하지 마세요.
번역되지 않은 문자열이 빌드를 실패시키게 하려면 어떻게 하나요?
JSX의 리터럴을 에러로 처리하는 lint 규칙을 추가하고, CI에서 실행하세요.
표준적인 선택은 eslint-plugin-i18next의 no-literal-string 규칙이에요. 기본적으로 파일 안의 모든 리터럴이 아니라 JSX 마크업의 일반 텍스트만 검사해요. 그래서 오탐 투성이가 아니라 실제 코드베이스에서 쓸 만해요. 정규식 무시 패턴, 안전한 함수를 위한 callee 제외, 마크업 전용 모드를 지원해요.
시작용 설정이에요.
// eslint.config.js
import i18next from 'eslint-plugin-i18next';
export default [
{
files: ['**/*.{jsx,tsx}'],
plugins: { i18next },
rules: {
'i18next/no-literal-string': [
'error',
{
markupOnly: true,
ignoreAttribute: ['data-testid', 'className'],
ignore: ['^[0-9]+$', '^\\s*$'],
},
],
},
},
];
에디터에서만이 아니라 파이프라인에서도 실행하세요.
npx eslint . --max-warnings=0
이제 보이지 않던 결함에도 빨간 표시가 생겨요. 에이전트는 타입 에러에서 받던 것과 같은 피드백 루프를 번역되지 않은 문자열에도 받고, 다른 로케일의 사용자가 발견하기 전에 같은 세션에서 스스로 고칠 수 있어요. Cursor 프로젝트에 i18n을 처음부터 연결하는 전체 그림이 궁금하다면 15분 만에 끝내는 Cursor와 Next.js 가이드와 Cursor 연동 페이지를 보세요.
lint 규칙이 실패하게 만드는 것만으로는 왜 부족한가요?
빨간 빌드는 문자열이 있다는 사실만 알려줄 뿐, 번역해 주지는 않아요.
규칙이 동작하고 나면 누군가는 여전히 기존 네임스페이스에 맞는 키를 정하고, 영어 원문 값을 추가하고, 다른 로케일을 만들어야 해요. 하루에 여러 번 배포하는 1인 프로젝트에서는 이 작업이 계속 미뤄져요. 오래 미루다 보면 결국 정직한 해결책은 그 파일을 무시 목록에 넣는 것이 되고, 설정만 늘어난 채 처음 상태로 돌아가요.
해결된 문제가 반복되는 부채로 바뀌는 지점이 바로 이 틈이에요. 1, 2번 레이어는 문제가 생기는 빈도와 발견하는 속도를 바꿀 뿐, 실제 작업은 하지 않아요.
세 레이어 구성은 어떻게 생겼나요?
지침, 강제, 자동화예요. 각 레이어는 앞 레이어가 놓친 것을 잡아내요.
1단계, 지침. 저장소 루트의 AGENTS.md에 i18n 블록을 작성하고, 컴포넌트 디렉터리 globs를 담은 범위 지정 .cursor/rules/i18n.mdc도 추가하세요. 비용은 15분, 한 번이면 돼요. 효과는 처음부터 리터럴이 덜 작성된다는 거예요.
2단계, 강제. no-literal-string을 켜고 CI에서 실패하도록 설정하세요. 비용은 기존 코드베이스의 무시 패턴을 조정하는 데 드는 오후 한나절이에요. 효과는 어떤 리터럴도 모르는 사이에 메인 브랜치로 들어가지 못하고, 에이전트가 스스로 고칠 수 있다는 거예요.
세 번째 레이어, 자동화. 추출, 키 생성, 번역이 사람 손 없이 이뤄지게 해요. globalize.now가 자리하는 레이어예요. i18n 런타임을 대체하지 않고 그 위에 올라가요. 문자열 렌더링은 계속 next-intl이나 i18next가 맡아요. globalize.now는 새로 생긴 하드코딩 텍스트를 감지하고, 프로젝트에 이미 있는 네임스페이스에 맞춰 키를 생성하고, 설정된 모든 로케일로 번역하고, Git 푸시마다 업데이트된 로케일 파일을 커밋해요. globalize.now에서 저장소를 연결하면 설정은 끝이고, 건너뛸 수동 단계가 없어요. 에이전트에 설치할 수도 있어요:
npx skills add globalize-now/globalize-skills
요금제는 월 €20부터 시작해요. Starter는 매월 €20 크레딧이 포함되고, 그 이후 사용량은 제공업체 원가에 마크업을 더한 금액으로 크레딧 잔액에서 차감돼요. 사용자 수, 언어 수, 프로젝트 수에 따른 요금은 없고, 가입하면 카드 없이 14일 후 만료되는 €5 체험 크레딧을 받아요. 엔지니어를 위한 자세한 내용은 개발자 페이지에, AI 도구로 개발하는 분들을 위한 간단한 안내는 vibe coder 페이지에 있어요.
세 레이어의 핵심은 어느 것도 수백 번의 에이전트 세션 동안 개발자의 꾸준함에 기대지 않는다는 거예요. 규칙 파일은 빈도를 낮추고, lint 규칙은 실패를 눈에 띄게 만들고, 동기화는 수정 비용을 없애요. 이 조합이 에이전트가 계속 코드를 다시 쓰는 동안에도 다국어 앱을 다국어로 유지해 줘요.
i18n 설정 자체는 약한 고리가 아니에요. 에이전트가 문자열을 쓰는 순간부터 그 문자열이 로케일 파일에 도달하기까지의 루프가 약한 고리예요. globalize.now는 push할 때마다 그 루프를 닫아요.
globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.
globalize.now 무료로 시작하기