이메일 로컬라이제이션

Lingo.dev CLI와 localization API는 이메일 로컬라이제이션을 위한 두 가지 방식을 지원합니다. 빌드 시점에 템플릿 파일을 번역해 로캘별 템플릿을 배포하거나, 발송 전에 런타임에서 콘텐츠를 번역할 수 있습니다. 두 방식 모두 용어집 규칙, 브랜드 보이스, 모델 선택이 자동으로 적용되도록 설정된 로컬라이제이션 엔진을 통해 실행됩니다.

방식 선택하기#

방식	적합한 용도	작동 방식
빌드 시점 (CLI)	템플릿 파일 - react-email, MJML, HTML	리포지토리의 파일을 번역한 뒤 로캘별 템플릿으로 배포
런타임 (API)	동적 콘텐츠, ESP에서 렌더링되는 템플릿	발송 전에 localization API를 호출하고, 번역된 콘텐츠를 이메일 제공업체에 전달

어떤 방식을 선택해야 하나요?

이메일 템플릿이 파일(HTML, MJML, React 컴포넌트) 형태로 리포지토리에 있다면 빌드 시점 방식을 사용하세요. 이메일 콘텐츠가 동적으로 생성되거나 이메일 서비스 제공업체에 저장되어 있다면 런타임 방식을 사용하세요.

사전 준비#

모든 번역은 어떤 LLM 모델, 용어집, 브랜드 보이스, 지침을 적용할지 결정하는 설정인 로컬라이제이션 엔진을 거칩니다. Lingo.dev 대시보드에서 엔진을 만들고 API key를 생성하세요.

빌드 시점 로컬라이제이션#

CLI는 이메일 템플릿 파일을 직접 번역합니다. 템플릿 형식에 맞는 버킷을 설정한 뒤 CLI를 실행하면, 원본 템플릿 옆에 로캘별 템플릿 파일이 생성됩니다.

react-email 템플릿은 HTML로 렌더링되는 React 컴포넌트입니다. react-i18next 같은 i18n 라이브러리를 사용해 번역 가능한 문자열을 JSON 리소스 파일로 추출한 다음, CLI로 해당 JSON 파일을 번역하세요.

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["emails/locales/[locale].json"]
    }
  }
}

렌더링 시점에는 이메일 컴포넌트에 로캘을 전달하고 해당 JSON 파일을 불러오세요. react-email의 render() 함수가 바로 발송 가능한 로캘별 HTML을 생성합니다.

다음과 같이 번역을 실행하세요:

bash

npx lingo.dev@latest run

런타임 로컬라이제이션#

이메일 콘텐츠가 동적인 경우 - 개인화 알림, 사용자 생성 콘텐츠 요약, CMS에 저장된 마케팅 카피 등 - 발송 전에 런타임에서 번역하세요. 이 방식은 Translation API guide에 설명된 패턴을 기반으로 합니다.

javascript

async function sendLocalizedEmail(userId, templateId, content) {
  const user = await db.users.findById(userId);

  const response = await fetch("https://api.lingo.dev/process/localize", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGODOTDEV_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      engineId: "eng_abc123",
      sourceLocale: "en",
      targetLocale: user.locale,
      data: {
        subject: content.subject,
        preheader: content.preheader,
        body: content.body,
      },
    }),
  });

  const { data } = await response.json();

  await emailProvider.send({
    to: user.email,
    subject: data.subject,
    html: renderTemplate(templateId, data),
  });
}

모범 사례#

영역	권장 사항
제목	50자 이내로 유지하세요. 브랜드명이 번역되지 않도록 glossary를 사용하세요.
미리보기 텍스트	본문과는 별도로 번역하세요. 이메일 클라이언트에서 독립적으로 표시됩니다.
브랜드 보이스	로컬라이제이션 엔진에서 로캘별 톤을 설정하세요. 일본어 마케팅 이메일에는 독일어와 다른 문체가 필요합니다.
RTL 언어	아랍어, 히브리어, 페르시아어는 이메일 클라이언트에서 렌더링 결과를 테스트하세요. HTML `dir="rtl"` 처리는 클라이언트마다 다를 수 있습니다.
키 잠금	번역되면 안 되는 URL, 제품명, 법적 식별자에는 locked keys를 사용하세요.

다음 단계#

Translation API

API를 통한 런타임 로컬라이제이션 전체 가이드

Brand Voices

대상 로캘별 톤과 격식을 설정하세요

Glossaries

어떤 용어를 번역하고 어떤 용어는 그대로 둘지 제어하세요

CI/CD 워크플로

푸시할 때마다 이메일 템플릿 번역을 자동화하세요