개발 도구 - Lingo.dev Compiler

@lingo.dev/compiler는 개발 워크플로를 가속화하고 개발 중 API 비용을 절감하는 개발 도구를 제공합니다.

의사 번역기

의사 번역기는 API 호출 없이 즉각적인 가짜 번역을 생성합니다.

활성화

{
  dev: {
    usePseudotranslator: true,
  }
}

기능

시각적 마커로 텍스트를 변환합니다:

원본:

Welcome to our app

의사 번역됨:

[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]

장점:

즉각적인 피드백 — API 호출 없음, 대기 시간 없음
번역 가능한 텍스트 시각화 — 번역되는 내용을 정확히 확인
다양한 길이 테스트 — 의사 번역은 약 30% 더 길어 레이아웃 문제를 드러냄
비용 제로 — API 크레딧 소비 없음

작동 원리

의사 번역기는:

마커 추가([!!! 및 !!!])
문자를 악센트 버전으로 대체(a → ä, e → ë)
텍스트 길이를 약 30% 확장
보간 유지({name}는 {name}로 유지)
HTML 구조 유지

보간이 포함된 예시:

<p>Hello {name}, you have {count} items</p>
// Becomes: [!!! Ḧëļļö {name}, ÿöü ḧävë {count} ïẗëṁṡ !!!]

사용 시기

개발 중:

초기 설정 및 통합
다양한 텍스트 길이로 레이아웃 테스트
번역 문제 디버깅
UI의 빠른 반복

사용하지 말아야 할 때:

실제 번역 품질 검토
로케일별 형식 테스트
배포 전 최종 QA

실제 번역을 위해 비활성화

{
  dev: {
    usePseudotranslator: false,
  }
}

개발 서버를 재시작하여 구성된 LLM 제공자를 사용해 실제 번역을 생성합니다.

번역 서버

번역 서버는 개발 중 온디맨드 번역 생성을 처리합니다.

작동 방식

npm run dev를 실행하면:

컴파일러가 로컬 HTTP 서버를 시작합니다
서버가 사용 가능한 포트를 자동으로 찾습니다 (60000-60099)
앱이 서버에 번역을 요청합니다
서버가 번역을 생성합니다 (의사 번역 또는 실제 번역)
번역이 .lingo/metadata.json에 캐시됩니다

구성

{
  dev: {
    translationServerStartPort: 60000, // Starting port
    translationServerUrl: "http://localhost:60000", // Custom URL (advanced)
  }
}

포트 범위: 서버는 사용 가능한 포트를 찾을 때까지 60000-60099 포트를 순차적으로 시도합니다.

수동 시작 (고급)

번역 서버를 수동으로 시작할 수 있습니다:

npx @lingo.dev/compiler translate-server \
  --port 60000 \
  --config ./lingo.config.json

다음과 같은 경우에 유용합니다:

빌드 프로세스와 별도로 번역 서버 실행
번역 문제 디버깅
커스텀 CI/CD 워크플로우

WebSocket 지원

번역 서버는 개발 위젯과의 실시간 통신을 위해 WebSocket을 지원합니다.

번역이 업데이트되면 서버는 WebSocket을 통해 연결된 클라이언트에 변경 사항을 푸시합니다.

개발 위젯

개발 위젯은 실시간으로 번역을 편집할 수 있는 브라우저 내 오버레이입니다.

기능

브라우저에서 번역 편집 — 파일을 편집할 필요가 없습니다
컨텍스트 확인 — 원본 텍스트, 컴포넌트 위치 확인
실시간 업데이트 — WebSocket을 통해 변경 사항이 즉시 적용됩니다
로케일 전환 — 다양한 로케일을 빠르게 테스트합니다

활성화

{
  dev: {
    enableWidget: true, // Coming soon
  }
}

상태: 개발 위젯은 현재 활발히 개발 중이며 향후 릴리스에서 제공될 예정입니다.

작동 방식

