Next-Translate 3.0 — Turbopack과 App Router를 위한 i18n 재건

Next-Translate는 Next.js 생태계에서 가장 가벼운 i18n 라이브러리 중 하나다. 그 라이브러리가 1년간의 공백 끝에 3.0을 내놨다. 무엇이 바뀌었고, 왜 지금 이 업데이트가 필요했는지 살펴본다.

왜 1년이나 걸렸나

Next.js 자체가 빠르게 바뀌었다. App Router 안정화, params의 비동기화, Turbopack 전환까지 Next.js 15-16 사이에 상당한 변화가 있었다. 기존 Next-Translate는 이 변화들을 따라잡는 게 쉽지 않았다.

[💡 잠깐! 이 용어는?] i18n (Internationalization): 앱을 여러 언어/지역에서 사용할 수 있게 만드는 작업. "국제화"를 줄여서 i18n이라 부른다 (i와 n 사이 글자 수가 18). 번역 파일 로딩, 날짜/숫자 포맷, RTL 레이아웃 지원 등이 포함된다.

3.0의 핵심 변경사항

Turbopack 지원

Next.js 16이 Turbopack을 기본 번들러로 채택하면서, Webpack 플러그인 기반 라이브러리들이 줄줄이 대응을 해야 했다. Next-Translate도 그 중 하나였다.

3.0은 Turbopack 환경에서도 번역 파일 로딩이 정상 작동하도록 내부 플러그인 구조를 재작성했다. 기존 Webpack 환경과의 하위 호환성은 유지된다. 비유하면 구형 엔진(Webpack)을 쓰던 차에서 신형 전기 모터(Turbopack)로 갈아끼웠는데 계기판과 핸들이 그대로 작동하는 것과 같다.

[💡 잠깐! 이 용어는?] Turbopack: Vercel이 개발한 Rust 기반 번들러. Webpack을 대체하는 것을 목표로 하며, Next.js 16부터 기본 번들러로 전환됐다. 빌드 속도가 Webpack 대비 크게 빠르다.

import nextTranslate from 'next-translate-plugin'
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  // Turbopack과 함께 동작 (별도 설정 불필요)
}
 
export default nextTranslate(nextConfig)

비동기 params 지원

Next.js 15부터 params와 searchParams가 비동기로 바뀌었다. 기존 동기 방식 코드를 그대로 쓰면 경고 또는 오류가 발생한다. 비유하면 식당 주문을 동기 방식으로 처리하다가 비동기 방식으로 전환한 것과 같다. 예전에는 주문을 받고 그 자리에서 즉시 음식을 내왔지만, 이제는 번호표를 받고 기다렸다가 준비되면 가져가는 방식이다. 이 변경에 맞게 번역 함수 호출 방식도 바뀌어야 했다.

// Next.js 15 이전 (동기)
export default function Page({ params }: { params: { locale: string } }) {
  const { t } = useTranslation('common')
  return <div>{t('title')}</div>
}
 
// Next.js 15 이후 (비동기) — 3.0에서 정식 지원
export default async function Page({
  params,
}: {
  params: Promise<{ locale: string }>
}) {
  const { locale } = await params
  const { t } = await createTranslation('common')
  return <div>{t('title')}</div>
}

createTranslation은 App Router 서버 컴포넌트 전용 헬퍼로, 서버에서 직접 번역을 불러올 수 있게 해준다.

Trans 컴포넌트 개선

Trans 컴포넌트가 중첩 배열과 개선된 복수형 처리를 지원하게 됐다. 이전에는 복잡한 번역 키 구조에서 렌더링이 어색하게 되는 경우가 있었다. 비유하면 번역가에게 단어 목록만 주고 문장을 만들어 달라고 했을 때, 문법 규칙이 없으면 어색한 문장이 나오는 것과 같다. 이번 개선으로 HTML 태그, 변수, 복수형 규칙이 하나의 컴포넌트에서 자연스럽게 조합된다.

import Trans from 'next-translate/Trans'
 
export function Welcome({ name }: { name: string }) {
  return (
    <Trans
      i18nKey="common:welcome"
      components={{
        strong: <strong />,
        br: <br />,
      }}
      values={{ name }}
    />
  )
}

주요 변경 사항 비교

pages → app 마이그레이션 자동화가 제거된 점은 브레이킹 체인지다. 아직 Pages Router를 쓰고 있다면 App Router로 먼저 전환한 뒤에 3.0을 적용해야 한다.

[💡 잠깐! 이 용어는?] 브레이킹 체인지(Breaking Change): 이전 버전 코드가 새 버전에서 동작하지 않게 만드는 변경사항. 라이브러리 메이저 버전 업(1.x → 2.x → 3.x)은 일반적으로 브레이킹 체인지가 허용된다.

마무리

Next-Translate 3.0은 Next.js 생태계의 최신 변화를 따라잡는 업데이트다. Turbopack으로 전환 중인 팀이라면 이번 업데이트가 필수다. createTranslation을 통해 서버 컴포넌트에서 번역이 깔끔하게 처리되는 부분도 실용적이다.

저자는 "상수적인 유지보수 리듬을 유지하겠다"고 약속했다. 앞으로는 1년 공백이 없기를 기대해본다.

참고:

• Next-Translate 3.0 릴리스 노트: https://aralroca.com/blog/next-translate-3-0
• GitHub: https://github.com/aralroca/next-translate