아래 i18n 섹션은 AGENTS.md에 붙여 넣어 쓰는 용도예요. 사용자에게 보이는 모든 문자열을 번역 함수로 처리하고, 기능별로 키를 붙이고, 문자열 조각을 이어 붙이지 않고, 삼항 연산자로 복수형을 흉내 내지 않고, 생성된 로케일 파일은 건드리지 않도록 코딩 에이전트에게 알려 주는 짧은 규칙 10가지예요. globalize.now는 AI 기반 현지화 인프라라서 에이전트가 작성한 i18n 코드를 많이 보는데, 거의 모든 문제가 같은 몇 가지 실수에서 나와요. 각 규칙은 그 실수 하나씩에 대응해요.
이 글의 후반부는 이 파일이 통하지 않는 지점을 다뤄요. 개발자가 가장 많이 쓰는 코드 작성 화면 두 곳은 이 파일을 아예 읽지 않고, 문구를 아무리 다듬어도 이 문제는 해결되지 않아요.
AGENTS.md의 i18n 섹션에는 무엇을 써야 할까요?
아래 블록이에요. 파일 경로 세 곳과 린트 명령만 프로젝트에 맞게 고치고 나머지는 그대로 두세요.
## Internationalization
- Every user-visible string goes through the translation function. That
includes JSX text, input hint text, `title`, `aria-label`, `alt`, toast and
error messages, empty states and the document `<title>`.
- The source locale is `en`. The catalog is `locales/en.json`. Add the key in
the same change that uses it.
- Keys are namespaced by feature: `checkout.summary.total`, not `total3`.
Search the catalog for an existing key before creating one.
- Never concatenate translated fragments. Use interpolation:
`t('cart.items', { count })`, not `t('cart.you_have') + count`.
- Plurals use the library's plural forms (`_one` / `_other` keys, or ICU
`{count, plural, ...}`). Never `count === 1 ? 'item' : 'items'`.
- Dates, numbers and currency go through `Intl.DateTimeFormat` and
`Intl.NumberFormat` with the active locale. Never a bare
`toLocaleString()`, never a currency symbol glued to a number.
- Do not hardcode the locale list, language names or text direction in
components. Read them from `i18n/config.ts`.
- Do not translate brand names, code identifiers, URLs or environment values.
- Do not edit locale files other than `en`. They are generated. If a
translation looks wrong, fix the source key or the glossary, not the file.
- Before finishing, run `npm run lint`. The `i18next/no-literal-string`
rule must pass.
규칙을 10개로 한 건 의도한 거예요. Cursor 규칙 문서는 자주 쓰는 패턴에 집중하고 스타일 가이드를 통째로 붙여 넣는 대신 린터를 쓰라고 안내해요. Claude Code의 가이드도 같아요. 검증할 수 있을 만큼 구체적으로 쓰고, 파일이 길어질수록 준수율이 떨어지니 짧게 유지하라고 해요. 항목이 마흔 개씩 되는 i18n 섹션은 대충 훑어보고 넘어가게 돼요.
“i18n을 사용하라”는 한 줄 대신 왜 이 10가지 규칙인가요?
에이전트는 <Button>Save changes</Button>를 쓰는 순간에도 이미 i18n을 하고 있다고 믿기 때문이에요. 모호한 지침은 에이전트 나름의 준수 기준으로 만족돼 버려요. 아래 규칙은 각각 구체적인 출력을 하나씩 지목해서 금지해요.
속성 안의 리터럴. 에이전트는 JSX 자식 요소를 번역해야 한다는 건 배우지만, 속성은 문구가 아니라 설정값처럼 보여서 aria-label="Close"와 alt="Company logo"를 일반 문자열로 써요. 속성 이름을 하나하나 적어 주면 이 빈틈이 막혀요. “전부 번역하라”는 일반적인 지시로는 안 막혀요.
문자열 이어 붙이기. t('greeting') + ' ' + name + '!'는 영어에서는 문제없이 렌더링되지만, 이름이 앞에 오거나 어형이 변하는 언어로는 번역할 수 없어요. 보간을 쓰면 번역가는 변수 하나가 들어간 문자열 하나만 다루면 돼요.
삼항 연산자 복수형. count === 1 ? 'item' : 'items'는 i18n을 세팅한 뒤에도 에이전트가 가장 자주 쓰는 코드인데, 복수형이 둘보다 많은 언어에서는 모두 틀려요. 규칙에서 이 패턴을 직접 지목하면 에이전트가 패턴을 보고 피할 수 있어요. 카탈로그에 ICU를 쓴다면 문법은 ICU MessageFormat이 무엇이고 AI가 만든 앱에서 어디서 깨지는지를 참고하세요.
생성된 로케일 파일. 이 규칙은 에이전트가 도움이 되려고 애쓰기 때문에 필요해요. 독일어 오타를 고쳐 달라고 하면 에이전트는 locales/de.json를 열어서 수정하는데, 다음 번역 작업이 소스에서 파일을 다시 생성하면 그 수정은 사라져요. 소스가 아닌 파일은 생성된 것이라고, 실제로 고칠 곳은 어디인지 알려 주면 이런 조용한 회귀를 막을 수 있어요.
같은 변경에서 en도 수정하기. 이 규칙이 없으면 에이전트는 t('checkout.summary.total')만 추가하고 넘어가요. 그러면 누가 알아차릴 때까지 키 이름이 그대로 화면에 표시돼요. 카탈로그 항목과 그 첫 사용처는 하나의 diff에 함께 들어가야 해요.
도구마다 이 파일을 실제로 어디서 읽나요?
에이전트에 따라 같은 내용을 넣는 위치가 달라요. 그 위치에 따라 규칙이 항상 컨텍스트에 들어가는지, 필요할 때만 로드되는지가 정해져요.
저장소 루트의 AGENTS.md가 공용 위치예요. 필수 필드가 없는 일반 Markdown 형식이고, Linux Foundation 산하 Agentic AI Foundation이 관리해요. Cursor, Codex, Copilot 코딩 에이전트를 비롯해 많은 도구가 읽어요. 스펙은 중첩 파일도 지원하고, 수정 중인 파일에 가장 가까운 파일이 우선해요.
Cursor는 중첩된 파일을 포함해 AGENTS.md를 직접 읽고, 범위를 지정할 수 있는 자체 형식도 있어요. UI 파일로 범위를 지정한 규칙은 일치하는 파일이 열릴 때까지 컨텍스트에 들어가지 않아요.
---
description: i18n rules for user-visible strings
globs: src/**/*.tsx, src/**/*.jsx
alwaysApply: false
---
(paste the Internationalization section here)
파일 확장자는 .mdc여야 하고 위치는 .cursor/rules/여야 해요. 그 폴더의 일반 .md는 frontmatter가 없어서 무시돼요.
VS Code의 GitHub Copilot은 선택지가 세 가지예요. .github/copilot-instructions.md는 모든 채팅 요청에 적용돼요. frontmatter에 applyTo: "**/*.tsx,**/*.jsx"를 지정한 .github/instructions/i18n.instructions.md 파일은 해당 파일이 생성되거나 수정될 때만 적용돼요. 저장소 루트의 AGENTS.md는 chat.useAgentsMdFile 설정이 켜져 있으면 Local 에이전트가 읽어요. 하위 폴더에 중첩된 AGENTS.md 파일은 별도의 실험적 설정인 chat.useNestedAgentsMdFiles 뒤에 있고, 이 설정은 기본적으로 꺼져 있어요. Copilot에서만 달라지는 동작은 GitHub Copilot으로 만든 앱에 i18n 추가하는 방법에서 다뤄요.
Claude Code는 CLAUDE.md를 읽어요. 그리고 v2.1.277부터는 작업 디렉터리 위쪽에 CLAUDE.md가 없는 프로젝트라면 루트의 AGENTS.md를 알아서 읽어요. 둘 다 둔다면 문서에서 안내하는 방식은 CLAUDE.md 맨 위에서 @AGENTS.md로 가져와서 파일이 한 번만 로드되게 하는 거예요. 범위 지정에는 frontmatter에 paths: 목록을 넣은 .claude/rules/i18n.md를 쓰면 돼요. Claude가 일치하는 파일을 읽을 때만 로드돼요. Claude Code 전체 워크플로는 Claude Code가 생성한 앱을 현지화하는 방법에 있어요.
여러 에이전트가 건드리는 저장소라면 이렇게 구성하는 게 현실적이에요. 팀에서 가장 많이 쓰는 에이전트용 범위 지정 파일에 규칙 10가지를 넣고, AGENTS.md에는 두 줄짜리 안내(“UI 문자열: .cursor/rules/i18n.mdc의 i18n 규칙을 확인하고 따를 것”)를 넣어요. 그러면 범위 지정을 지원하지 않는 에이전트도 지침을 받을 수 있어요.
AGENTS.md를 읽지 않는 코드 작성 화면은 어디인가요?
인라인 자동 완성이에요. 두 회사 모두 문서에 밝혀 둔 사실이고, 규칙 파일만으로는 충분하지 않은 이유이기도 해요.
Cursor 규칙 FAQ는 “규칙이 Cursor Tab이나 다른 AI 기능에 영향을 주나요?”라는 질문에 아니라고 분명히 답해요. 규칙은 Agent에 반영되고, 입력 중인 줄을 채워 주는 자동 완성인 Tab은 규칙을 보지 못해요. VS Code의 사용자 지정 지침 페이지에도 Copilot에 대해 같은 안내가 있어요. 에디터에서 입력하는 동안 나오는 인라인 제안에는 지침이 반영되지 않는다는 거예요.
그래서 개발자가 <p>No results found</p>를 입력하고 고스트 텍스트를 수락하는 바로 그 화면에는 규칙이 닿지 않아요. 채팅과 에이전트 모드는 문자열에 키를 붙이지만, 다른 생각을 하는 사이에 줄을 완성해 버린 자동 완성은 그러지 않아요. 평소처럼 일주일을 작업하면 지침 파일이 다루지 않는 그 경로로 리터럴이 계속 쌓여요. 그러면 규칙 파일을 꼼꼼히 써 둔 개발자는 에이전트가 규칙을 무시한다고 생각하게 돼요.
Claude Code에는 인라인 자동 완성이 없지만, 문서는 반대편에서 같은 점을 짚어요. CLAUDE.md 내용은 강제되는 설정이 아니라 컨텍스트이고, 모델의 판단과 상관없이 동작을 막으려면 훅(hook)을 써야 한다는 거예요. 여기 나온 모든 도구에 해당하는 올바른 관점이에요. 지침 파일은 확률을 바꿔 줄 뿐 강제하지는 않아요.
그럼 규칙을 실제로 강제하는 건 뭔가요?
CI의 린트 규칙이에요. 규칙 파일이 이미 에이전트에게 린트를 실행하라고 알려 주고 있다면 한 줄만 추가하면 돼요. eslint-plugin-i18next는 no-literal-string를 제공해요. 컴포넌트 디렉터리에 이 규칙을 켜 두면 JSX 안의 리터럴이 정중한 안내가 아니라 빌드 실패로 이어져요. 설정 방법, 규칙 옵션, 지침과 강제가 서로 다른 계층인 이유는 i18n 설정 후에도 Cursor가 하드코딩된 문자열을 계속 추가하는 이유에 정리돼 있어서 여기서는 반복하지 않을게요.
린트 계층에는 규칙 파일이 줄 수 없는 장점이 두 가지 있어요. 하나는 린트가 대화가 아니라 파일에 대해 실행되기 때문에 인라인 자동 완성이 만든 코드도 잡는다는 거예요. 다른 하나는 에이전트 자신의 루프가 수정 수단이 된다는 거예요. 위 블록의 마지막 규칙은 작업을 마치기 전에 린트를 실행하라고 에이전트에게 알려 주고, no-literal-string가 실패하는 걸 본 에이전트는 같은 세션에서 그 문자열에 직접 키를 붙여요.
Claude Code에서는 방금 작성한 파일에 린터를 실행하는 PreToolUse 또는 post-edit 훅이 문서가 가리키는 강제 수단이에요. 훅은 정해진 시점에 셸 명령으로 실행되고, 모델이 규칙을 따르기로 했는지와 상관없이 적용돼요.
그래도 빠져나온 문자열은 어떻게 되나요?
추출하고, 기존 네임스페이스에 맞춰 키를 붙이고, 번역해야 해요. 이 부분이 재프롬프트 대신 자동화할 가치가 있는 영역이에요. 빌드가 빨갛게 변하면 리터럴이 있다는 건 알 수 있어요. 하지만 그걸 키로 바꾸고, en에 추가하고, 나머지 모든 로케일에 반영하는 건 여전히 누군가의 몫이에요.
globalize.now는 바로 이 계층을 맡아요. 변환은 앱 안에서 한 번만 해요. 저장소를 연결하면 코드베이스가 한 번 변환되고, 카탈로그는 검토할 수 있는 풀 리퀘스트로 전달돼요. 그 뒤에는 새 카탈로그 단위가 들어올 때마다 푸시 작업이 번역해요. 그래서 화요일 PR에 추가한 키는 수요일 PR에 번역이 들어 있어요. 런타임 라이브러리, 카탈로그 형식, 위의 규칙 파일은 모두 여러분 것이에요. 설정 이후 Cursor, Claude Code, Codex, Copilot의 에이전트가 이 역할을 이어받는 방식은 개발자 레퍼런스에 있고, 가장 빠르게 따라 해 볼 수 있는 건 Cursor 연동이에요.
관련된 문제 두 가지는 각각 별도의 글이 있어요. 이미 키로 만든 문구를 에이전트가 다시 고쳐 쓰는 문제라면 AI 에이전트가 UI 문구를 마음대로 고쳐 쓰지 못하게 하는 방법을 보세요. 해법은 위 아홉 번째 규칙과 같은 소스 로케일 원칙이에요. 로케일은 있는데 계속 어긋난다면 번역 파일이 동기화에서 벗어나는 이유에서 그 뒤에 있는 라우팅 실패를 설명해요.
어디서부터 시작하면 될까요?
블록을 붙여 넣고, UI 디렉터리로 범위를 지정하고, 같은 날 오후에 CI에서 no-literal-string를 켜세요. 그다음 일주일 동안 린트 규칙이 무엇을 잡아내는지 지켜보세요. 규칙 파일이 혼자서 얼마나 해낼 수 있었는지 가늠하는 척도예요. AI로 만든 앱을 배포하면서 새어 나온 모든 문자열의 추출과 번역을 직접 관리하지 않고 맡기고 싶다면 vibe coder 페이지에서 개요를 볼 수 있고, 요금은 별도 페이지에 있어요.
globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.
globalize.now 무료로 시작하기