이메일 현지화하기
제목, 프리헤더, 본문을 함께 번역한 뒤 수신자의 로캘과 템플릿 값을 적용해 완성된 메시지를 렌더링하세요.
이메일은 독자가 열어 보기 전부터 메시지를 전달합니다. 제목과 프리헤더가 건넨 약속은 본문과 버튼, 치환된 값에서도 같은 언어로 이어져야 합니다. 번역 원문에서 이 요소들을 함께 관리하고, 모두 동일한 수신자 로캘로 렌더링하세요.
반복적으로 사용하는 트랜잭션 이메일 템플릿은 발송 전에 카탈로그를 번역하세요. 그러면 발송 시스템이 승인된 카탈로그를 불러와 새 번역 생성을 기다리지 않고 메시지를 렌더링할 수 있습니다. 콘텐츠를 미리 준비할 수 없다면 런타임 번역이 유용합니다. 다만 이 방식에는 명확한 실패 처리 및 발송 정책이 필요하며, 자세한 내용은 아래에서 설명합니다.
문구를 수신자 및 발송 데이터와 분리하기 #
다음과 같은 문구를 담아 emails/locales/en.json을 만드세요.
{
"subject": "Your order is on its way",
"preheader": "Track delivery for order {orderNumber}.",
"heading": "Your order has shipped",
"body": "Hello {name}, your order will arrive within {days} business days.",
"cta": "Track your order",
"footer": "You received this message because you placed an order."
}템플릿에서 name, orderNumber, days, 추적 URL을 제공합니다. 번역 원문에 수신자 데이터를 포함하지 않으면 주문마다 같은 메시지를 다시 생성하거나 비공개 값을 불필요하게 전송하지 않아도 됩니다. 개인정보가 문구에 영향을 준다면, 제출 전에 해당 정보를 번역 서비스에 제공해도 되는지 확인하세요.
기존 렌더러와 호환되는 플레이스홀더 구문을 사용하세요. JSON 번역이 템플릿 언어를 정해 주지는 않습니다. 수신자와의 관계, 배송 약속, 반드시 포함해야 할 법적 문구에 관한 맥락을 제공하세요. 이 예시에서 “도착합니다”는 약속을 뜻하므로, 문체를 다듬는 과정에서 단순한 가능성으로 의미가 약해져서는 안 됩니다.
카탈로그 번역하기 #
프로젝트 루트에서 현재 CLI를 초기화하세요.
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'emails/locales/en.json' --yes
lingo link
lingo push --backfill-missing --wait사용할 조직과 로컬라이제이션 엔진을 연결하세요. 첫 백필을 실행하면 emails/locales/es.json이 생성됩니다. 처음에 일반 푸시만 실행하면 누락된 대상 언어를 번역하지 않은 채 기준 상태만 저장될 수 있습니다. 작업이 실제로 완료될 때까지 기다린 뒤, 대상 번역을 사용하기 전에 제목, 프리헤더, 본문, 플레이스홀더 이름을 확인하세요.
React Email에서는 카탈로그 문자열을 불러와 기존 컴포넌트에 전달하세요. MJML에서는 프로젝트의 템플릿 계층에서 문구를 치환한 뒤 HTML을 컴파일하세요. CLI는 .mjml 파일을 읽지 않습니다. 레이아웃, 이스케이프 처리, 링크는 두 경우 모두 기존 렌더러가 담당합니다.
일반 HTML 템플릿 번역하기 #
템플릿이 일반 HTML 파일이라면 CLI로 직접 번역할 수 있습니다. emails/en/*.html처럼 경로에 원본 로캘이 포함된 패턴을 추가하면 각 대상 언어가 emails/es/order-shipped.html처럼 별도의 파일로 생성됩니다. HTML 형식은 원본 사본에 번역된 텍스트와 지원되는 속성을 반영합니다. 링크와 수정 대상이 아닌 마크업은 작성된 그대로 유지하고, {{...}} 템플릿 토큰은 보호합니다.
발송 전에 현지화된 메시지 전체 렌더링하기 #
애플리케이션의 기존 미리 보기 렌더러를 사용해 원본과 번역본에 동일한 안전한 값을 적용하세요. 간단한 Node 테스트 코드로 이메일을 발송하지 않고도 일반 텍스트 버전을 검증할 수 있습니다. 다음 내용을 프로젝트 루트에 임시 preview-email.mjs 파일로 저장하세요.
import { readFile, writeFile } from "node:fs/promises";
const locale = process.argv[2] ?? "es";
if (!["en", "es"].includes(locale)) {
throw new Error("Unsupported preview locale");
}
const messages = JSON.parse(await readFile(`emails/locales/${locale}.json`, "utf8"));
const values = { name: "Alexandra Example", orderNumber: "EXAMPLE-42", days: 3 };
const trackingUrl = "https://example.com/orders/EXAMPLE-42";
function message(key) {
if (typeof messages[key] !== "string" || messages[key].length === 0) {
throw new Error(`Missing message: ${key}`);
}
return messages[key].replace(/\{(\w+)\}/g, (_, name) => {
if (!Object.hasOwn(values, name)) {
throw new Error(`Unknown placeholder: ${name}`);
}
return String(values[name]);
});
}
const preview = {
subject: message("subject"),
preheader: message("preheader"),
text: [message("heading"), message("body"), `${message("cta")}: ${trackingUrl}`, message("footer")].join("\n\n"),
};
await writeFile(`email-preview-${locale}.json`, JSON.stringify(preview, null, 2) + "\n");node preview-email.mjs en 및 node preview-email.mjs es을 실행한 뒤 저장된 두 미리 보기를 비교하세요. 이 테스트 코드는 단순한 이름 기반 플레이스홀더만 지원하며, ICU, 복수형 선택, HTML 이스케이프 처리, 이메일 발송 기능은 구현하지 않습니다. 이러한 작업에는 운영 환경의 템플릿 렌더러를 사용하세요. 템플릿에서 서식이 적용된 값을 요구한다면, 날짜와 숫자를 수신자의 로캘에 맞게 서식 지정한 뒤 메시지에 전달하세요.
긴 값과 빈 값을 넣어서도 HTML 버전과 일반 텍스트 버전을 렌더링하세요. 프리헤더가 의도한 위치에 표시되는지, 버튼이 허용된 추적 URL로 연결되는지, 법적 식별 정보와 수신 거부 동작이 그대로 유지되는지 확인하세요. 지원되는 이메일 클라이언트에서의 표시, 모바일에서의 잘림, 긴 레이블을 점검하고, 필요한 경우 오른쪽에서 왼쪽으로 쓰는 레이아웃도 확인하세요. 제목 길이 권장 사항만으로는 실제 클라이언트에서 확인하는 과정을 대신할 수 없습니다.
콘텐츠에 런타임 번역이 필요한 경우 #
인증 정보와 번역 호출은 서버에서 처리하세요. 메시지 필드를 인라인 JSON 문서로 제출하고 작업을 시작한 뒤, 이메일을 렌더링하기 전에 완료된 대상 번역을 다운로드하세요. 발송 시스템이 번역과 설정된 검토 절차를 기다릴 수 있도록 발송 전에 이 작업을 큐에 넣으세요.
요청에 사용한 원본 및 대상 로캘, 콘텐츠 개정 버전, 로컬라이제이션 엔진 설정을 기록하세요. 요청 자체가 거부된 경우와 작업이 접수된 뒤 실패한 경우를 구분해 처리하세요. 렌더링 전에 필수 제목 및 본문 필드와 플레이스홀더 호환성을 검증하세요. 선택한 워크플로가 검토를 기다리는 방식이라면 발송 프로세스도 해당 대기 상태를 준수해야 합니다.
번역이 실패하거나 대기 상태로 남아 있을 때 발송을 어떻게 처리할지 정하세요. 나중에 다시 시도하거나, 검토를 마친 대체 콘텐츠를 사용하거나, 메시지 발송을 보류할 수 있습니다. 검증이 끝나면 승인된 콘텐츠를 기존 이메일 서비스에 전달해 발송하세요.
승인된 문구를 템플릿 개정 버전과 함께 보관하기 #
이후 원문이 변경되면 lingo push --wait을 사용한 뒤 렌더링 결과를 다시 비교하세요. 카탈로그, 템플릿, 승인된 대상 번역, CLI Lockfile을 함께 보관하세요. 새로 고치기 전에 기존 수정 사항을 저장하세요. 제출 후 대상 번역이 수정되었는지 확인하려면 --wait을 생략하고 가져오기 전에 lingo pull --dry-run을 확인하세요. 충돌 처리 방법은 검토된 번역 보존하기를 참고하세요.
원문에서 약속하는 내용이 바뀌면 발송 시스템을 해당 개정 버전으로 전환하기 전에 관련 대상 메시지를 검토하세요. 다국어 출시 계획하기에서는 여러 로캘에 걸쳐 이러한 발송 결정을 내리는 방법을 다룹니다.