키보드 단축키를 누릅니다 (예: Cmd+Shift+L)
위젯 오버레이가 나타납니다
번역된 텍스트를 클릭하여 편집합니다
특정 로케일에 대한 번역을 변경합니다
저장—변경 사항이 WebSocket을 통해 동기화됩니다
번역이 .lingo/metadata.json에서 즉시 업데이트됩니다

개발 워크플로우

권장 설정

1. 초기 설정:

{
  dev: {
    usePseudotranslator: true, // Fast feedback
  }
}

npm run dev를 실행하여 의사 번역을 즉시 확인하세요.

2. 레이아웃 테스트:

의사 번역은 레이아웃 문제를 드러냅니다:

텍스트 오버플로
잘린 레이블
정렬되지 않은 요소
잘못된 반응형 중단점

실제 번역에 투자하기 전에 레이아웃 문제를 수정하세요.

3. 실제 번역 검토:

{
  dev: {
    usePseudotranslator: false,
  }
}

실제 번역을 생성하여 품질을 검토하세요. 테스트 항목:

번역 정확도
어조 및 격식
기술 용어 처리
브랜드명 보존

4. 미세 조정:

정밀한 제어를 위해 data-lingo-override를 사용하세요:

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

5. 프로덕션 빌드:

{
  buildMode: "cache-only",
}

빠르고 결정론적인 빌드를 위해 사전 생성된 번역을 사용하세요.

디버깅

번역 서버 확인

번역 서버가 콘솔에 로그를 출력합니다:

[lingo] Translation server started on port 60001
[lingo] Pseudotranslator: enabled
[lingo] Watching for changes...

메타데이터 파일 확인

.lingo/metadata.json를 검사하여 캐시된 번역을 확인하세요:

{
  "translations": {
    "abc123": {
      "source": "Welcome to our app",
      "locales": {
        "es": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]",
        "de": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]"
      }
    }
  }
}

의사 번역기가 비활성화되면 실제 번역이 대신 표시됩니다.

포트 충돌

60000-60099 포트가 모두 사용 중인 경우:

{
  dev: {
    translationServerStartPort: 61000, // Use different range
  }
}

또는 해당 포트를 사용하는 프로세스를 수동으로 중지하세요:

# Find process using port 60000
lsof -i :60000

# Kill process
kill -9 <PID>

성능 팁

Pseudotranslator는 빠릅니다—개발 시 기본적으로 사용하세요.

실제 번역은 더 느립니다—품질을 검토해야 할 때만 사용하세요:

초기 번역 생성: API 지연 시간이 적용됩니다
후속 빌드: 번역이 캐시되어 빠릅니다

번역 서버는 가볍습니다—최소한의 메모리 및 CPU 사용량.

자주 묻는 질문

번역 서버를 수동으로 시작해야 하나요? 아니요. npm run dev를 실행하면 자동으로 시작됩니다.

프로덕션에서 pseudotranslator를 사용할 수 있나요? 아니요. Pseudotranslator는 개발 전용입니다. 프로덕션 빌드는 항상 .lingo/metadata.json의 실제 번역을 사용합니다.

개발 위젯이 아직 제공되지 않는 이유는 무엇인가요? 현재 활발히 개발 중입니다. 업데이트는 GitHub 릴리스를 참조하세요.

pseudotranslation을 커스터마이징할 수 있나요? 현재는 불가능합니다. Pseudotranslator는 번역 가능한 텍스트를 시각화하는 데 최적화된 고정 알고리즘을 사용합니다.

pseudotranslation이 모든 문자 집합에서 작동하나요? 예. Pseudotranslator는 이모지, CJK 문자, RTL 언어를 포함한 유니코드를 올바르게 처리합니다.

다음 단계

프로젝트 구조 — .lingo/ 디렉토리 이해하기
빌드 모드 — 개발 vs 프로덕션 최적화
모범 사례 — 권장 개발 워크플로우