Context Crawler: better-i18n의 AI 기반 웹사이트 및 리포지토리 분석으로 더 스마트한 번역 실현

better-i18n이 제품에서 AI 컨텍스트를 구축하는 방법

대부분의 현지화 워크플로우는 수동 단계에서 시작됩니다. 누군가 string에 태그를 붙이고, 파일을 내보내고, 누락된 것이 없기를 바랍니다. better-i18n은 다른 접근 방식을 취합니다. Context Crawler는 두 가지 강력한 분석 모드(웹사이트 크롤링과 저장소 스캔)를 결합하여 AI 번역을 극적으로 정확하게 만드는 풍부한 컨텍스트를 자동으로 구축합니다.

그 결과, AI 번역기가 단 하나의 string을 번역하기 전에 여러분의 브랜드, 제품 어휘, 기술 스택을 이해하는 워크플로우가 만들어집니다.

웹사이트 분석: Firecrawl 기반 브랜드 발견

Context Crawler의 웹사이트 분석 모드는 Firecrawl API를 사용하여 제공한 URL에서 콘텐츠를 체계적으로 크롤링하고 추출합니다. 이것은 단순한 HTML 스크래핑이 아닙니다. Firecrawl은 JavaScript 렌더링 페이지, SPA, 동적 콘텐츠를 처리하여 사용자가 실제로 보는 내용을 캡처합니다.

웹사이트 분석 작동 방식

1. URL 제공 — 제품의 마케팅 사이트, 문서 또는 모든 웹 자산의 URL을 입력합니다. 크롤러는 공개적으로 접근 가능한 모든 URL을 허용합니다.
2. Firecrawl 추출 — Firecrawl API가 페이지를 렌더링하고, 내부 링크를 따라가며, 제목, 본문 텍스트, 내비게이션 레이블, CTA 및 메타데이터를 포함한 구조화된 콘텐츠를 추출합니다.
3. 용어 감지 — AI 분석이 크롤링된 모든 페이지에서 반복되는 용어, 브랜드 언어, 제품명, 기능명 및 도메인별 어휘를 식별합니다.
4. 후보 제안 — 감지된 용어가 제안된 정의, 컨텍스트 메모, 빈도 데이터와 함께 glossary 후보로 제안됩니다. 각 후보에는 발견된 소스 URL이 포함됩니다.

웹사이트 분석이 캡처하는 내용

• 브랜드 용어 — 사이트 전반에 걸쳐 일관되게 나타나는 제품명, 기능명, 가격 티어 레이블 및 고유 용어
• 내비게이션 패턴 — 제품 어휘를 정의하는 메뉴 레이블, breadcrumb 텍스트 및 CTA 언어
• 도메인 어휘 — 제품이 사용하는 업계별 용어로 정확하고 일관된 번역이 필요한 것들
• 톤 및 보이스 신호 — 콘텐츠가 격식체인지, 캐주얼한지, 기술적인지, 마케팅 지향적인지 여부 — AI가 적절한 어조로 번역하는 데 도움이 되는 컨텍스트

웹사이트 분석 활용 사례

• 새 프로젝트 설정 — 현지화를 시작하기 전에 마케팅 사이트를 크롤링하여 수 주가 아닌 몇 분 만에 glossary와 컨텍스트 프로필을 부트스트랩합니다
• 경쟁사 분석 — 타겟 시장의 경쟁사 사이트를 크롤링하여 유사한 개념을 어떻게 번역하는지 파악하고, 자체 glossary 결정에 반영합니다
• 콘텐츠 감사 — 마지막 glossary 업데이트 이후 새로 등장한 용어를 감지하기 위해 주기적으로 재크롤링합니다

저장소 분석: 프레임워크 및 용어 감지

Context Crawler의 저장소 분석 모드는 GitHub 저장소에 연결하여 코드베이스를 심층 분석하고 번역 관련 컨텍스트를 추출합니다.

저장소 분석 작동 방식

1. GitHub 저장소 연결 — 저장소 URL을 제공합니다. 크롤러는 공개 저장소에 직접 접근하고 비공개 저장소는 GitHub 통합을 통해 접근합니다.
2. 프레임워크 감지 — 분석기가 기술 스택을 식별합니다: React, Next.js, Vue, Angular, Svelte, Flutter, React Native 등. 이를 통해 어떤 i18n 패턴을 찾을지, 코드를 어떻게 파싱할지 결정합니다.
3. i18n 패턴 인식 — 감지된 프레임워크를 기반으로 기존 번역 함수 호출(t(), useTranslations(), $t(), tr() 등)을 찾고, 프로젝트가 번역을 어떻게 구성하는지 매핑합니다.
4. 용어 추출 — 분석기가 하드코딩된 string, 컴포넌트명, 라우트 레이블 및 제품 어휘를 나타내는 기타 사용자 대면 텍스트를 식별합니다.
5. 컨텍스트 프로필 생성 — 모든 발견 사항이 감지된 프레임워크, i18n 라이브러리 사용, namespace 구조 및 용어 후보를 포함한 컨텍스트 프로필로 컴파일됩니다.

