FAQ

Lingo.dev 컴파일러에 관한 일반적인 질문과 답변입니다.

문자열 리터럴을 번역할 수 있나요?

Lingo.dev 컴파일러는 JSX 내의 모든 것이 현지화 가능하다는 규칙을 따릅니다. JSX 컴포넌트 외부의 문자열 리터럴은 설계상 현지화되지 않습니다.

현재 동작 방식:

// 이것은 번역되지 않습니다
const message = "Hello world";
const errorText = "Something went wrong";

// 이것은 번역됩니다
function Component() {
  return <h1>Hello world</h1>;
}

리터럴을 현지화 가능하게 만들기:

JSX 프래그먼트로 문자열 리터럴을 감싸면 현지화 가능하게 만들 수 있습니다:

// 이전: 현지화 불가능
const message = "Hello world";

// 이후: 프래그먼트를 사용하여 현지화 가능
const message = <>Hello world</>;

// 컴포넌트에서 사용
function Component() {
  return <div>{message}</div>;
}

대안적 접근법:

// 동적 메시지의 경우
function getLocalizedMessage() {
  return <>Something went wrong</>;
}

// 조건부 텍스트의 경우
const statusText = isError ? <>Error occurred</> : <>Success</>;

이 규칙은 현지화 가능한 콘텐츠와 현지화 불가능한 콘텐츠 간의 명확한 경계를 유지하면서 일관된 현지화 동작을 보장합니다.

향후 더 많은 사용 사례를 지원하기 위한 방법을 모색하고 있습니다. 지원되길 원하는 특정 패턴에 대해 논의하려면 Discord에 참여하세요.

어떤 프레임워크가 지원되나요?

Lingo.dev 컴파일러는 현재 다음 React 프레임워크를 지원합니다:

Next.js (App Router만 해당)
React Router v6+
Remix (최신 버전)
Vite + React

다른 플랫폼에 대한 컴파일러 지원 구현에 관심 있는 기여자를 환영합니다. 구현 전략에 대해 논의하려면 Discord에 참여하세요.

더 많은 언어를 추가할 수 있나요?

네! 컴파일러 구성에서 직접 사용자 정의 모델을 구성하여 언어 지원을 확장할 수 있습니다:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de", "pt", "it"],
  models: {
    "*:pt": "mistral-saba-24b",
    "en:it": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
};

lingoCompiler.next(compilerConfig)(nextConfig);

자세한 내용은 고급 구성을 참조하세요.

사용자 정의 프롬프트를 사용할 수 있나요?

네! 컴파일러 구성에서 직접 번역 프롬프트를 사용자 정의할 수 있습니다:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  prompt:
    "당신은 기술 문서 전문 번역가입니다. 기술적 정확성을 유지하면서 {SOURCE_LOCALE}에서 {TARGET_LOCALE}로 번역하세요.",
};

사용자 정의 용어집의 경우, 프롬프트에 용어 정의를 포함하세요. 모범 사례는 기본 프롬프트를 참조하세요.

더 많은 LLM 제공업체를 사용할 수 있나요?

현재 Lingo.dev 컴파일러는 GROQ와 통합되어 있지만, 곧 더 많은 LLM 제공업체를 지원하고 싶습니다 (저희와 대화하세요 또는 풀 리퀘스트를 보내주세요!).

CI/CD에서 GROQ API 키가 필요한가요?

일반적으로 필요하지 않습니다. 로컬에서 앱을 빌드하면 모든 번역이 lingo/ 디렉토리에 저장됩니다. CI/CD 빌드에서는 문자열을 번역하기 위해 LLM을 호출할 필요가 없습니다.

대안으로 CI/CD에 GROQ_API_KEY 변수를 추가하고 빌드 시 모든 번역을 수행할 수 있지만, 최종 번역에 대한 더 많은 제어를 유지하기 위해 이 접근 방식을 권장하지 않습니다.

번역을 편집할 수 있나요?

네! lingo/dictionary.js 파일을 수동으로 편집할 수 있습니다. 이 파일은 모든 파일과 항목에 대한 번역이 포함된 객체를 내보냅니다. content 속성에서 각 로케일의 텍스트를 편집할 수 있습니다. React 컴포넌트의 소스 텍스트가 업데이트될 때까지 편집 내용이 유지됩니다.

