프로젝트 구조

Lingo.dev Compiler는 프로젝트 루트에 번역 메타데이터와 캐시를 저장하는 .lingo/ 디렉터리를 생성하고 유지합니다. 이 디렉터리 구조를 이해하면 버전 관리에서 번역을 효율적으로 관리하고, 누락된 번역을 디버깅하고, 빌드 성능을 최적화하는 데 도움이 됩니다.

.lingo/ 디렉터리#

컴파일러는 첫 번째 빌드 시 이 디렉터리를 자동으로 생성합니다. 여기에는 빌드 파이프라인에서 사용하는 모든 번역 메타데이터가 들어 있습니다:

.lingo/
  metadata.json              # Translation cache and content hashes
  locale-resolver.server.ts  # Optional: custom server-side locale resolver
  locale-resolver.client.ts  # Optional: custom client-side locale resolver

metadata.json#

이 파일은 .lingo/ 디렉터리의 핵심 파일입니다. 다음 정보를 저장합니다:

• 콘텐츠 해시 - 각 번역 가능 문자열에 대한 안정적인 해시 기반 식별자
• 캐시된 번역 - 각 로캘 쌍에 대해 생성된 번역
• 원문 텍스트 스냅샷 - 번역 시점의 원문 텍스트로, 변경 사항을 감지하는 데 사용됩니다

컴파일러는 빌드가 시작될 때마다 이 파일을 읽습니다. 해시가 일치하는 문자열은 캐시된 번역을 재사용하고, 해시가 변경되었거나 없는 문자열은 설정된 번역 제공자로 전송됩니다.

.gitignore 관련 주의사항#

.lingo/를 .gitignore에 추가하지 마세요. 이 디렉터리는 버전 관리 대상에 포함되어야 합니다. 컴파일러를 사용하는 프로젝트의 일반적인 .gitignore 예시는 다음과 같습니다:

# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.env

sourceRoot#

sourceRoot 옵션은 컴파일러가 번역 가능한 React 컴포넌트를 스캔할 디렉터리를 결정합니다:

{
  sourceRoot: "./app",  // Next.js App Router
  // or
  sourceRoot: "src",    // Vite + React
}

컴파일러는 sourceRoot 안에 있는 모든 .tsx, .ts, .jsx, .js 파일을 재귀적으로 스캔해 번역 가능한 JSX 콘텐츠를 찾습니다. 이 디렉터리 밖에 있는 파일은 처리되지 않습니다.

'use i18n'을 사용하는 옵트인 모드#

기본적으로 컴파일러는 sourceRoot 내의 모든 JSX 텍스트를 번역합니다. 옵트인 모드로 전환하려면 useDirective: true를 설정하세요:

{
  useDirective: true,
}

옵트인 모드에서는 'use i18n' 지시어로 시작하는 파일만 처리됩니다:

'use i18n';

export function Welcome() {
  return <h1>Welcome to our app</h1>;
  // This text IS translated
}

지시어가 없는 파일은 건너뜁니다:

export function InternalAdmin() {
  return <h1>Admin Dashboard</h1>;
  // This text is NOT translated
}

옵트인 모드를 사용할 때#

lingoDir#

lingoDir 옵션으로 메타데이터 디렉터리의 위치를 변경할 수 있습니다:

{
  lingoDir: ".lingo",  // Default
  // or
  lingoDir: ".translations",  // Custom location
}

프로젝트에 이미 있는 디렉터리와 .lingo/가 충돌할 때 유용합니다.

다음 단계#