프로젝트 구조

.lingo/ 디렉토리와 그 내용을 이해합니다.

디렉토리 개요

컴파일러를 처음 실행하면 프로젝트 루트에 .lingo/ 디렉토리가 생성됩니다:

your-project/
├── .lingo/
│   ├── metadata.json
│   ├── locale-resolver.server.ts (optional)
│   └── locale-resolver.client.ts (optional)
├── src/
├── package.json
└── ...

metadata.json

모든 번역 데이터를 포함하는 핵심 파일입니다.

구조

{
  "version": "1",
  "sourceLocale": "en",
  "targetLocales": ["es", "de", "fr"],
  "translations": {
    "abc123def456": {
      "source": "Welcome to our app",
      "context": {
        "file": "app/page.tsx",
        "line": 12,
        "component": "HomePage"
      },
      "locales": {
        "es": "Bienvenido a nuestra aplicación",
        "de": "Willkommen in unserer App",
        "fr": "Bienvenue dans notre application"
      },
      "metadata": {
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  }
}

주요 필드

버전: 메타데이터 형식 버전. 현재: "1"

소스/타겟 로케일: 구성된 로케일

번역: 모든 번역 가능한 문자열의 해시 기반 매핑:

• 해시 (abc123def456): 소스 텍스트 + 컨텍스트를 기반으로 한 안정적인 식별자
• source: 원본 영어 텍스트
• context: 이 텍스트가 나타나는 위치(파일, 라인, 컴포넌트)
• locales: 각 타겟 로케일에 대한 번역
• metadata: 번역이 생성/업데이트된 시간

해시 생성

해시는 결정론적입니다:

• 소스 텍스트 + 컴포넌트 컨텍스트를 기반으로 함
• 다른 위치의 동일한 텍스트 = 다른 해시
• 컨텍스트 인식 번역 가능

예시:

// app/home/page.tsx
<button>Submit</button> // Hash: abc123

// app/checkout/page.tsx
<button>Submit</button> // Hash: def456 (different context)

커스텀 로케일 리졸버

로케일 감지 및 지속성을 커스터마이징하기 위한 선택적 파일입니다.

locale-resolver.server.ts

서버 측 로케일 감지(Next.js 전용):

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Your custom logic
  return "en";
}

locale-resolver.client.ts

클라이언트 측 로케일 감지 및 지속성:

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  // Detect locale
  return "en";
}

export function persistLocale(locale: string): void {
  // Save locale preference
}

이러한 파일이 존재하지 않으면 컴파일러는 기본 쿠키 기반 동작을 사용합니다.

자세한 내용은 사용자 정의 로케일 리졸버를 참조하세요.

버전 관리

.lingo/를 커밋해야 하나요?

예. .lingo/ 디렉토리는 버전 관리되어야 합니다:

커밋할 항목:

• metadata.json — 모든 번역 포함
• 사용자 정의 로케일 리졸버(생성된 경우)

커밋하지 않을 항목:

• 없음 — .lingo/의 모든 파일을 커밋해야 합니다

번역을 커밋하는 이유는?

1. 버전 관리 — 코드와 함께 번역 변경 사항 추적
2. 팀 협업 — 팀 전체에서 번역 공유
3. CI/CD — 프로덕션 빌드에서 커밋된 번역 사용
4. 감사 추적 — 번역이 언제, 왜 변경되었는지 확인

Git 통합

저장소에 .lingo/를 추가하세요:

git add .lingo/
git commit -m "chore: update translations"
git push

컴파일러는 다음과 같은 경우 .lingo/metadata.json를 자동으로 업데이트합니다:

• 새로운 번역 가능한 텍스트가 추가된 경우
• 기존 텍스트가 수정된 경우
• 번역이 생성된 경우

이러한 업데이트를 정기적으로 커밋하세요.

파일 크기

metadata.json는 앱과 함께 증가합니다:

• 소규모 앱(50개 문자열): ~10 KB
• 중규모 앱(500개 문자열): ~100 KB
• 대규모 앱(5000개 문자열): ~1 MB

이는 버전 관리에서 정상적이고 허용 가능한 수준입니다.

정리

사용하지 않는 번역 제거

시간이 지나면서 사용하지 않는 번역(삭제된 컴포넌트에서 발생)이 누적될 수 있습니다.

수동 정리:

1. 코드베이스에서 해시 검색
2. 찾을 수 없으면 metadata.json에서 삭제

자동 정리(곧 출시 예정):

npx @lingo.dev/compiler clean

이렇게 하면 사용하지 않는 번역이 자동으로 제거됩니다.

번역 초기화

모든 번역을 처음부터 다시 생성하려면:

# Backup current translations
cp .lingo/metadata.json .lingo/metadata.backup.json

# Delete metadata
rm .lingo/metadata.json

# Regenerate
npm run dev # or npm run build

마이그레이션

이전 컴파일러에서 마이그레이션

이전 컴파일러는 다른 파일 구조를 사용했습니다:

이전:

lingo/
├── dictionary.js
├── meta.json
└── [locale]/
    └── *.json

새로운:

.lingo/
└── metadata.json

마이그레이션은 자동화되지 않습니다. 자세한 내용은 마이그레이션 가이드를 참조하세요.

번역 검사

편집기에서 보기

편집기에서 .lingo/metadata.json를 엽니다:

{
  "translations": {
    "abc123": {
      "source": "Welcome",
      "locales": {
        "es": "Bienvenido"
      }
    }
  }
}

번역 검색

원본 텍스트로 번역 찾기:

grep -r "Welcome" .lingo/metadata.json

해시로 찾기

grep -r "abc123" .lingo/metadata.json

보기 좋게 출력

cat .lingo/metadata.json | jq '.'

자주 묻는 질문

metadata.json을 수동으로 편집할 수 있나요? 가능하지만 권장하지 않습니다. 대신 data-lingo-override를 사용하세요. 더 안전하고 소스 코드에서 버전 관리됩니다.

metadata.json을 삭제하면 어떻게 되나요? 컴파일러가 다음 빌드 시 재생성합니다. 모든 번역이 새로 생성됩니다(API 크레딧 소모).

.lingo/를 다른 디렉토리로 이동할 수 있나요? 예. lingoDir 옵션을 통해 구성하세요:

{
  lingoDir: "translations"
}

metadata.json에 민감한 데이터가 포함되어 있나요? 아니요. 소스 텍스트와 번역만 포함되며 API 키나 비밀 정보는 포함되지 않습니다.

여러 브랜치의 metadata.json을 병합할 수 있나요? 예. Git이 자동으로 병합을 처리합니다. 충돌은 드뭅니다(해시는 고유합니다).

두 브랜치가 동일한 번역을 추가하면 어떻게 되나요? Git이 자동으로 병합합니다. 해시가 다르면(다른 컨텍스트) 둘 다 유지됩니다.

다음 단계

• 커스텀 로케일 리졸버 — 지속성 커스터마이징
• 개발 도구 — 의사 번역기 작업
• 빌드 모드 — 캐싱 동작 이해