모범 사례

알파

Lingo.dev Compiler는 현재 알파 버전입니다. 안정적이지 않으며 프로덕션 사용은 권장되지 않고, API는 릴리스마다 변경될 수 있습니다.

이 가이드는 Lingo.dev Compiler로 안정적이면서도 비용 효율적인 결과를 얻는 데 효과적인 패턴을 바탕으로 정리했습니다. 빌드 파이프라인, 코드 구성, 번역 품질, 테스트를 다룹니다.

빌드 파이프라인#

3단계 모드 전략을 사용하세요#

개발 - pseudotranslator

즉각적인 피드백을 위해 dev.usePseudotranslator: true를 활성화하세요. API 호출도 없고 비용도 들지 않으며 결과를 바로 확인할 수 있습니다. 의사 번역은 번역되지 않은 문자열을 찾고 레이아웃을 점검하는 데 유용합니다.

{
  buildMode: "translate",
  dev: { usePseudotranslator: true },
}

CI - 번역 모드

buildMode: "translate"와 실제 제공업체를 함께 사용해 실행하세요. 프로덕션에서 번역을 사용할 수 있도록, 매번 CI 실행 후 업데이트된 .lingo/metadata.json를 커밋하세요.

bash

LINGO_BUILD_MODE=translate npm run build

프로덕션 - cache-only 모드

buildMode: "cache-only"로 배포하세요. 프로덕션에서는 API 키가 필요하지 않습니다. 빌드는 결정적이고 빠릅니다.

bash

LINGO_BUILD_MODE=cache-only npm run build

버전 관리#

.lingo/를 리포지토리에 커밋하세요#

.lingo/metadata.json 파일은 캐시된 모든 번역의 기준이 되는 소스입니다. cache-only 모드의 프로덕션 빌드는 이 파일에 의존합니다.

gitignore

# .gitignore - do NOT ignore .lingo/
node_modules/
dist/
.env

.lingo/metadata.json를 커밋하지 않으면 cache-only 모드에서 읽을 번역이 없기 때문에 프로덕션 빌드가 실패합니다.

번역 diff를 검토하세요#

CI가 업데이트된 번역을 커밋하면 pull request에서 .lingo/metadata.json diff를 검토하세요. 코드 변경 사항을 검토하듯, 번역 문제가 프로덕션에 반영되기 전에 미리 발견할 수 있습니다.

코드 구성#

번역할 텍스트는 JSX에 직접 배치하세요#

Compiler는 번역 가능한 콘텐츠를 찾기 위해 JSX를 스캔합니다. JavaScript 변수, 상수, 외부 파일에 저장된 텍스트는 감지되지 않습니다:

tsx

// Good - compiler detects this text
export function Header() {
  return <h1>Welcome to our app</h1>;
}

// Bad - compiler cannot detect text in a variable
const title = "Welcome to our app";
export function Header() {
  return <h1>{title}</h1>;
}

대규모 코드베이스에는 useDirective를 사용하세요#

규모가 큰 프로젝트에서는 모든 파일을 스캔할수록 빌드 시간이 늘어납니다. useDirective: true를 활성화하고, 사용자에게 보이는 텍스트가 들어 있는 파일에만 'use i18n'를 추가하세요:

{
  useDirective: true,
}

tsx

'use i18n';

// Only this file is scanned for translations
export function PublicPage() {
  return <h1>Welcome</h1>;
}

sourceRoot 범위는 최대한 좁게 유지하세요#

번역 가능한 컴포넌트가 들어 있는 가장 작은 디렉터리로 sourceRoot를 설정하세요. 범위가 넓은 sourceRoot는 불필요한 파일까지 스캔하게 됩니다:

프로젝트 유형	권장 sourceRoot
Next.js App Router	`"./app"`
Vite + React	`"src"`
Monorepo (useDirective 사용 시)	`"."`

번역 품질#

브랜드 용어에는 manual overrides를 사용하세요#

브랜드명, 제품명, 법률 문구는 AI 번역에 맡기기보다 manual overrides를 사용해야 합니다:

tsx

<h1 data-lingo-override={{ es: "Motor de Localizacion", de: "Lokalisierungs-Engine" }}>
  Localization Engine
</h1>

비용 최적화를 위해 로캘 쌍 매핑을 활용하세요#

모델마다 강점과 가격대가 다릅니다. 고가 모델은 꼭 필요한 언어에 매핑하고, 나머지에는 비용 효율적인 모델을 사용하세요:

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",      // Fast, cost-effective default
    "*:ja": "anthropic:claude-3-5-sonnet",       // Higher quality for Japanese
    "*:zh-Hans": "anthropic:claude-3-5-sonnet",  // Higher quality for Chinese
  },
}

{
  pluralization: { enabled: false },
}

count에 따라 달라지는 텍스트는 자연스럽게 작성하세요#

복수형 처리가 활성화되어 있다면 숫자 변수와 함께 쓰이는 텍스트를 자연스럽게 작성하세요. Compiler가 ICU MessageFormat 변환을 처리합니다:

tsx

// Good - the compiler detects and pluralizes this
<p>You have {count} items in your cart</p>

// Also good - works with any numeric expression
<p>{unreadCount} unread messages</p>

테스트#

먼저 pseudotranslator로 테스트하세요#

실제 번역을 생성하기 전에 pseudotranslator로 실행해 전체 적용 범위를 확인하세요:

dev.usePseudotranslator: true를 활성화하세요
모든 페이지와 컴포넌트를 둘러보세요
[!!! ... !!!] 표시가 없는 텍스트는 번역되지 않고 있는 것입니다
텍스트 배치 문제를 수정하세요(JSX로 텍스트 이동, sourceRoot 조정, 'use i18n' 지시어 추가)

