문제 해결

@lingo.dev/compiler 사용 시 발생하는 일반적인 문제와 해결 방법입니다.

설치 문제

"Cannot find module '@lingo.dev/compiler'"

원인: 패키지가 설치되지 않았거나 잘못 설치되었습니다.

해결 방법:

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

설치 확인:

ls node_modules/@lingo.dev/compiler

"Module not found: Can't resolve '@lingo.dev/compiler/react'"

원인: 잘못된 경로에서 가져오거나 오래된 패키지입니다.

해결 방법:

  1. import 문 확인:

    import { LingoProvider } from "@lingo.dev/compiler/react"; // Correct

  2. 패키지 재설치:

    rm -rf node_modules
npm install

구성 문제

"Config must be async function" (Next.js)

원인: Next.js 구성이 비동기 함수로 래핑되지 않았습니다.

해결 방법:

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

"sourceLocale is required"

원인: 구성에 sourceLocale가 누락되었습니다.

해결 방법:

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

"targetLocales must be an array"

원인: targetLocales가 배열이 아니거나 비어 있습니다.

해결 방법:

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

번역 문제

번역이 표시되지 않음

증상: 텍스트가 소스 언어로만 표시됩니다.

원인 및 해결 방법:

1. LingoProvider가 추가되지 않았거나 잘못된 위치에 있음

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. 메타데이터에 번역이 누락됨 .lingo/metadata.json를 확인하세요:

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

비어 있거나 누락된 경우 buildMode: "translate"로 실행하세요:

npm run dev # or build

3. 빌드 모드가 캐시 전용이지만 캐시된 번역이 없음

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

모든 번역이 "[!!! ...]"로 표시됨

원인: 의사 번역기(pseudotranslator)가 활성화되어 있습니다.

해결 방법:

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

개발 서버를 재시작하세요.

일부 텍스트가 번역되지 않음

원인:

1. 동적 콘텐츠 또는 props

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

해결 방법: 컴파일러가 문자열 리터럴을 지원하도록 개선되고 있습니다. 현재로서는 텍스트를 JSX에 직접 넣으세요.

2. 속성의 텍스트는 특정 처리가 필요합니다

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. useDirective가 활성화됨 useDirective: true인 경우, 'use i18n'가 없는 파일은 번역되지 않습니다.

해결 방법: 지시문을 추가하세요:

'use i18n';

export function Component() { ... }

빌드 문제

"로케일 X에 대한 번역이 누락됨"

원인: buildMode: "cache-only"이지만 번역이 누락되었습니다.

해결 방법:

  1. 번역을 생성하세요:

    npm run dev # or
LINGO_BUILD_MODE=translate npm run build

  2. .lingo/metadata.json를 커밋하세요

  3. cache-only로 재시도하세요

"번역 생성 실패"

원인:

1. 유효하지 않은 API 키

# Check .env file
cat .env | grep API_KEY

제공업체에 맞는 올바른 API 키인지 확인하세요.

2. 네트워크 문제 API 연결을 테스트하세요:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. 속도 제한 번역 생성 속도를 늦추거나 API 등급을 업그레이드하세요.

4. 유효하지 않은 모델 구성

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

빌드가 느림

원인:

1. 많은 번역 생성 새 텍스트가 있는 첫 번째 빌드는 느립니다. 이후 빌드는 빠릅니다(캐시됨).

2. 개발 환경에서 의사 번역기가 비활성화됨

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. 불필요하게 활성화된 복수형 처리

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

HMR 문제

HMR이 작동하지 않음

원인: LingoProvider 배치 또는 프레임워크 설정 문제.

해결 방법:

Next.js: LingoProvider가 중첩된 레이아웃이 아닌 루트 레이아웃에 있는지 확인하세요.

Vite: lingoCompilerPlugin가 react() 플러그인 앞에 배치되어 있는지 확인하세요:

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

번역 변경 시 상태 초기화

원인: 로케일 변경으로 인한 페이지 새로고침.

