H-7: 국제화 ① — 언어를 주소로 옮깁니다

 오늘의 여정

 1. 한국어가 박혀 있다     도구를 붙이고 첫 글자를 옮긴다
 2. 쿠키에서 알아낸다면     빌드가 다섯 군데에서 멈춘다
 3. 주소로 옮긴다          언어별로 한 벌씩 미리 그려진다
 4. 타입이 목록을 준다      고칠 곳 아홉 군데 — 그리고 못 잡는 한 군데
 5. 빌드는 통과했는데       모든 화면이 도달 불가
 6. 탭 제목도 번역한다      Step 1 이 남긴 빚

 한국어가 들어간 줄   144줄 / 31파일

 화면에 나갈 수 있는 한국어   101개 / 24파일
   그중 lib/posts.ts          30개

 '오늘 한강 노을이 미쳤다'
 '제주도 3박 4일 기록'
 '한강'  '노을'  '여행'

 UI 글자      71개   ← 오늘부터 옮겨갈 것
 사용자 글    30개   ← 절대 건드리면 안 되는 것

npm install next-intl

// apps/web-next/messages/ko.json
{
  "Nav": {
    "brand": "인스타그램 클론",
    "home": "홈",
    "explore": "탐색"
  }
}

// apps/web-next/messages/en.json
{
  "Nav": {
    "brand": "Instagram Clone",
    "home": "Home",
    "explore": "Explore"
  }
}

// apps/web-next/messages/ja.json
{
  "Nav": {
    "brand": "インスタグラムクローン",
    "home": "ホーム",
    "explore": "見つける"
  }
}

// apps/web-next/i18n/request.ts
import { getRequestConfig } from 'next-intl/server';

export default getRequestConfig(async () => {
  const locale = 'ko';

  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  };
});

// apps/web-next/next.config.ts
import createNextIntlPlugin from 'next-intl/plugin';

// i18n/request.ts 를 빌드에 물려준다. 이걸 안 하면 번역을 찾을 곳을 모른다.
const withNextIntl = createNextIntlPlugin();

// ... 기존 설정 그대로 ...

export default withNextIntl(nextConfig);

// apps/web-next/app/components/HeaderNav.tsx
const items = [
  { href: '/', label: '홈' },
  { href: '/explore', label: '탐색' },
] as const;

const items = [
  { href: '/', key: 'home' },
  { href: '/explore', key: 'explore' },
] as const;

