AI 현지화 에이전트

AI 에이전트를 ai-l10n MCP 서버에 연결하면 전문가용 현지화 도구로 변모합니다. 원시 국제화(i18n) 파일 콘텐츠를 컨텍스트에 붙여넣는 대신, 에이전트가 l10n.dev를 전용 번역 엔진으로 호출하여 형식 보장, 영구 용어집, 사용자 지정 스타일 지침 및 토큰 효율적인 출력을 제공합니다.

왜 AI 에이전트를 현지화 MCP에 연결해야 하나요?

i18n 파일을 채팅에 붙여넣는 단순한 방식은 금방 한계에 부딪힙니다. 에이전트가 전문가용 현지화 엔진을 사용할 때 달라지는 점은 다음과 같습니다:

• 대용량 파일 서버 측 처리 — 에이전트가 원시 파일 콘텐츠를 컨텍스트 창에 로드할 필요가 없습니다.
• 형식 보장 — 플레이스홀더, 키, 구조가 번역 후에도 그대로 유지되며 매 호출 시마다 검증됩니다.
• 영구 용어집 — 주요 용어가 모든 파일, 모든 청크, 모든 향후 세션에서 일관되게 유지됩니다.
• 토큰 효율성 — 에이전트는 파일 경로만 전송하며 메타데이터만 반환받습니다.
• 증분 번역 — 새 문자열이나 변경된 문자열만 번역되어 기존 번역을 보호합니다.
• 실무용 출력 — 별도의 사후 편집이 필요 없습니다.

AI 에이전트를 위한 전문가 수준의 현지화 기능

ai-l10n MCP 서버는 AI 에이전트가 단독으로 구현할 수 없는 기능을 추가합니다:

📖 AI 용어집 생성

번역 전 에이전트에게 원본 콘텐츠로부터 용어집을 생성하도록 요청하세요. 용어집은 l10n.dev 계정에 저장되며 이후 모든 파일과 청크에 자동으로 적용되어 전체 애플리케이션에서 용어 일관성을 영구적으로 유지합니다.

✏️ 사용자 지정 스타일 및 어조 규칙

언어 쌍별로 언어적 지침을 생성하세요(예: "라틴 아메리카 스페인어를 대상으로 비격식 어조 사용" 또는 "브랜드 용어는 항상 영어로 유지"). 지침은 계정에 저장되어 매 번역 호출 시 자동으로 적용되므로 매번 반복할 필요가 없습니다.

💾 토큰 효율적인 번역

MCP 없이는 대용량 i18n 파일을 번역할 때 전체 파일을 에이전트 컨텍스트 창에 로드해야 하므로 비용이 많이 들고 종종 잘립니다. MCP를 사용하면 에이전트는 파일 경로만 보내고 메타데이터만 받습니다. 전체 번역은 서버 측에서 처리되어 컨텍스트 창을 비워둡니다.

🛡️ 형식 보장

서버는 매 번역 후 출력 형식이 원본과 일치하는지 검증합니다. JSON 구조, Flutter ARB 메타데이터, YAML 키, PO 카탈로그, XLIFF 세그먼트 및 모든 플레이스홀더 구문을 보존합니다. 결과가 반환되기 전 서버 측에서 검증이 수행됩니다.

⚡ 증분 업데이트

해시 기반 변경 감지를 활성화하여 이미 번역된 문자열을 건너뜁니다. 새로 추가되거나 수정된 문자열만 번역 대상으로 전송되어 문자 할당량을 절약하고 기존 번역이 덮어쓰이지 않도록 보호합니다.

시작하기

API 키 받기

무료 계정을 만들고 다음에서 API 키를 받으세요: l10n.dev/ws/api-keys. 에이전트 구성(아래 참조)에서 환경 변수로 키를 설정하거나, l10n_set_api_key 도구를 사용하여 에이전트가 한 번 저장하도록 요청할 수 있습니다. 이 도구는 ~/.ai-l10n/config.json에 저장되어 자동으로 사용됩니다.

AI 에이전트 구성

아래에서 에이전트를 선택하고 MCP 서버 구성을 추가하세요. 모든 에이전트는 동일한 npm 패키지를 사용하며 구성 형식만 다릅니다.

Claude Desktop

설정(Settings) → 개발자(Developer) → 구성 편집(Edit Config)을 엽니다. Claude Desktop이 설치에 맞는 올바른 MCP 구성 파일을 엽니다. l10n 서버 블록을 추가하세요:

