---
title: '"use i18n";'
---

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

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

## 작동 방식

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

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

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

## 지시어 활성화

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

```js
{
  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 엔진](/compiler/how-it-works#option-1-lingodev-engine)을 간소화된 구문(`models: "lingo.dev"`)으로 사용하거나 [대체 LLM 제공업체](/compiler/how-it-works#option-2-alternative-llm-providers)의 모델을 특정 모델 매핑(예: `models: { "*:*": "groq:qwen/qwen3-32b" }`, 위 참조)으로 사용할 수 있습니다. 엔진은 각 언어 쌍에 최적의 모델을 자동으로 선택합니다.

## 기본 사용법

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

```tsx
"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 지시어와 자연스럽게 함께 작동합니다:

```tsx
"use client";
"use i18n";

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

  return (
    <div>
      <h1>Click Counter</h1>
      <p>You've clicked {count} times</p>
      <button onClick={() => setCount(count + 1)}>Click me!</button>
    </div>
  );
}
```

```tsx
"use server";
"use i18n";

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

  return (
    <div>
      <h1>Server-rendered Content</h1>
      <p>This content is rendered on the server and localized at build time</p>
    </div>
  );
}
```

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

## 개발 워크플로우

### 1. 점진적 마이그레이션

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

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

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

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

### 2. 핫 모듈 교체(HMR)

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

```tsx
"use i18n";

export function StatusMessage() {
  return (
    <div>
      {/* 이 텍스트를 변경하면 모든 언어에서 즉시 업데이트되는 것을 확인할 수 있습니다 */}
      <p>Your changes have been saved successfully!</p>
    </div>
  );
}
```

### 3. 파일별 접근 방식

점진적으로 현지화하고 싶은 대규모 코드베이스에 완벽합니다:

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

## 이점

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

## 다음 단계

- **빠른 시작**: [Lingo.dev 컴파일러 시작하기](/compiler/quick-start)
- **작동 방식**: [빌드 타임 처리 이해하기](/compiler/how-it-works)
- **프레임워크 통합**: [플랫폼별 가이드](/compiler/frameworks/nextjs-app-router)
- **고급 구성**: [커스터마이징 옵션](/compiler/configuration/advanced)