예상 동작: setLocale()는 기본적으로 새 로케일을 적용하기 위해 페이지를 새로고침합니다.

새로고침 방지: 새로고침 없이 커스텀 persistLocale를 구현하세요:

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

참고: 이 방법은 모든 로케일에 대한 번역을 미리 로드해야 합니다.

API/인증 문제

"API 키가 유효하지 않음"

해결 방법:

1. 환경 변수 이름 확인

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. API 키가 활성화되어 있는지 확인 제공업체 대시보드에 로그인하여 키 상태를 확인하세요.

3. 키 추가 후 개발 서버 재시작

npm run dev

환경 변수는 시작 시 로드됩니다.

"인증 실패" (Lingo.dev)

해결 방법:

1. 재인증

npx lingo.dev@latest login

2. 수동 API 키

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

lingo.dev 프로젝트 설정에서 키를 가져오세요.

브라우저가 인증 플로우 차단

원인: Brave 브라우저 또는 확장 프로그램이 인증을 차단합니다.

해결 방법: .env에 API 키를 수동으로 추가하세요:

LINGODOTDEV_API_KEY=...

서버 문제

"번역 서버 시작 실패"

원인: 60000-60099 포트가 모두 사용 중입니다.

해결 방법:

1. 다른 포트 범위 구성

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. 기존 프로세스 종료

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

"포트 60000이 이미 사용 중"

원인: 다른 프로세스가 해당 포트를 사용하고 있습니다.

해결 방법: 서버가 자동으로 사용 가능한 다음 포트를 찾습니다. 콘솔에서 실제 포트를 확인하세요:

[lingo] Translation server started on port 60001

모든 포트가 사용 중인 경우 위의 "번역 서버 시작 실패"를 참조하세요.

타입 오류

"Property 'data-lingo-override' does not exist"

원인: TypeScript가 해당 속성을 인식하지 못합니다.

해결 방법: 타입 선언을 추가하세요:

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

또는 따옴표를 사용하세요:

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

"Type error: Config must return Promise"

원인: Next.js 설정이 올바르게 타입 지정되지 않았습니다.

해결 방법:

import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

프로덕션 문제

프로덕션에서 번역이 누락됨

원인:

1. .lingo/가 커밋되지 않음

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

2. 프로덕션 빌드 모드가 잘못됨

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. CI가 번역을 생성하지 않음 CI 로그를 확인하여 번역이 생성되고 커밋되었는지 확인하세요.

개발 환경과 프로덕션 환경의 번역이 다름

원인: 프로덕션에서 Pseudotranslator가 활성화되어 있습니다.

해결 방법:

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

도움 받기

여전히 문제가 해결되지 않는다면:

  1. 로그 확인 — 콘솔에서 오류 메시지를 확인하세요
  2. .lingo/metadata.json 확인 — 구조와 내용을 검증하세요
  3. pseudotranslator로 테스트 — API 문제를 격리하세요
  4. GitHub 이슈 확인 — github.com/lingodotdev/lingo.dev/issues
  5. Discord에서 질문 — discord.gg/lingo

도움을 요청할 때 다음을 포함하세요:

  • 오류 메시지 (전체 스택 트레이스)
  • 구성 (next.config.ts 또는 vite.config.ts)
  • 패키지 버전 (npm list @lingo.dev/compiler)
  • 재현 단계

자주 묻는 질문

Q: 프로덕션에서 API 키가 필요한가요? A: 아니요, buildMode: "cache-only"를 사용하면 필요하지 않습니다. 번역은 CI에서 미리 생성됩니다.

Q: 빌드가 실패하는 이유는 무엇인가요? A: 오류 메시지를 확인하세요. 일반적인 원인: 누락된 번역, 잘못된 API 키, 네트워크 문제.

Q: 여러 LLM 제공업체를 사용할 수 있나요? A: 예, models 구성에서 로케일 쌍 매핑을 사용하면 가능합니다.

Q: API 비용 없이 테스트하려면 어떻게 해야 하나요? A: 개발 환경에서 usePseudotranslator: true를 활성화하세요.

다음 단계