export function HeaderNav({ children }: { children?: ReactNode }) {
  const pathname = usePathname();
  const { toggle } = useTextScale();
  // 번역 파일의 "Nav" 칸을 연다. 아래에서는 그 안의 이름만 부르면 된다.
  const t = useTranslations('Nav');

  return (
    <nav className="mx-auto flex max-w-3xl items-center gap-4 p-4 text-sm">
      <span className="font-bold">{t('brand')}</span>
      {items.map((item) => {
        const active = pathname === item.href;
        return (
          <Link
            key={item.href}
            href={item.href}
            aria-current={active ? 'page' : undefined}
            className={active ? 'font-semibold text-black' : 'text-black/50'}
          >
            {t(item.key)}
          </Link>
        );
      })}

// apps/web-next/app/layout.tsx
{/* 번역문을 아래 조각들에게 흘려보낸다. 브라우저에서 도는 조각도 이걸 통해 읽는다. */}
<NextIntlClientProvider>
  <Providers>
    {/* ... 머리말과 children ... */}
  </Providers>
</NextIntlClientProvider>

 Route (app)
 ┌ ◐ /
 ├ ◐ /_not-found
 ├ ◐ /[username]
 ├ ◐ /explore
 └ ◐ /signup

             바꾸기 전    바꾼 뒤
 홈              1건        0건
 탐색            1건        0건
 ホーム          0건        1건
 見つける        0건        1건

 <title>인스타그램 클론</title>
 <meta property="og:title" content="인스타그램 클론">
 <meta name="twitter:title" content="인스타그램 클론">

// apps/web-next/i18n/request.ts
import { cookies } from 'next/headers';
import { getRequestConfig } from 'next-intl/server';

export default getRequestConfig(async () => {
  // 사람이 고른 언어를 쿠키에서 꺼내 온다.
  const store = await cookies();
  const locale = store.get('locale')?.value === 'en' ? 'en' : 'ko';

  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  };
});

 Error: Route "/": Next.js encountered uncached or runtime data during prerendering.

 `fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()`
 accessed outside of `<Suspense>` prevents the route from being prerendered.

 Ways to fix this:
   - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
   - [cache]  For uncached data: cache the access with "use cache"
   - [block]  Set `export const instant = false` to allow a blocking route

 /            /_not-found     /[username]     /explore     /signup

 at <anonymous> (i18n/request.ts:7:30)      ← await cookies()
 at RootLayout (app/layout.tsx:38:9)        ← <NextIntlClientProvider>

 <NextIntlClientProvider>          ← 여기가 쿠키를 읽는다
   <Providers>
     <Suspense>                     ← 경계는 이 아래에 있다
       <HeaderNav />                ← 번역을 쓰는 곳

 빌드         exit 0
 주소 표      전부 ◐  — 바뀐 것 없음

                        미리 그려진 HTML    머리말이 그 안에 있나
 A. 언어 고정              3,052 B                있음
 B. 쿠키 + Suspense        2,003 B                없음

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

// 우리가 지원하기로 한 언어와 기본값.
// 이 목록이 곧 주소 첫 칸에 올 수 있는 값 전부다.
export const routing = defineRouting({
  locales: ['ko', 'en', 'ja'],
  defaultLocale: 'ko',
});

// apps/web-next/i18n/request.ts
import { hasLocale } from 'next-intl';
import { getRequestConfig } from 'next-intl/server';
import { routing } from './routing';

export default getRequestConfig(async ({ requestLocale }) => {
  // 주소의 첫 칸에서 온다. 쿠키와 달리 미리 그릴 때도 아는 값이다.
  const requested = await requestLocale;
  const locale = hasLocale(routing.locales, requested) ? requested : routing.defaultLocale;

  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  };
});

 옮기기 전                     옮긴 뒤
 app/                          app/
   page.tsx                      [locale]/
   layout.tsx                      page.tsx
   explore/page.tsx                layout.tsx
   signup/page.tsx                 explore/page.tsx
   [username]/                     signup/page.tsx
   not-found.tsx                   [username]/
   components/                   not-found.tsx      ← 여기는 안 옮긴다
   api/                          components/
                                 api/

// apps/web-next/app/[locale]/layout.tsx

// 어떤 언어들을 미리 그려둘지 알려준다. 이게 있어야 빌드가 언어별로 한 벌씩 만든다.
export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}