저장소 분석이 감지하는 내용

• 프레임워크 및 i18n 라이브러리 — AI 번역이 올바른 포맷 규칙을 사용할 수 있도록 스택 자동 감지 (ICU MessageFormat, i18next interpolation, Flutter ARB 등)
• Namespace 구조 — 프로젝트가 번역 key를 구성하는 방식으로, 새 번역이 동일한 패턴을 따를 수 있게 합니다
• 기존 용어 — 코드베이스에서 이미 사용 중인 용어로, glossary에 추가해야 할 항목 식별에 도움을 줍니다
• String 패턴 — 번역 규칙을 알려주는 사용자 대면 string의 일반적인 패턴 (날짜 형식, 숫자 형식, 복수형 처리 방식)

AST 기반 Key 감지

컨텍스트 구축 외에도, CLI의 scan 명령어는 취약한 regex 매칭이 아닌 syntax tree 수준에서 소스 코드를 파싱합니다. React JSX, useTranslations, getTranslations 패턴을 기본적으로 이해합니다. 즉, <h1>Welcome back</h1>과 같은 사용자 대면 string과 className="flex items-center"와 같은 기술적 string을 오탐 없이 구별할 수 있습니다.

감지 대상:

• 하드코딩된 JSX 텍스트 — t() 호출로 래핑해야 하는 <h1>Hello</h1> 같은 콘텐츠
• 하드코딩된 JSX 속성 — <img alt="Company logo" />와 같은 사용자 대면 속성
• Toast 및 알림 string — toast.error("Something went wrong")과 같은 호출
• Locale 기반 삼항 논리 — 수동 locale 처리를 나타내는 locale === 'en' ? 'Hi' : 'Hola'와 같은 패턴
• String 변수 — 사용자 대면으로 보이는 텍스트를 포함하는 변수

지능적으로 무시하는 항목:

• Tailwind 및 CSS 클래스명
• URL, 파일 경로 및 이미지 소스
• HTML 엔티티 (&, ")
• SCREAMING_CASE의 기술적 상수
• 숫자 및 비텍스트 값

better-i18n scan              # 현재 디렉토리 스캔
better-i18n scan --dir ./src  # 특정 디렉토리 스캔
better-i18n scan --staged     # 스테이징된 파일만 (pre-commit hook용)
better-i18n scan --ci         # 문제 발견 시 exit code 1
better-i18n scan --format json # 도구 활용을 위한 JSON 출력
better-i18n scan --verbose    # 스캔 감사 포함 상세 출력

Namespace 해석

스캐너는 클라이언트 및 서버 컴포넌트 모두에 대해 lexical scope 추적을 사용하여 namespace를 자동으로 해석합니다. 감지된 key에 key 이름만이 아닌 전체 namespace 경로가 포함된다는 것을 의미하기 때문에 중요합니다.

hook을 사용하는 클라이언트 컴포넌트:

const t = useTranslations('hero');
return <h1>{t('title')}</h1>; // 감지 결과: hero.title

async 함수를 사용하는 서버 컴포넌트:

const t = await getTranslations('welcome');
return <h1>{t('title')}</h1>; // 감지 결과: welcome.title

스캐너는 객체 형식(getTranslations({ locale, namespace: 'settings' }))과 namespace가 제공되지 않은 루트 범위 번역기도 처리합니다. 변수나 template literal을 사용하는 동적 namespace는 --verbose 모드에서 보고되며, 오탐을 방지하기 위해 메트릭에서 제외됩니다.

분석에서 Glossary까지: 전체 파이프라인

Context Crawler의 웹사이트 및 저장소 분석 모드는 Glossary 관리 시스템으로 직접 연결됩니다:

1. 크롤링 — Firecrawl을 통한 웹사이트 분석으로 브랜드 용어를 추출하고, 저장소 분석으로 프레임워크 컨텍스트와 기존 용어를 감지합니다.
2. 제안 — 감지된 용어가 draft 상태로 glossary 후보로 제안됩니다.
3. 검토 — 팀이 제안된 용어를 검토하고 정의 및 번역을 편집합니다.
4. 승인 — 승인된 용어는 AI 번역 및 검토 에디터에 즉시 적용됩니다.
5. 동기화 — 승인된 용어는 프로바이더 수준 적용을 위해 DeepL과 동기화할 수 있습니다.

이 파이프라인 덕분에 "glossary가 없는 상태"에서 "AI 번역이 200개의 브랜드 용어를 적용하는 상태"로 단 하루 오후 만에 전환할 수 있습니다.

Sync: 로컬과 클라우드 비교

sync 명령어는 코드에서 사용하는 것과 better-i18n에 존재하는 것 사이의 간격을 연결합니다. scan과 동일한 방식으로 코드베이스를 스캔한 후 better-i18n API를 쿼리하여 key 집합을 비교합니다.

출력은 명확한 비교 보고서입니다:

• Remote에 누락 — 코드에서 참조되지만 아직 better-i18n에 업로드되지 않은 key. 이는 사용자에게 번역되지 않은 상태로 보일 수 있는 string입니다.
• 코드에서 미사용 — better-i18n에는 존재하지만 소스 어디에도 더 이상 참조되지 않는 key. 이는 정리 후보입니다.

better-i18n sync              # 그룹화된 tree 출력
better-i18n sync --summary    # 고수준 커버리지 메트릭만
better-i18n sync --format json # CI 자동화를 위한 JSON 출력
better-i18n sync -d ./src     # 특정 디렉토리 스캔

tree 출력은 key를 namespace별로 그룹화하여 앱의 어느 부분에 격차가 있는지 쉽게 확인할 수 있습니다. --verbose 플래그는 불변성 검사, 스코핑 요약 및 특정 key 프로브를 포함한 심층 감사 로그를 제공합니다.

커버리지 메트릭

sync 명령어는 백분율 기반 커버리지 메트릭을 제공합니다:

• 로컬-Remote 커버리지: 코드에서 사용된 key 중 better-i18n에 존재하는 비율
• Remote 사용률: better-i18n의 key 중 실제로 코드에서 사용되는 비율

이 수치는 팀에게 언제든지 번역 상태에 대한 명확한 그림을 제공합니다. 터미널 출력에서 확인하거나 JSON 출력에서 추출하여 커스텀 대시보드 및 리포팅에 활용할 수 있습니다.

CI 통합

scan과 sync 모두 자동화 파이프라인에서 실행되도록 설계되었습니다. scan과 함께 --ci를 사용하여 하드코딩된 string이 감지될 때 빌드를 실패시키고, jq를 통해 sync 출력을 파이프하여 누락된 key 수에 따라 배포를 제어합니다.

# GitHub Actions 예시
name: i18n Check
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @better-i18n/cli scan --ci
      - run: |
          npx @better-i18n/cli sync --format json \
            | jq -e '.comparison.missingCount == 0' > /dev/null || exit 1

pre-commit hook의 경우, 스테이징된 파일만 스캔하여 피드백을 빠르게 유지합니다:

npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

지원하지 않는 기능

명확한 기대치 설정을 위해:

• 시각적 컨텍스트 캡처 없음 — CLI는 렌더링된 UI가 아닌 코드 수준에서 작동합니다. string이 표시되는 위치의 스크린샷이나 시각적 미리보기는 없습니다.
• 실시간 모니터링 없음 — scan과 sync는 온디맨드 또는 CI 파이프라인에서 실행됩니다. 백그라운드 감시자나 파일 시스템 옵저버가 아닙니다.
• 오래된 번역 감지 없음 — sync 명령어는 누락 및 미사용 key를 표시하지만, 소스 텍스트 변경에 비해 기존 번역이 구식인지 여부는 감지하지 않습니다.

시작하기

1분 이내에 CLI를 설치하고 첫 번째 스캔을 실행합니다:

npm install -g @better-i18n/cli
better-i18n scan --dir ./src

그런 다음 better-i18n 프로젝트에 연결하고 클라우드와 비교합니다:

better-i18n sync

웹사이트 분석을 시작하려면, 프로젝트 대시보드의 AI Context 섹션을 방문하여 URL을 입력하고 Firecrawl이 브랜드 용어를 추출하도록 합니다. 저장소 분석의 경우 GitHub 저장소를 연결하고 분석기가 프레임워크 및 기존 용어를 감지하도록 합니다.

전체 설정 옵션, 감지 규칙 및 고급 사용법은 CLI 문서를 참조하세요.

번역 컨텍스트 및 용어 발견을 자동화할 준비가 되셨나요? 계정을 만들고 첫 번째 프로젝트를 연결하거나, 크롤러가 발견한 용어를 적용하는 Glossary 관리 시스템에 대해 알아보세요.