Next.js 앱에 다국어 기능을 추가하세요.
로케일 파일, 마크다운 콘텐츠, HTML 페이지를 단일 API 호출로 번역하세요. App Router, next-intl 및 모든 i18n 라우팅 설정과 호환됩니다.
Next.js는 라우팅을 제공합니다. 번역은 제공하지 않습니다.
Next.js App Router는 로케일 기반 라우팅을 훌륭하게 지원합니다. next-intl 같은 라이브러리는 번역 파일 관리와 로케일 전환을 간단하게 만듭니다. 하지만 번역 자체는 해결하지 못합니다 — 모든 언어로 번역된 콘텐츠를 만드는 사람은 보통 여러분입니다. 대부분 팀의 워크플로우는 영어 JSON을 DeepL에 복사하고, 깨진 형식을 수정한 후 결과를 붙여넣고, 모든 언어에 대해 반복하는 방식입니다. 느리고 오류가 많으며 확장성이 떨어집니다.
가장 일반적인 워크플로우는 모든 UI 문자열을 소스 코드 내 영어로 작성한 후 각 대상 언어별로 messages.json 파일을 번역하는 것입니다. 이론적으로는 간단하지만, 실제로는 10개 이상의 로케일 파일을 소스 변경과 동기화하는 것이 반복적인 문제입니다. 영어 문구가 변경될 때마다 모든 로케일 파일을 업데이트해야 합니다. 표준 번역 API를 사용할 경우 키 이름이 손상되고 변수 자리 표시자가 번역되며 JSON 구조가 로케일마다 달라져 미묘한 런타임 버그가 발생하기 쉽습니다.
PolyLingo는 기존 Next.js i18n 설정에 적합합니다.
next-intl 또는 다른 i18n 라이브러리를 사용한다면 메시지는 이미 JSON 형식입니다. PolyLingo는 그 JSON을 받아 번역 모델에 보내고, 키는 그대로 유지하고 중첩 구조도 보존하며 문자열 값만 올바르게 번역된 각 대상 언어별 번역본을 반환합니다. 빌드 스크립트, 웹훅, PolyLingo UI에서 호출할 수 있습니다. 결과는 바로 messages 디렉터리에 저장됩니다.
워크플로우: 영어 messages.json을 작성하세요. 단일 스크립트를 실행하여 소스 파일과 모든 대상 언어 코드를 PolyLingo API에 전달합니다. 각 언어별로 동일한 구조의 번역된 JSON 파일을 받습니다. messages/ 디렉터리에 각각 저장하고 커밋하세요. 완료입니다.
CMS(Sanity, Contentful)에서 마크다운이 많은 콘텐츠 중심 사이트의 경우, 같은 방식을 콘텐츠에도 적용할 수 있습니다: 마크다운 또는 HTML로 내보내고 번역한 후 CMS API를 통해 다시 작성합니다. 전체 파이프라인은 빌드 단계나 웹훅 트리거로 실행할 수 있습니다.
// This repository: frontend/scripts/translate-messages.mjs
// Chunks large namespaces (e.g. home) so the model stays within output limits.
//
// export POLYLINGO_API_KEY=pl_xxx
// npm run i18n:polylingo
//
// Writes messages/es.json, fr.json, … from messages/en.json via POST /v1/translate
// with format: "json". See MARKETING_I18N.md for options and CI notes.
//
// Minimal one-shot pattern (fine for small message files):
//
// const source = readFileSync('./messages/en.json', 'utf8')
// const { translations } = await fetch(apiUrl + '/translate', {
// method: 'POST',
// headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
// body: JSON.stringify({
// content: source, format: 'json', source: 'en',
// targets: ['es', 'fr', 'de'], model: 'standard',
// }),
// }).then((r) => r.json())
//
// for (const [lang, raw] of Object.entries(translations)) {
// const obj = typeof raw === 'string' ? JSON.parse(raw) : raw
// writeFileSync(`./messages/${lang}.json`, JSON.stringify(obj, null, 2))
// }// i18n.ts (next-intl v4)
import { getRequestConfig } from 'next-intl/server'
export const locales = [
'en', 'ar', 'bn', 'cs', 'da', 'de', 'el', 'es', 'fa', 'fi',
'fr', 'he', 'hi', 'id', 'it', 'ja', 'ko', 'ms', 'nl', 'no',
'pl', 'pt', 'ru', 'sv', 'sw', 'th', 'tr', 'uk', 'vi', 'zh',
] as const
export type Locale = (typeof locales)[number]
export default getRequestConfig(async ({ requestLocale }) => {
const locale = await requestLocale
return {
locale,
messages: (await import(`./messages/${locale}.json`)).default,
}
})// package.json
{
"scripts": {
"dev": "next dev",
"build": "next build",
"i18n:polylingo": "node scripts/translate-messages.mjs",
"translate:build": "npm run i18n:polylingo && next build"
}
}왜 PolyLingo가 Next.js i18n 워크플로우에 적합한가
- ✓messages/*.json 파일을 직접 번역 — 키는 항상 보존
- ✓블로그 게시물 및 문서 페이지용 마크다운 콘텐츠 번역
- ✓next-intl, next-i18next 및 맞춤 설정과 호환
- ✓REST API는 빌드 스크립트 및 CMS 웹훅과 통합
- ✓36개 언어를 한 번의 요청으로 처리
- ✓무료 티어 — 월 50,000 토큰 제공
- ✓이 저장소는 워크플로우를 자체 사용: npm run i18n:polylingo는 messages/en.json에서 마케팅 로케일을 재생성합니다 (MARKETING_I18N.md 참고).
- ✓App Router와 Pages Router 모두 지원
- ✓출력 파일은 커밋 준비 완료 — 재포맷 불필요
Next.js 앱에 다국어 설정하기
영어 메시지 파일로 next-intl 설정
next-intl을 설치하고 i18n.ts 및 미들웨어를 구성하세요. 모든 UI 문자열을 messages/en.json에 작성하세요. 앱에 맞게 파일 구조를 평면 또는 중첩으로 만드세요. 이 파일이 단일 진실 소스가 됩니다.
번역 스크립트 실행
위 코드 예제처럼 작은 Node 스크립트에서 PolyLingo JSON API를 사용하세요. 이 모노레포에서는 frontend/에서 POLYLINGO_API_KEY를 설정하고 npm run i18n:polylingo를 실행하세요 — 큰 네임스페이스를 신뢰성 있게 분할합니다. 전체 마케팅 번들은 일반적으로 1분 이내에 완료됩니다.
로케일 파일 커밋 및 배포
생성된 로케일 파일은 소스와 동일한 구조의 유효한 JSON입니다. 이를 저장소에 커밋하세요. 번역 스크립트를 CI 파이프라인에 추가하여 콘텐츠 변경 시마다 로케일을 동기화하세요.
Next.js 다국어 사용 사례
SaaS 앱 및 대시보드
한 번의 스크립트 실행으로 전체 UI 문자열 라이브러리를 번역하세요. JSON 구조가 정확히 보존되므로 날짜, 숫자, 복수형 등 next-intl의 모든 형식 기능을 지원합니다.
콘텐츠 사이트 및 블로그
Sanity 또는 Contentful을 사용하는 콘텐츠 중심 Next.js 사이트의 경우, PolyLingo를 사용해 페이지 콘텐츠와 UI 문자열을 모두 번역하세요 — 동일한 API, 동일한 형식 보존 보장.
지역별 변형이 있는 전자상거래
제품명, 설명, 카테고리 페이지, 체크아웃 UI를 번역하세요. 브랜드 음성이 중요한 마케팅 문구에는 고급 모델을, 기능적 UI 문자열에는 표준 모델을 사용하세요.
자주 묻는 질문
Next.js App Router와 함께 작동하나요?
네. PolyLingo 통합은 JSON 파일을 읽고 쓰는 스크립트일 뿐이며 Next.js 내부에 의존하지 않습니다. App Router, Pages Router 또는 어떤 프레임워크와도 작동합니다. 예시로 제시된 next-intl 구성은 Next.js 13, 14, 15와 호환되는 v4 API의 requestLocale을 사용합니다.
messages.json이 자주 변경되면 어떻게 하나요?
권장 패턴은 messages/en.json 변경 시 CI/CD 파이프라인에서 번역 스크립트를 실행하도록 하는 것입니다. 이렇게 하면 모든 로케일 파일이 자동으로 동기화됩니다. 잦은 문구 변경이 있는 팀에선 로케일 드리프트를 완전히 방지할 수 있습니다.
PolyLingo가 next-i18next와 next-intl 모두와 작동하나요?
네. next-i18next도 동일한 로케일 JSON 구조를 사용합니다. 번역 스크립트는 동일하게 작동하며, public/locales/en/ 디렉터리를 지정하고 다른 로케일 디렉터리에 출력 파일을 씁니다. JSON 형식 호환성도 동일합니다.
messages 파일에 없는 동적 콘텐츠는 어떻게 하나요?
동적 콘텐츠 — 블로그 게시물, 제품 설명, 사용자 생성 콘텐츠 — 는 데이터 계층에서 번역해야 하며, CMS 또는 Next.js에 도달하기 전에 콘텐츠를 처리하는 빌드 스크립트를 통해 처리해야 합니다. PolyLingo는 마크다운, HTML, 일반 텍스트를 모두 잘 처리합니다.
지난 실행 이후 변경된 문자열만 번역할 수 있나요?
변경된 키만 번역하는 증분 번역 기능은 로드맵에 있습니다. 현재 스크립트는 전체 파일을 다시 번역합니다. 대부분 메시지 파일(20KB 미만)은 커밋마다 실행해도 충분히 빠릅니다. 매우 큰 파일은 네임스페이스별 분할을 권장합니다.
번역을 프로덕션에 반영하기 전에 검토할 방법이 있나요?
권장 패턴은 번역된 로케일 파일을 별도 브랜치나 PR에 커밋하여 메인에 병합하기 전에 검토하는 것입니다. 이는 번역 품질에 인간 검토가 필요한 팀의 표준 관행입니다. PolyLingo는 좋은 1차 번역을 생성하며, 대부분 UI 문자열은 표준 모델 출력만으로도 편집이 필요 없습니다.
5분 이내에 첫 로케일 파일 번역을 시작하세요.
무료 API 키. 신용카드 불필요. 메시지 JSON을 붙여넣고 즉시 결과를 확인하세요.
API 키 받기번역 스크립트 설정은 5분이면 충분합니다. 무료 티어 — 신용카드 불필요.