FAQ - Lingo.dev Compiler

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에 참여하세요.

컬렉션 기반 컴포넌트가 번역되지 않는 이유는 무엇인가요?

현재 컴파일러는 자식 요소로 컬렉션을 기대하는 Adobe React-Aria/React-Stately 기반 컴포넌트에 제한이 있습니다. 컬렉션 아이템 내의 직접적인 텍스트 콘텐츠는 자동으로 지역화되지 않습니다.

이는 HeroUI, NextUI 및 기타 React-Aria 구현 라이브러리의 Select, Listbox, Menu와 같은 컬렉션 기반 컴포넌트에 영향을 미칩니다.

현재 동작:

import { Select, SelectItem } from "@heroui/react";

export default function SelectExample() {
  return (
    <Select label="Select an animal">
      {/* 이 텍스트는 번역되지 않습니다 */}
      <SelectItem key="cat" textValue="Cat">
        Cat
      </SelectItem>
      <SelectItem key="dog" textValue="Dog">
        Dog
      </SelectItem>
    </Select>
  );
}

해결 방법:

텍스트 콘텐츠를 JSX 프래그먼트로 감싸서 지역화 가능하게 만듭니다:

import { Select, SelectItem } from "@heroui/react";

export default function SelectWithWorkaround() {
  return (
    <Select label="Select an animal">
      {/* 이 텍스트는 번역됩니다 */}
      <SelectItem key="cat" textValue="Cat">
        <>Cat</>
      </SelectItem>
      <SelectItem key="dog" textValue="Dog">
        <>Dog</>
      </SelectItem>
    </Select>
  );
}

이 제한은 텍스트 콘텐츠가 컬렉션 아이템에 직접 자식으로 전달되는 React-Aria의 컬렉션 패턴을 사용하는 모든 컴포넌트에 영향을 미칩니다. 저희는 이러한 경우에 대한 컴파일러 지원을 개선하기 위해 노력하고 있습니다.

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

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 컴파일러는 Lingo.dev 엔진 및 여러 다른 LLM 제공업체와 통합되어 있습니다.

곧 더 많은 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}.",
};

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

컴파일러는 기본적인 복수형 패턴을 자동으로 처리하지만, 복잡한 복수형 규칙의 경우 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
고급 기능: 구성 옵션