"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: {
    "*:*": "groq:mistral-saba-24b",
  }
}

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

기본 사용법

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>
  );
}

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

기존 지시어와 함께 작동

'"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 컴포넌트에 단 한 줄만 추가하여 현지화를 간단하게 만들어주며, 점진적인 현지화가 필요한 성숙한 프로젝트를 위해 설계되었습니다.

다음 단계