Next.js 블로그에 i18n 붙이기 — next-intl v4 실전 가이드

// i18n/routing.ts
import { defineRouting } from 'next-intl/routing'

export const routing = defineRouting({
  locales: ['ko', 'en'] as const,
  defaultLocale: 'ko',
  localePrefix: 'as-needed',
})

import { getRequestConfig } from 'next-intl/server'
import { routing } from './routing'

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale
  if (!locale || !(routing.locales as readonly string[]).includes(locale)) {
    locale = routing.defaultLocale
  }
  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  }
})

import { createNavigation } from 'next-intl/navigation'
import { routing } from './routing'

export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing)

app/
  layout.tsx          ← passthrough only (children as never)
  [locale]/
    layout.tsx        ← setRequestLocale(locale) 여기서 한 번
    page.tsx
    blog/[slug]/page.tsx
    category/[name]/page.tsx
    tag/[name]/page.tsx
    tags/page.tsx
    about/page.tsx

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return children as never
}

// app/[locale]/layout.tsx
import { setRequestLocale } from 'next-intl/server'

export default async function LocaleLayout({ children, params }) {
  const { locale } = await params
  setRequestLocale(locale)   // ← 이게 없으면 하위 전체가 깨진다
  // ...
}

// messages/en.json (일부)
{
  "nav": { "home": "/home", "tags": "/tags", "about": "/about" },
  "post": { "readTime": "{minutes} min read" },
  "blog": {
    "prevPost": "Prev",
    "nextPost": "Next",
    "relatedPosts": "Related Posts"
  }
}

// 서버 컴포넌트
const t = await getTranslations('post')
return <span>{t('readTime', { minutes: post.readTime })}</span>

// 클라이언트 컴포넌트
const t = useTranslations('blog')
return <button>{t('prevPost')}</button>

// lib/tagTranslations.ts
const TAG_MAP: Record<string, string> = {
  '머신러닝': 'Machine Learning',
  '미적분': 'Calculus',
  '선형대수': 'Linear Algebra',
  '인증': 'Authentication',
  // ... 80여 개
}

export function translateTag(tag: string, locale: string): string {
  if (locale !== 'en') return tag
  return TAG_MAP[tag] ?? tag  // 번역 없으면 원문 그대로
}

content/posts/
  oauth-oidc.mdx        ← 한국어 원본
  oauth-oidc.en.mdx     ← 영어 번역본
  calculus-1.mdx
  calculus-1.en.mdx

function resolvePostPath(slug: string, locale?: string): string {
  if (locale === 'en') {
    const enPath = path.join(postsDirectory, `${slug}.en.mdx`)
    if (fs.existsSync(enPath)) return enPath  // EN 파일 있으면 사용
  }
  return path.join(postsDirectory, `${slug}.mdx`)  // 없으면 한국어 fallback
}

export function getAllPosts(locale?: string): PostMeta[] {
  return fs.readdirSync(postsDirectory)
    .filter((name) => name.endsWith('.mdx') && !name.endsWith('.en.mdx'))
    // ↑ .en.mdx는 base 목록에서 제외 — 중복 노출 방지
    .map((fileName) => {
      const slug = fileName.replace(/\.mdx$/, '')
      const localizedPath = resolvePostPath(slug, locale)
      const { data, content } = matter(fs.readFileSync(localizedPath, 'utf8'))

      // 썸네일은 항상 한국어 base 파일에서 추출
      // (EN 파일에 이미지 없어도 썸네일이 깨지지 않는다)
      const basePath = path.join(postsDirectory, fileName)
      const baseContent = localizedPath !== basePath
        ? matter(fs.readFileSync(basePath, 'utf8')).content
        : content
      const thumbnail = extractFirstImage(baseContent)

      return { slug, title: data.title, .../* 나머지 frontmatter */ }
    })
}

// ❌ 잘못된 예 — locale별로 중복 slug가 생길 수 있다
export async function generateStaticParams() {
  return routing.locales.flatMap((locale) =>
    getAllPosts(locale).map((post) => ({ locale, slug: post.slug }))
  )
}

// ✅ 올바른 예 — base slugs를 locale 없이 가져오고, locale만 조합
export async function generateStaticParams() {
  return routing.locales.flatMap((locale) =>
    getAllPosts().map((post) => ({ locale, slug: post.slug }))
  )
}

# ❌
git add app/[locale]/blog/[slug]/page.tsx

# ✅
git add "app/[locale]/blog/[slug]/page.tsx"

// ❌ — EN 로케일에서 /en/ prefix 누락
import Link from 'next/link'

// ✅ — locale 자동 처리
import { Link } from '@/i18n/navigation'