export default async function LocaleLayout({ children, params }: LayoutProps<'/[locale]'>) {
  // 언어가 주소 첫 칸으로 들어온다.
  const { locale } = await params;

  // 우리가 모르는 값이 첫 칸에 오면 그건 언어가 아니다.
  if (!hasLocale(routing.locales, locale)) {
    notFound();
  }

  // 이 요청이 무슨 언어인지 아래 조각들에게 알려둔다.
  // 이 줄이 있어야 미리 그리는 동안에도 번역을 찾을 수 있다.
  setRequestLocale(locale);

  return (
    <html lang={locale} className={notoSansKr.className}>

 Route (app)
 ┌ ○ /_not-found
 ├   /[locale]
 │ ├ ◐ /[locale]
 │ ├ ◐ /ko
 │ ├ ◐ /en
 │ └ ◐ /ja
 ├   /[locale]/[username]
 │ ├ ◐ /ko/[username]   ├ ◐ /en/[username]   └ ◐ /ja/[username]
 ├   /[locale]/explore
 │ ├ ◐ /ko/explore      ├ ◐ /en/explore      └ ◐ /ja/explore
 └   /[locale]/signup
   ├ ◐ /ko/signup       ├ ◐ /en/signup       └ ◐ /ja/signup

 쿠키    화면 하나 · 요청이 와야 언어를 안다 · 미리 못 그린다
 주소    언어마다 한 벌 · 빌드 때 언어를 안다 · 전부 미리 그린다

 app/[locale]/[username]/layout.tsx(8,65):  error TS2344
   Type '"/[username]"' does not satisfy the constraint 'LayoutRoutes'.
 app/[locale]/[username]/layout.tsx(9,11):  error TS2339
   Property 'username' does not exist on type 'unknown'.
 app/[locale]/[username]/page.tsx(10,62):   error TS2344
 app/[locale]/[username]/page.tsx(11,11):   error TS2339
 app/[locale]/[username]/page.tsx(28,65):   error TS2344
 app/[locale]/[username]/page.tsx(29,11):   error TS2339
 app/[locale]/[username]/layout.tsx(23,73): error TS2344
 app/components/HeaderNav.tsx(37,13):       error TS2322
   Type '"/" | "/explore"' is not assignable to type 'RouteImpl<"/" | "/explore">'.
 app/not-found.tsx(11,13):                  error TS2322
   Type '"/"' is not assignable to type 'RouteImpl<"/">'.

 TS2344  네 건   없어진 주소를 가리키고 있다
 TS2339  세 건   그래서 params 가 무엇인지 모른다
 TS2322  두 건   손으로 적어둔 주소가 이제 없는 주소다

// 고치기 전
export default async function ProfilePage({ params }: PageProps<'/[username]'>) {

// 고친 뒤
export default async function ProfilePage({ params }: PageProps<'/[locale]/[username]'>) {

const items = [
  { href: '/', key: 'home' },
  { href: '/explore', key: 'explore' },
] as const;

// apps/web-next/i18n/navigation.ts
import { createNavigation } from 'next-intl/navigation';
import { routing } from './routing';

// next/link 와 next/navigation 을 «언어를 아는» 것으로 바꿔 끼운다.
// 이걸 쓰면 주소에 언어 칸을 손으로 붙이지 않아도 되고,
// usePathname 도 언어 칸을 뗀 주소를 돌려준다.
export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

// apps/web-next/app/components/HeaderNav.tsx
import { Link, usePathname } from '@/i18n/navigation';

 사용자가 있는 곳       /ko/explore
 usePathname 이 주는 값
   next/navigation      "/ko/explore"
   i18n/navigation      "/explore"
 우리가 비교하는 값      "/explore"

                          타입   린트   빌드   현재 위치 표시
 i18n/navigation            0     0      0        1건
 next/navigation            0     0      0        0건

// apps/web-next/app/not-found.tsx
{/* 린터는 여기에 Link 를 쓰라고 한다. 그런데 이 화면은 언어를 모른다 —
    Link 를 쓰려면 /ko 인지 /en 인지를 여기서 정해버려야 한다.
    "/" 로 통째로 이동하면 그 판단을 문지기에게 넘길 수 있다. */}
<a href="/" className="underline">
  피드로 돌아가기
</a>

 /              404
 /ko            307  →  /?next=%2Fko
 /en            307  →  /?next=%2Fen
 /ja            307  →  /?next=%2Fja
 /ko/explore    307  →  /?next=%2Fko%2Fexplore
 /ko/signup     307  →  /?next=%2Fko%2Fsignup
 /ko/jaehoon    307  →  /?next=%2Fko%2Fjaehoon

 빌드    통과
 타입    통과
 린트    통과
 화면    미리 그려짐 (스무 개)
 앱      전부 도달 불가

// apps/web-next/proxy.ts
const PUBLIC_PATHS = ['/', '/explore', '/signup'];

const username = pathname.slice(1);

// apps/web-next/proxy.ts
import createIntlMiddleware from 'next-intl/middleware';
import { routing } from './i18n/routing';

// 언어 라우팅을 맡는 조각. 주소에 언어 칸이 없으면 붙여서 되돌려보낸다.
const handleI18nRouting = createIntlMiddleware(routing);

// 주소에서 언어 칸을 떼어낸다.
// 아래 검사들은 전부 언어를 «모르던 시절» 에 쓰인 주소로 판단하기 때문에,
// 떼지 않으면 /ko/explore 가 공개 목록의 /explore 와 안 맞는다.
function stripLocale(pathname: string) {
  const segments = pathname.split('/');
  const first = segments[1];
  const isLocale = (routing.locales as readonly string[]).includes(first);

  return {
    locale: isLocale ? first : routing.defaultLocale,
    // 언어 칸을 뗀 나머지. 떼고 나서 빈 문자열이면 그건 홈이다.
    rest: isLocale ? `/${segments.slice(2).join('/')}`.replace(/\/$/, '') || '/' : pathname,
  };
}

  // 통과시킬 때는 우리가 응답을 만들지 않고 언어 라우팅에게 만들게 한다.
  // 그래야 /ko 를 내부 라우트로 다시 쓰고, 언어 칸이 없으면 붙여서 되돌려보낸다.
  const pass = () => withCsp(handleI18nRouting(request));

  // 언어 칸을 떼고 나서 판단한다. 아래 목록과 검사는 언어를 모르는 주소로 적혀 있다.
  const { locale, rest } = stripLocale(request.nextUrl.pathname);

  if (PUBLIC_PATHS.includes(rest)) {
    return pass();
  }

  if (getSessionCookie(request) === null) {
    // 되돌려보낼 곳도 그 사람이 보던 언어여야 한다.
    const signInUrl = new URL(`/${locale}`, request.url);
    signInUrl.searchParams.set('next', rest);
    return withCsp(NextResponse.redirect(signInUrl));
  }

  const username = rest.slice(1);

 로그아웃 상태                        로그인 상태
 /             307 → /ko              /ko            200
 /ko           200                    /ko/jaehoon    200
 /en           200                    /en/jaehoon    200
 /ja           200                    /ja/jaehoon    200
 /ko/explore   200                    /ko/zzzzz      404
 /ja/explore   200                    /en/zzzzz      404
 /ko/signup    200
 /ko/jaehoon   307 → /ko?next=%2Fjaehoon

 보안 헤더의 번호표    /ko /en /ja 세 화면 모두 정상 · 비율도 예전과 같음
 없는 사람 404         /ko/zzzzz · /en/zzzzz 둘 다 404
 로그인 문지기         로그아웃이면 프로필이 307
 화면의 언어 표시      ko / en / ja 로 갈린다

 <title>인스타그램 클론</title>
 <meta property="og:title" content="인스타그램 클론">
 <meta name="twitter:title" content="인스타그램 클론">

// apps/web-next/app/[locale]/layout.tsx
export const metadata: Metadata = {
  title: '인스타그램 클론',
  description: 'Next.js App Router 로 다시 짓는 인스타그램',
};

// apps/web-next/app/[locale]/layout.tsx

// metadata 는 컴포넌트가 아니다. 그래서 useTranslations 를 못 쓴다 —
// 훅은 그리는 도중에만 부를 수 있는데 이건 그리기 전에 불린다.
// 대신 기다렸다 받는 getTranslations 를 쓰고, 함수로 바꿔 params 를 받는다.
export async function generateMetadata({ params }: LayoutProps<'/[locale]'>): Promise<Metadata> {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: 'Meta' });

  return {
    title: t('title'),
    description: t('description'),
    // 아래 화면이 자기 것을 안 주면 이게 쓰인다 — 링크가 맨몸으로 나가는 일은 없다.
    openGraph: {
      title: t('title'),
      description: t('description'),
      type: 'website',
    },
  };
}

// apps/web-next/messages/en.json
{
  "Meta": {
    "title": "Instagram Clone",
    "description": "Rebuilding Instagram with the Next.js App Router",
    "profileTitle": "@{username} · Instagram Clone",
    "followers": "{count} followers"
  }
}

// apps/web-next/app/[locale]/[username]/page.tsx
export async function generateMetadata({ params }: PageProps<'/[locale]/[username]'>): Promise<Metadata> {
  const { locale, username } = await params;
  const profile = await fetchProfile(username);
  const t = await getTranslations({ locale, namespace: 'Meta' });

  return {
    title: t('profileTitle', { username }),
    description: t('followers', { count: profile.followerCount }),

 /ko          <title>인스타그램 클론</title>
 /en          <title>Instagram Clone</title>
 /ja          <title>インスタグラムクローン</title>

 /ko/jaehoon  @jaehoon · 인스타그램 클론      팔로워 1240명
 /en/jaehoon  @jaehoon · Instagram Clone     1240 followers
 /ja/jaehoon  @jaehoon・インスタグラムクローン   フォロワー1240人