{
  "mcpServers": {
    "l10n": {
      "command": "npx",
      "args": ["-y", "ai-l10n-mcp"],
      "env": {
        "L10N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Cursor의 사용자 지정(Customize)에서 MCP 서버를 관리하거나 구성을 수동으로 추가하세요. 사용자 전체 설정에는 ~/.cursor/mcp.json을, 프로젝트별 설정에는 프로젝트 내 .cursor/mcp.json을 사용하세요:

{
  "mcpServers": {
    "l10n": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ai-l10n-mcp"],
      "env": {
        "L10N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

Cascade에서 MCP 패널을 열거나 Devin 설정(Devin Settings) → Cascade → MCP 서버(MCP Servers)로 이동하세요. 수동 설정의 경우 ~/.codeium/windsurf/mcp_config.json을 편집하세요:

{
  "mcpServers": {
    "l10n": {
      "command": "npx",
      "args": ["-y", "ai-l10n-mcp"],
      "env": {
        "L10N_API_KEY": "your-api-key-here"
      }
    }
  }
}

GitHub Copilot (VS Code)

명령 팔레트(Command Palette)를 열고 MCP: 사용자 구성 열기(MCP: Open User Configuration)를 선택하거나 작업 공간에 .vscode/mcp.json 파일을 만드세요:

{
  "servers": {
    "l10n": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ai-l10n-mcp"],
      "env": {
        "L10N_API_KEY": "your-api-key-here"
      }
    }
  }
}

OpenAI Codex

사용자 전체 설정은 ~/.codex/config.toml에, 신뢰할 수 있는 프로젝트는 프로젝트 내 .codex/config.toml에 추가하세요:

[mcp_servers.l10n]
command = "npx"
args = ["-y", "ai-l10n-mcp"]

[mcp_servers.l10n.env]
L10N_API_KEY = "your-api-key-here"

또는 터미널에서 직접 추가하세요:

codex mcp add l10n --env L10N_API_KEY=your-api-key-here -- npx -y ai-l10n-mcp

Claude Code

터미널에서 서버를 추가하세요. CLI와 VS Code 확장 프로그램 모두에서 작동합니다:

claude mcp add --env L10N_API_KEY=your-api-key-here --transport stdio l10n -- npx -y ai-l10n-mcp

예시: AI 에이전트로 앱 번역하기

MCP가 연결되면 에이전트는 번역 전 지침과 용어집을 사전에 확인합니다. "내 앱을 스페인어와 프랑스어로 번역해 줘"라고 말할 때 일반적인 세션은 다음과 같습니다:

프로젝트 설정 프롬프트

MCP에는 내장된 l10n_project_setup 프롬프트가 포함되어 있어, 최적의 번역 품질을 위해 에이전트가 언어적 지침과 용어집을 확인하고 구성하도록 안내합니다. 새 프로젝트를 시작할 때나 현지화 설정을 검토할 때 실행하세요.

"l10n_project_setup 프롬프트 실행" 또는 "이 프로젝트에 l10n.dev 설정"

자동화 설정 프롬프트

MCP에는 내장된 l10n_automation_setup 프롬프트가 포함되어 있어, i18n 파일의 자동 번역 구성을 에이전트가 수행하도록 안내합니다. 한 번만 실행하면 향후 모든 커밋에 대해 자동 번역이 설정되어 수동으로 번역을 트리거할 필요가 없습니다.

"l10n_automation_setup 프롬프트 실행" 또는 "이 프로젝트에 자동 현지화 설정"

모범 사례

• 용어집 사용: 용어집 생성을 활성화하거나 기존 용어집을 사용하세요. AI에게 기존 용어집을 프로젝트에 추가하도록 요청하세요. 이는 첫 번째 번역부터 일관된 용어 사용을 보장합니다.
• 언어별 어조 지침 설정: 시장마다 기대치가 다릅니다. 언어 쌍별로 지침을 설정하세요(예: 독일어 비즈니스 소프트웨어에는 격식 있는 어조, 스페인어 소비자 앱에는 비격식 어조).
• 업데이트 시 증분 모드 사용: 대상 파일이 이미 존재하는 경우 항상 증분 번역을 활성화하세요. 이는 현재 번역을 보호하고 문자 할당량을 절약합니다.
• API 키 안전하게 저장: 공유 또는 CI/CD 설정의 경우 에이전트의 MCP 구성에서 환경 변수를 사용하세요. 개인용은 에이전트에게 l10n_set_api_key로 한 번 저장하도록 요청하세요.
• 프로젝트 설정 프롬프트 사용: 새 프로젝트를 시작할 때마다 l10n_project_setup을 실행하여 번역 전 지침과 용어집이 구성되었는지 확인하세요.
• 자동화 설정 프롬프트 사용: 수동 작업 감소 및 릴리스 속도 향상. ai-l10n CLI 또는 VS Code 확장 프로그램을 사용하여 i18n 파일의 번역을 자동화하세요. 번역을 수동으로 트리거할 필요가 없으며, 모든 파일에서 일관된 형식, 용어집 적용 및 스타일 지침을 보장합니다.

AI 에이전트에 전문가 수준의 현지화 기능을 추가할 준비가 되셨나요?