Vite + React

알파

Lingo.dev Compiler는 현재 알파 단계입니다. 아직 안정적이지 않아 프로덕션 환경에서의 사용은 권장되지 않으며, 릴리스마다 API가 변경될 수 있습니다.

Lingo.dev Compiler는 lingoCompilerPlugin을 통해 Vite와 통합됩니다. 이 Vite 플러그인은 빌드 시점에 React 컴포넌트를 변환해 번역을 주입하며, 완전한 Hot Module Replacement를 지원하므로 개발 중에도 번역이 즉시 반영됩니다.

사전 요구 사항#

요구 사항

React와 함께 사용하는 Vite 5+
Node.js 18+
@lingo.dev/compiler 설치

설치#

bash

pnpm install @lingo.dev/compiler

vite.config.ts 구성#

Vite 설정에 lingoCompilerPlugin을 추가하세요. 이 플러그인은 반드시 react() 플러그인 앞에 배치해야 합니다. 컴파일러가 React 플러그인이 JSX를 처리하기 전에 먼저 JSX를 변환해야 하기 때문입니다.

// 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", "ja"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

플러그인 순서가 중요합니다

lingoCompilerPlugin이 react() 뒤에 있으면 React 플러그인이 JSX를 먼저 처리하게 되어, 컴파일러가 번역 가능한 텍스트를 식별할 수 없습니다. plugins 배열에서는 항상 Lingo 플러그인을 가장 먼저 배치하세요.

LingoProvider 추가#

엔트리 파일에서 애플리케이션 루트를 LingoProvider으로 감싸세요:

tsx

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

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

LingoProvider은 로캘 컨텍스트를 초기화하고, 현재 활성 로캘에 맞는 번역 사전을 불러옵니다.

Hot Module Replacement#

이 플러그인은 Vite의 HMR 시스템과 통합됩니다. 컴포넌트에서 번역 가능한 텍스트를 수정하면 다음과 같이 동작합니다.

원본 텍스트 수정

JSX 안의 텍스트를 변경하세요. 예를 들어 제목을 "환영합니다"에서 "다시 오신 것을 환영합니다"로 바꿀 수 있습니다.

컴파일러가 변경 사항 감지

플러그인이 HMR 업데이트를 가로채 변경된 문자열을 식별하고, 새 번역을 생성합니다(개발 모드에서는 의사 번역).

브라우저에 즉시 반영

전체 페이지를 새로고침하지 않아도 번역된 컴포넌트가 다시 렌더링됩니다. .lingo/metadata.json의 번역 메타데이터도 디스크에 업데이트됩니다.

sourceRoot 구성#

sourceRoot 옵션은 컴파일러가 번역 가능한 텍스트를 찾기 위해 어떤 파일을 스캔할지 결정합니다. 일반적인 Vite + React 프로젝트라면 다음을 권장합니다.

{
  sourceRoot: "src",
}

프로젝트 구조	권장 sourceRoot
표준 (`src/`)	`"src"`
공유 패키지가 있는 모노레포	`"."` (프로젝트 루트)
사용자 지정 디렉터리	컴포넌트 디렉터리 경로

대규모 코드베이스에서는 범위를 좁게 잡은 sourceRoot이 빌드 시간을 줄이는 데 도움이 됩니다. 특정 파일에서만 번역이 필요하다면 useDirective: true을 활성화하고 해당 파일에 'use i18n'을 추가하세요. 자세한 내용은 Project Structure를 참고하세요.

예제 프로젝트 구조#

text

my-vite-app/
  src/
    main.tsx          # LingoProvider wraps <App />
    App.tsx           # Translatable components
    components/
      Header.tsx      # Automatically scanned
      Footer.tsx      # Automatically scanned
  .lingo/
    metadata.json     # Translation cache (commit this)
  vite.config.ts      # lingoCompilerPlugin configured here

다음 단계#

Setup

인증을 포함한 전체 설정 가이드

Configuration Reference

알파