Next.js 연동

알파

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

Lingo.dev Compiler는 withLingo() 설정 래퍼를 통해 Next.js App Router에 연동되며, 빌드 파이프라인을 변환해 로캘별 번들을 생성합니다. 컴포넌트 코드를 수정하지 않아도 React Server Components, Webpack, Turbopack을 모두 지원합니다.

사전 준비#

요구 사항

App Router를 사용하는 Next.js 14+
Node.js 18+
@lingo.dev/compiler 설치 완료

설치#

bash

pnpm install @lingo.dev/compiler

next.config.ts 설정#

Next.js 설정을 withLingo로 감싸세요. 설정 함수는 반드시 async여야 합니다. 이는 withLingo가 빌드 중 비동기 초기화를 수행하기 때문입니다.

// next.config.ts
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, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true,
    },
  });
}

비동기 설정 필수

설정은 일반 객체가 아니라 async 함수로 export해야 합니다. 일반 객체를 export하면 Compiler를 초기화할 수 없어 빌드가 실패합니다. 자세한 내용은 Troubleshooting을 참고하세요.

LingoProvider 추가#

컴포넌트 트리 전반에서 로캘 컨텍스트를 활성화하려면 루트 레이아웃을 LingoProvider로 감싸세요:

tsx

// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

LingoProvider는 로캘 확인, 유지, 사전 로드를 처리합니다. Server Components와 Client Components 모두에서 동작합니다.

Server Components와 Client Components#

Compiler는 두 컴포넌트 유형을 모두 투명하게 처리합니다:

컴포넌트 유형	번역 방식
React Server Components	번역은 요청 시 서버에서 처리됩니다. 클라이언트 측 JS 오버헤드가 없습니다.
Client Components (`"use client"`)	번역은 클라이언트 청크에 번들됩니다. 로캘 전환에는 `useLingoContext()`를 사용할 수 있습니다.
공유 컴포넌트	두 환경 모두에서 동작합니다. Compiler가 렌더링 환경을 자동으로 감지합니다.

tsx

// app/page.tsx - Server Component (default)
export default function Home() {
  return <h1>Welcome to our app</h1>;
  // Renders translated text with zero client JS
}

tsx

// app/components/greeting.tsx - Client Component
"use client";

export function Greeting() {
  return <p>Hello, world</p>;
  // Translations included in client bundle
}

번들러 지원#

withLingo() 래퍼는 Next.js가 지원하는 두 번들러 모두에서 동작합니다:

번들러	지원 범위	참고
Webpack	완전 지원	기본 번들러입니다. 추가 설정이 필요하지 않습니다.
Turbopack	완전 지원	`next dev --turbopack`로 활성화하세요. Compiler가 Turbopack을 자동으로 감지합니다.

sourceRoot 설정#

sourceRoot 옵션은 번역 가능한 컴포넌트가 들어 있는 디렉터리를 Compiler에 알려줍니다. Next.js App Router 프로젝트에서는 일반적으로 ./app를 사용합니다:

{
  sourceRoot: "./app",
}

./app 밖에 컴포넌트가 있다면(예: 공용 components/ 디렉터리) sourceRoot를 공통 상위 디렉터리로 설정하세요:

{
  sourceRoot: ".",
}

sourceRoot 범위가 넓을수록 더 많은 파일을 스캔하게 됩니다. 대규모 프로젝트라면 빌드 시간을 줄이기 위해 가능한 한 범위를 좁게 유지하세요. 또는 useDirective: true를 사용하고 번역이 필요한 파일에만 'use i18n'를 추가할 수도 있습니다. 자세한 내용은 Project Structure를 참고하세요.

다음 단계#

알파