"use i18n";

"use i18n" 지시어는 기존 코드를 리팩토링하지 않고도 React 컴포넌트의 파일별 현지화를 가능하게 합니다. "use client" 또는 "use server"와 마찬가지로, 파일 상단에 이 지시어를 추가하기만 하면 해당 컴포넌트의 모든 번역 가능한 콘텐츠가 자동으로 현지화됩니다.

이 접근 방식은 대규모 코드베이스에 최소한의 위험과 최대한의 유연성으로 다국어 지원을 점진적으로 추가하는 데 완벽합니다.

작동 방식

React 파일 상단에 "use i18n"을 추가하면, Lingo.dev 컴파일러는 자동으로 다음을 수행합니다:

  1. 파일 전체를 스캔하여 번역 가능한 콘텐츠 식별
  2. JSX 텍스트와 번역 가능한 속성 추출
  3. 구성된 AI 모델을 사용하여 번역 생성
  4. 빌드 시 현지화된 버전 주입
  5. 원활한 개발을 위한 핫 모듈 교체(HMR) 유지

이 지시어는 파일 수준에서 작동하여 해당 컴포넌트의 경계 내에서 모든 것을 처리하면서 앱의 나머지 부분은 변경하지 않습니다.

지시어 활성화

"use i18n" 지시문을 사용하려면 컴파일러 구성에서 이를 활성화하세요:

{
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  useDirective: true, // "use i18n" 지시문 활성화
  models: "lingo.dev", // 옵션 1: Lingo.dev 엔진
  // models: {
  //   "*:*": "groq:qwen/qwen3-32b", // 옵션 2: GROQ
  //   "*:*": "google:gemini-2.0-flash", // 옵션 2: Google AI
  //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // 옵션 2: OpenRouter
  //   "*:*": "ollama:mistral-small3.1", // 옵션 2: Ollama
  //   "*:*": "mistral:mistral-small-latest", // Mistral
  // },
}

참고: useDirective가 false로 설정된 경우(기본값), Lingo.dev 컴파일러는 모든 파일을 상단에 "use i18n"이 있는 것처럼 처리합니다. useDirective: true로 설정하면 파일별로 지역화할 수 있는 세밀한 제어가 가능합니다.

모델 구성: Lingo.dev 엔진을 간소화된 구문(models: "lingo.dev")으로 사용하거나 대체 LLM 제공업체의 모델을 특정 모델 매핑(예: models: { "*:*": "groq:qwen/qwen3-32b" }, 위 참조)과 함께 사용할 수 있습니다. 엔진은 각 언어 쌍에 대해 최적의 모델을 자동으로 선택합니다.

기본 사용법

React 컴포넌트 파일 상단에 지시어를 추가하세요:

"use i18n";

import React from "react";

export function WelcomeCard() {
  return (
    <div className="card">
      <h2>Welcome to our app!</h2>
      <p>
        Get started by exploring our features and discovering what makes our
        platform special.
      </p>
      <button>Get Started</button>
    </div>
  );
}

참고: <LingoProvider>를 렌더링하는 파일 상단에 "use i18n"을 추가하세요.

이게 전부입니다! 이제 컴포넌트는 코드 변경 없이 사용자가 선택한 언어로 자동 렌더링됩니다.

기존 지시어와 함께 작동

'"use i18n"' 지시어는 이미 사용 중인 다른 React 지시어와 자연스럽게 함께 작동합니다:

"use client";
"use i18n";

export function InteractiveComponent() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h1>클릭 카운터</h1>
      <p>{count}번 클릭했습니다</p>
      <button onClick={() => setCount(count + 1)}>클릭하세요!</button>
    </div>
  );
}

"use server";
"use i18n";

export async function ServerComponent() {
  const data = await fetchData();

  return (
    <div>
      <h1>서버 렌더링 콘텐츠</h1>
      <p>이 콘텐츠는 서버에서 렌더링되고 빌드 시점에 현지화됩니다</p>
    </div>
  );
}

컴파일러는 모든 지시어를 함께 지능적으로 처리하여 현지화를 추가하면서 컴포넌트의 의도된 동작을 유지합니다.

개발 워크플로우

1. 점진적 마이그레이션

개별 컴포넌트에 지시어를 추가하는 것으로 시작하세요:

// 이전: 영어 전용 컴포넌트
export function Header() {
  return <h1>My Application</h1>;
}

// 이후: 한 줄로 다국어 컴포넌트 구현
("use i18n");

export function Header() {
  return <h1>My Application</h1>;
}

2. 핫 모듈 교체(HMR)

이 지시어는 HMR과 원활하게 작동합니다. "use i18n"이 있는 컴포넌트의 텍스트를 수정하면 번역이 브라우저에서 즉시 업데이트됩니다:

"use i18n";

export function StatusMessage() {
  return (
    <div>
      {/* 이 텍스트를 변경하면 모든 언어에서 즉시 업데이트되는 것을 확인할 수 있습니다 */}
      <p>변경 사항이 성공적으로 저장되었습니다!</p>
    </div>
  );
}

3. 파일별 접근 방식

점진적으로 현지화하려는 대규모 코드베이스에 적합합니다:

src/
├── components/
│   ├── Header.tsx          // ✅ "use i18n" - 현지화됨
│   ├── Navigation.tsx      // ✅ "use i18n" - 현지화됨
│   ├── ProductCard.tsx     // ✅ "use i18n" - 현지화됨
│   ├── Footer.tsx          // ⏳ 아직 현지화되지 않음
│   └── Sidebar.tsx         // ⏳ 아직 현지화되지 않음

이점

"use i18n" 지시어는 React 컴포넌트에 단 한 줄만 추가하여 현지화를 간단하게 만들어주며, 점진적인 현지화가 필요한 성숙한 프로젝트를 위해 설계되었습니다.

다음 단계