Vite + React 통합

@lingo.dev/compiler는 SPA 및 SSR 설정 모두에서 작동하는 플러그인을 통해 Vite와 통합됩니다.

설정

1. 패키지 설치

pnpm install @lingo.dev/compiler

2. Vite 구성

Vite 설정에 lingoCompilerPlugin를 추가하세요:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

플러그인 순서: lingoCompilerPlugin를 react() 플러그인보다 앞에 배치하세요. 이렇게 하면 컴파일러가 React가 처리하기 전에 JSX를 변환합니다.

3. Provider 추가

진입점에서 LingoProvider로 앱을 래핑하세요:

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <App />
    </LingoProvider>
  </StrictMode>
);

중요: LingoProvider를 컴포넌트 트리에서 가능한 한 높은 위치에 배치하세요. TanStack Router 또는 React Router를 사용하는 경우 LingoProvider를 라우터 provider 위에 배치하세요.

SPA 설정

단일 페이지 애플리케이션의 경우 위의 설정으로 충분합니다. 로케일은 클라이언트 측에서 관리됩니다.

언어 전환기

"use client";

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

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <div>
      <label>Language:</label>
      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
        <option value="en">English</option>
        <option value="es">Español</option>
        <option value="de">Deutsch</option>
        <option value="fr">Français</option>
      </select>
    </div>
  );
}

SSR 설정 (React Router, Remix, TanStack Start)

SSR 프레임워크의 경우 서버에서 로케일 감지를 처리해야 할 수 있습니다.

커스텀 로케일 감지

서버 측 로직을 위한 .lingo/locale-resolver.server.ts를 생성하세요:

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Access request context (framework-specific)
  // Example: parse cookies, headers, or database
  return "en"; // Return detected locale
}

그리고 클라이언트 측을 위한 .lingo/locale-resolver.client.ts:

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

export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
}

프레임워크별 예제는 커스텀 로케일 리졸버를 참조하세요.

TanStack Router 통합

TanStack Router의 경우, LingoProvider를 RouterProvider 위에 배치하세요:

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { RouterProvider, createRouter } from "@tanstack/react-router";
import { LingoProvider } from "@lingo.dev/compiler/react";
import { routeTree } from "./routeTree.gen";

const router = createRouter({ routeTree });

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <RouterProvider router={router} />
    </LingoProvider>
  </StrictMode>
);

이렇게 하면 라우팅된 컴포넌트 전체에서 번역을 사용할 수 있으며 코드 분할로 인해 컨텍스트가 손상되지 않습니다.

React Router 통합

React Router v6/v7의 경우:

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </LingoProvider>
  </StrictMode>
);

HMR 및 개발

컴파일러는 Vite의 Hot Module Replacement(HMR)를 완벽하게 지원합니다. 번역 가능한 텍스트를 업데이트하면:

  1. 컴파일러가 변경 사항을 감지합니다
  2. 번역 서버가 새로운 번역(또는 의사 번역)을 생성합니다
  3. HMR이 전체 리로드 없이 컴포넌트를 업데이트합니다
  4. 컴포넌트 상태가 유지됩니다

Fast Refresh는 정상적으로 작동합니다—컴파일러는 Vite의 HMR을 방해하지 않습니다.

빌드 구성

개발 빌드

{
  dev: {
    usePseudotranslator: true, // Fast fake translations
  }
}

의사 번역을 통한 즉각적인 피드백을 위해 npm run dev를 실행하세요.

프로덕션 빌드

{
  buildMode: "cache-only", // Use pre-generated translations
}

npm run build를 실행하세요. 번역은 .lingo/metadata.json에서 가져오므로 API 호출이 필요하지 않습니다.

모범 사례: 프로덕션 빌드 전에 CI에서 실제 번역을 생성하세요. 빌드 모드를 참조하세요.

코드 분할

컴파일러는 Vite의 코드 분할을 준수합니다. 각 지연 로드된 청크에는 필요한 번역만 포함됩니다.

// Lazy-loaded route
const Dashboard = lazy(() => import("./pages/Dashboard"));

// Dashboard component's translations are bundled with the Dashboard chunk

번역은 자동으로 트리 셰이킹됩니다—사용된 번역만 각 청크에 포함됩니다.

TypeScript

컴파일러는 완전히 타입이 지정되어 있습니다:

import type { LingoConfig } from "@lingo.dev/compiler";

const config: LingoConfig = {
  sourceRoot: "src",
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
};

환경 변수

API 키에 Vite의 환경 변수 시스템을 사용하세요:

# .env
VITE_LINGO_API_KEY=your_key_here

설정에서 접근:

{
  models: "lingo.dev",
  // API key is automatically read from LINGODOTDEV_API_KEY env variable
}

API 키를 절대 커밋하지 마세요. .gitignore에 .env를 추가하세요.

일반적인 문제

"Cannot find module '@lingo.dev/compiler/react'" 패키지가 설치되어 있는지 확인하세요: pnpm install @lingo.dev/compiler

LingoProvider 추가 후 HMR이 중단됨 Vite 설정에서 lingoCompilerPlugin가 react() 플러그인보다 앞에 배치되어 있는지 확인하세요.

프로덕션에서 번역이 표시되지 않음 buildMode: "cache-only"와 .lingo/metadata.json에 모든 로케일에 대한 번역이 있는지 확인하세요.

코드 분할로 인한 컨텍스트 손실 LingoProvider가 라우터 프로바이더(TanStack Router, React Router 등)보다 위에 배치되어 있는지 확인하세요. 그렇지 않으면 코드 분할된 라우트에서 컨텍스트가 손실될 수 있습니다.

포트 60000이 이미 사용 중 번역 서버는 사용 가능한 포트(60000-60099)를 자동으로 찾습니다. 모두 사용 중인 경우 수동으로 구성하세요:

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

다음 단계