JavaScript 객체 편집이 마음에 들지 않나요? 곧 편집 경험을 개선하기 위한 에디터를 출시할 예정입니다. 관심이 있으시면 알려주세요!

전체 앱, 특정 파일 또는 언어를 어떻게 다시 번역할 수 있나요?

전체 앱을 다시 번역하려면 lingo/ 디렉토리에서 dictionary.js 파일을 삭제하세요.

특정 파일만 다시 번역하려면 dictionary.js에서 해당 키(파일 이름)를 삭제할 수 있습니다.

특정 로케일을 다시 번역하려면 해당 로케일에 대한 모든 레코드를 삭제해야 합니다.

왜 앱을 로컬에서 빌드해야 하나요?

로컬 빌드는 다음과 같은 방식으로 lingo/ 번역 파일을 정규화합니다:

사용되지 않는 번역 키 제거
콘텐츠 지문 업데이트
일관된 파일 형식 보장
프로덕션 배포를 위한 최적화

깨끗한 번역 파일을 유지하기 위해 변경사항을 커밋하기 전에 항상 npm run build를 실행하세요.

번역이 누락되었습니다!

번역이 누락된 경우:

로컬에서 빌드하여 lingo/ 파일을 정규화하세요:
```
npm run build
```

API 키가 올바르게 설정되었는지 확인하세요:

# .env 파일에 다음이 포함되어 있는지 확인
GROQ_API_KEY=gsk_...

업데이트된 파일을 커밋하세요:

git add lingo/
git commit -m "Update translations"

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

사용자 정의 용어집을 설정할 수 있나요?

네! 컴파일러 구성에서 직접 용어와 용어집을 정의하기 위해 사용자 정의 프롬프트를 사용하세요:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  prompt:
    "You are a professional translator. Use these terms consistently: 'Dashboard' should be 'Tableau de bord' in French, 'Settings' should be 'Configuración' in Spanish. Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.",
};

특정 콘텐츠를 번역에서 제외하려면 어떻게 하나요?

data-lingo-skip 속성을 사용하세요:

<div data-lingo-skip>This content will not be translated</div>

콘텐츠 유형에 따라 조건부로 건너뛰기:

<code data-lingo-skip>
  // Code blocks are automatically skipped const apiKey = "secret-key";
</code>

특정 번역을 재정의할 수 있나요?

네! 로케일별 재정의를 위해 data-lingo-override- 속성을 사용하세요:

<button data-lingo-override-es="¡Hola!" data-lingo-override-fr="Bonjour!">
  Hello
</button>

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

번역되지 않아야 하는 브랜드 이름
지역별 용어
수동 검토가 필요한 마케팅 문구

컴파일러는 복수형을 어떻게 처리하나요?

컴파일러는 기본적인 복수형 패턴을 자동으로 처리하지만, 복잡한 복수형 규칙의 경우 JSX를 적절히 구성해야 할 수 있습니다:

// 컴파일러가 이를 적절히 처리합니다
<p>{count === 1 ? "1 item" : `${count} items`}</p>

프로덕션 환경에서의 성능은 어떤가요?

Lingo.dev 컴파일러는 프로덕션 환경에 최적화되어 있습니다:

런타임 비용 제로 - 번역은 사전 컴파일됨
번들 분할 - 활성화된 로케일만 로드됨
트리 쉐이킹 - 사용되지 않는 번역은 제거됨
CDN 친화적 - 정적 번역 파일이 효율적으로 캐싱됨

TypeScript와 함께 사용할 수 있나요?

네! 컴파일러는 TypeScript 프로젝트와 원활하게 작동합니다. 제공된 모든 React 컴포넌트는 완전히 타입이 지정되어 있습니다:

import { LocaleSwitcher } from "lingo.dev/react/client";

// 완전한 TypeScript 지원
const locales: string[] = ["en", "es", "fr"];
<LocaleSwitcher locales={locales} />;

버그를 보고하거나 기능을 요청하려면 어떻게 하나요?

GitHub 이슈: 이슈 열기
Discord 커뮤니티: Discord 참여하기
기능 요청: 기능 제안을 위해 GitHub 토론 사용

다음 단계

시작하기: 빠른 시작 가이드
프레임워크 통합: Next.js, React Router, Vite
고급 기능: 구성 옵션