pseudotranslator로 번역되지 않은 문자열을 미리 찾아내면, 실제 번역을 생성한 뒤 발견하는 것보다 훨씬 빠르고 비용도 적게 듭니다.

출시 전에 실제 번역으로 테스트하세요#

출시 전에 pseudotranslator를 비활성화하고, 최소 하나의 대상 로캘에 대해 실제 번역을 생성하세요:

{
  dev: { usePseudotranslator: false },
}

pseudotranslation으로는 드러나지 않는 레이아웃 넘침, 텍스트 잘림, 양방향 텍스트 문제를 확인하세요.

다음 단계#

Pseudotranslator와 번역 서버

문제 해결

자주 발생하는 문제와 해결 방법

알파

Lingo.dev Compiler는 현재 알파 버전입니다. 안정적이지 않으며 프로덕션 사용은 권장되지 않고, API는 릴리스마다 변경될 수 있습니다.

빌드 파이프라인#

3단계 모드 전략을 사용하세요#

개발 - pseudotranslator

{
  buildMode: "translate",
  dev: { usePseudotranslator: true },
}

CI - 번역 모드

bash

LINGO_BUILD_MODE=translate npm run build

프로덕션 - cache-only 모드

buildMode: "cache-only"로 배포하세요. 프로덕션에서는 API 키가 필요하지 않습니다. 빌드는 결정적이고 빠릅니다.

bash

LINGO_BUILD_MODE=cache-only npm run build

버전 관리#

.lingo/를 리포지토리에 커밋하세요#

.lingo/metadata.json 파일은 캐시된 모든 번역의 기준이 되는 소스입니다. cache-only 모드의 프로덕션 빌드는 이 파일에 의존합니다.

gitignore

# .gitignore - do NOT ignore .lingo/
node_modules/
dist/
.env

.lingo/metadata.json를 커밋하지 않으면 cache-only 모드에서 읽을 번역이 없기 때문에 프로덕션 빌드가 실패합니다.

// Good - compiler detects this text
export function Header() {
  return <h1>Welcome to our app</h1>;
}

// Bad - compiler cannot detect text in a variable
const title = "Welcome to our app";
export function Header() {
  return <h1>{title}</h1>;
}

대규모 코드베이스에는 useDirective를 사용하세요#

{
  useDirective: true,
}

tsx

'use i18n';

// Only this file is scanned for translations
export function PublicPage() {
  return <h1>Welcome</h1>;
}

sourceRoot 범위는 최대한 좁게 유지하세요#

번역 가능한 컴포넌트가 들어 있는 가장 작은 디렉터리로 sourceRoot를 설정하세요. 범위가 넓은 sourceRoot는 불필요한 파일까지 스캔하게 됩니다:

프로젝트 유형	권장 sourceRoot
Next.js App Router	`"./app"`
Vite + React	`"src"`
Monorepo (useDirective 사용 시)	`"."`

번역 품질#

브랜드 용어에는 manual overrides를 사용하세요#

브랜드명, 제품명, 법률 문구는 AI 번역에 맡기기보다 manual overrides를 사용해야 합니다:

tsx

<h1 data-lingo-override={{ es: "Motor de Localizacion", de: "Lokalisierungs-Engine" }}>
  Localization Engine
</h1>

비용 최적화를 위해 로캘 쌍 매핑을 활용하세요#

모델마다 강점과 가격대가 다릅니다. 고가 모델은 꼭 필요한 언어에 매핑하고, 나머지에는 비용 효율적인 모델을 사용하세요:

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",      // Fast, cost-effective default
    "*:ja": "anthropic:claude-3-5-sonnet",       // Higher quality for Japanese
    "*:zh-Hans": "anthropic:claude-3-5-sonnet",  // Higher quality for Chinese
  },
}

{
  pluralization: { enabled: false },
}

count에 따라 달라지는 텍스트는 자연스럽게 작성하세요#

복수형 처리가 활성화되어 있다면 숫자 변수와 함께 쓰이는 텍스트를 자연스럽게 작성하세요. Compiler가 ICU MessageFormat 변환을 처리합니다:

tsx

// Good - the compiler detects and pluralizes this
<p>You have {count} items in your cart</p>

// Also good - works with any numeric expression
<p>{unreadCount} unread messages</p>

테스트#

먼저 pseudotranslator로 테스트하세요#

실제 번역을 생성하기 전에 pseudotranslator로 실행해 전체 적용 범위를 확인하세요:

dev.usePseudotranslator: true를 활성화하세요
모든 페이지와 컴포넌트를 둘러보세요
[!!! ... !!!] 표시가 없는 텍스트는 번역되지 않고 있는 것입니다
텍스트 배치 문제를 수정하세요(JSX로 텍스트 이동, sourceRoot 조정, 'use i18n' 지시어 추가)

pseudotranslator로 번역되지 않은 문자열을 미리 찾아내면, 실제 번역을 생성한 뒤 발견하는 것보다 훨씬 빠르고 비용도 적게 듭니다.

출시 전에 실제 번역으로 테스트하세요#

출시 전에 pseudotranslator를 비활성화하고, 최소 하나의 대상 로캘에 대해 실제 번역을 생성하세요:

{
  dev: { usePseudotranslator: false },
}

pseudotranslation으로는 드러나지 않는 레이아웃 넘침, 텍스트 잘림, 양방향 텍스트 문제를 확인하세요.

다음 단계#

Pseudotranslator와 번역 서버

문제 해결

자주 발생하는 문제와 해결 방법