이메일 로컬라이제이션

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

방식 선택하기#

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

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

번역할 이메일 카피가 리포지토리 안의 리소스 파일에 있다면 빌드 타임 방식을 사용하세요. 이메일 콘텐츠가 동적으로 생성되거나 이메일 서비스 제공업체에 저장되어 있다면 런타임 방식을 사용하세요.

사전 준비#

모든 번역은 적용할 LLM 모델, 용어집, 브랜드 보이스, 규칙을 결정하는 설정인 로컬라이제이션 엔진을 거칩니다. 먼저 Lingo.dev 대시보드에서 엔진을 만든 뒤, CLI를 설치하고 인증하세요:

bash

npm install -g @lingo.dev/cli
lingo login

CLI를 사용하려면 Node 22+가 필요합니다. CI에서는 LINGO_API_KEY를 실행하는 대신 lingo login를 설정하세요.

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

CLI는 JSON 리소스 파일에 담긴 이메일 콘텐츠를 번역합니다. 번역할 카피를 JSON으로 추출한 뒤 CLI가 해당 파일을 가리키도록 설정하면, 소스 파일과 나란히 로캘별 파일이 생성됩니다.

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

설정을 스캐폴딩하려면 lingo init를 실행하고, 조직과 엔진을 연결하려면 lingo link를 실행하세요. 그러면 생성되는 .lingo/config.json는 다음과 같습니다:

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "emails/locales/en.json" }]
}

로캘은 경로에 포함됩니다. CLI는 패턴 안의 소스 로캘을 각 대상 로캘로 바꾸므로, emails/locales/en.json를 사용하면 emails/locales/es.json, emails/locales/fr.json 등이 생성됩니다. .lingo/config.json를 리포지토리에 커밋하세요.

첫 실행에서는 모든 로캘을 번역하고, 이후에는 변경된 내용만 번역하세요:

bash

lingo push --backfill-missing   # first run / new locale
lingo push                      # delta on later runs

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

가장 최근 push 실행 결과를 언제든 가져오려면 lingo pull를 사용하세요. 변경 사항을 기록하지 않고 번역이 최신 상태인지 확인하려면(예: CI) lingo check를 사용하세요.

런타임 로컬라이제이션#

이메일 콘텐츠가 동적인 경우 - 개인화 알림, 사용자 생성 콘텐츠 요약, 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

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

GitHub App

모든 pull request에서 이메일 템플릿 번역을 자동화하세요

방식 선택하기#

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

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

사전 준비#

bash

npm install -g @lingo.dev/cli
lingo login

CLI를 사용하려면 Node 22+가 필요합니다. CI에서는 LINGO_API_KEY를 실행하는 대신 lingo login를 설정하세요.

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

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "emails/locales/en.json" }]
}

첫 실행에서는 모든 로캘을 번역하고, 이후에는 변경된 내용만 번역하세요:

bash

lingo push --backfill-missing   # first run / new locale
lingo push                      # delta on later runs

런타임 로컬라이제이션#

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

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

GitHub App

모든 pull request에서 이메일 템플릿 번역을 자동화하세요