Sprint 122 — i18n UX 경로 완성 및 전체 페이지 번역 적용

배경

Sprint 121에서 next-intl 기반 i18n 아키텍처를 구축하고 Landing/Auth 시범 2페이지 번역을 완성했다. 그러나 머지 후 다음 UX 결함이 확인되어 Sprint 122 최우선 작업으로 이관되었다.

이관 원인 (Sprint 121 마감 후 발견):

• LanguageSwitcher가 AppLayout(로그인 후 화면)에만 통합되어 있어, 미인증 사용자(랜딩·Auth 화면 방문자)는 UI로 언어 전환 불가
• /en/* URL을 직접 입력하면 랜딩은 영문으로 렌더링되나, 그 외 페이지(dashboard, problems 등)는 번역 미적용 상태
• app/[locale]/layout.tsx(skip-nav), not-found.tsx, */error.tsx(21개), components/ad/AdBanner.tsx 등에 하드코딩 한글 문자열 잔존

Sprint 122 목표: Sprint 121이 구축한 i18n 기반 위에서 미인증 UX 경로 보완 + 전체 주요 페이지 번역 완성 + SEO hreflang 대응을 통해 실제 글로벌 서비스 가능 상태로 전환한다.

핵심 결정 (D1~D3)

D1. LanguageSwitcher 배치 전략

문제: Sprint 121에서 LanguageSwitcher는 AppLayout의 사이드바·상단바에 배치되었다. 랜딩 페이지(LandingContent.tsx)와 인증 레이아웃(app/[locale]/(auth)/layout.tsx)에는 토글 버튼이 없어 미인증 사용자가 UI로 언어를 전환할 수 없다.

선택:

generateMetadata 위치: Auth 레이아웃의 generateMetadata는 Server Component인 layout.tsx에 유지한다. AuthShell은 Client Component로 분리하여 인터랙션(LanguageSwitcher)만 담당한다. Server/Client 경계를 명확히 분리함으로써 메타데이터 SEO 이점을 유지한다.

대안 비교:

트레이드오프: AuthShell을 Client Component로 분리하면 Auth 레이아웃 트리에서 useSearchParams, usePathname 등 클라이언트 훅을 사용할 수 있다. 단, AuthShell 내부에서 getTranslations() 서버 함수는 직접 호출 불가 — 번역은 useTranslations() 훅으로 처리한다.

D2. 네임스페이스 도메인 그룹핑

문제: Sprint 121에서 확정한 4개 네임스페이스(common/landing/auth/difficulty)로는 대시보드·문제·제출·리뷰 등 주요 페이지 번역을 수용할 수 없다. 네임스페이스 구조를 Sprint 122 전체 번역 범위에 맞춰 확장한다.

선택 — 기존 4개 유지 + 신설 6개:

common.nav.* 확장 상세:

common.nav.dashboard   → "대시보드" / "Dashboard"
common.nav.problems    → "문제" / "Problems"
common.nav.submissions → "제출" / "Submissions"
common.nav.reviews     → "리뷰" / "Reviews"
common.nav.profile     → "프로필" / "Profile"
common.nav.settings    → "설정" / "Settings"
common.nav.admin       → "관리자" / "Admin"
common.nav.skipToMain  → "본문으로 건너뛰기" / "Skip to main content"

errors.json + LocalizedErrorPage 래퍼 전략:

현재 */error.tsx 파일 21개와 not-found.tsx 등에 하드코딩된 한글 문자열이 분산되어 있다. 각 파일을 개별 수정하는 대신, LocalizedErrorPage 공통 래퍼 컴포넌트를 신설하고 모든 error.tsx가 이를 임포트하도록 일괄 치환한다.

components/error/LocalizedErrorPage.tsx  ← Client Component
  - useTranslations('errors') 사용
  - props: errorCode (404|403|500|...), retry?: boolean
  - 21개 error.tsx가 <LocalizedErrorPage errorCode={...} />로 교체

errors.json 키 구조:

{
  "notFound": { "title": "...", "description": "...", "back": "..." },
  "forbidden": { "title": "...", "description": "..." },
  "serverError": { "title": "...", "description": "...", "retry": "..." },
  "generic": { "title": "...", "description": "...", "home": "..." }
}

근거: 21개 error.tsx 개별 수정은 변경 파일 수가 과다하고 일관성 유지가 어렵다. LocalizedErrorPage 단일 래퍼로 에러 UI를 집중 관리하면 향후 에러 메시지 변경 시 단일 파일만 수정하면 된다(OCP). Client Component로 구성하여 useTranslations 훅을 사용할 수 있다.

트레이드오프: account 네임스페이스가 profile과 settings를 통합하므로 파일 크기가 커질 수 있다. 향후 두 페이지가 독립 확장될 경우 account.profile.*/account.settings.* 서브키를 별도 파일로 분리한다.

D3. SEO 전략 — hreflang + metadataBase + sitemap

문제: Sprint 121 이월 항목으로 sitemap.xml hreflang 태그, robots.txt, metadataBase 설정이 미완성 상태다. 영문 페이지가 추가됨에 따라 검색엔진이 로케일별 URL을 올바르게 인덱싱하도록 SEO 대응이 필요하다.

선택:

1) metadataBase — NEXT_PUBLIC_BASE_URL 환경 변수

모든 메타데이터의 기준 URL을 환경 변수로 관리한다:

// app/[locale]/layout.tsx
export const metadata: Metadata = {
  metadataBase: new URL(process.env.NEXT_PUBLIC_BASE_URL ?? 'https://algosu.kr'),
};

근거: 하드코딩된 도메인 문자열을 제거하고, 스테이징/프로덕션 환경별 URL을 환경 변수로 분리한다.

2) buildLocaleAlternates 헬퍼 — src/lib/i18n/metadata.ts

로케일별 alternates.languages 객체를 생성하는 헬퍼 함수를 신설하여 각 페이지 generateMetadata에서 재사용한다:

// src/lib/i18n/metadata.ts
/**
 * @file src/lib/i18n/metadata.ts
 * @domain i18n
 * @layer lib
 * @related src/i18n/routing.ts, app/[locale]/layout.tsx
 */

/**
 * 로케일별 hreflang alternates 객체를 생성합니다.
 * @param locale - 현재 로케일 ('ko' | 'en')
 * @param path - 경로 (예: '/problems', '/dashboard')
 * @returns Next.js Metadata alternates.languages 형태
 */
export function buildLocaleAlternates(
  locale: string,
  path: string,
): Record<string, string> {
  const base = process.env.NEXT_PUBLIC_BASE_URL ?? 'https://algosu.kr';
  return {
    ko: `${base}${path}`,
    en: `${base}/en${path}`,
    'x-default': `${base}${path}`,
  };
}

사용 예시:

// app/[locale]/problems/page.tsx
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: 'problems' });
  return {
    title: t('meta.title'),
    alternates: {
      languages: buildLocaleAlternates(locale, '/problems'),
    },
  };
}

3) app/sitemap.ts — alternates.languages hreflang

Next.js App Router의 sitemap.ts에서 로케일별 URL 쌍을 자동 생성한다:

// app/sitemap.ts (개념)
export default function sitemap(): MetadataRoute.Sitemap {
  const base = process.env.NEXT_PUBLIC_BASE_URL ?? 'https://algosu.kr';
  const paths = ['/problems', '/dashboard', '/submissions', '/reviews'];
  return paths.map((path) => ({
    url: `${base}${path}`,
    alternates: {
      languages: {
        ko: `${base}${path}`,
        en: `${base}/en${path}`,
      },
    },
  }));
}

4) app/robots.ts 신설

robots.txt를 동적으로 생성하여 검색엔진 크롤링 허용/금지 경로를 명시한다:

// app/robots.ts
export default function robots(): MetadataRoute.Robots {
  const base = process.env.NEXT_PUBLIC_BASE_URL ?? 'https://algosu.kr';
  return {
    rules: { userAgent: '*', allow: '/', disallow: ['/admin/', '/api/'] },
    sitemap: `${base}/sitemap.xml`,
  };
}

대안 비교:

트레이드오프: 동적 페이지(문제 상세, 제출 상세 등)의 URL은 DB 쿼리가 필요하므로, Sprint 122 범위에서는 정적 경로만 포함한다. 동적 경로 hreflang은 Sprint 123에서 generateSitemaps 확장으로 처리한다.

범위 결정

Sprint 122 범위 — 페이지 레벨 + P0 처리

컴포넌트 53개 Sprint 123 이월 근거

Sprint 121 Phase B에서 app/[locale]/* 재편 시 확인된 컴포넌트 내 한글 하드코딩은 53개 파일에 걸쳐 있다. 이를 Sprint 122에서 일괄 처리하면:

• 변경 파일 수 과다 → PR 리뷰 품질 저하
• 페이지 레벨 번역이 완성되지 않은 상태에서 컴포넌트 선처리는 검증 기준 부재

원칙: 페이지 레벨 번역(+네임스페이스)이 완성된 컴포넌트부터 순차 적용. Sprint 123에서 renderWithI18n 테스트 마이그레이션과 함께 진행.

Phase 계획표 (A~H)

Phase 실행 결과

누적 네임스페이스 10개: common, landing, auth, difficulty, errors, dashboard, problems, submissions, reviews, account
Wave D 총 커밋: 14 commits
최종 커밋: 37c8eb2 (Phase E)

Critic 리뷰 이력

검증

Sprint 123 이월 시드

Sprint 122 범위에서 의도적으로 제외하고 Sprint 123으로 이관하는 항목 목록.

컴포넌트 번역 (53개)

우선순위 순:

• AppLayout / TopNav / StudySidebar / NotificationBell
• Dashboard* / Analytics* 위젯 컴포넌트
• Feedback* / Review* / Submission*
• ShareLinkManager 및 기타 공용 컴포넌트

미번역 페이지

i18n 품질 개선

보안 및 백엔드

Critic 지적 anti-pattern

관련 문서

• 이전 스프린트: sprint-121.md
• 다음 스프린트: sprint-123.md
• 현재 스프린트 윈도우: memory/sprint-window.md
• 디자인 토큰: CLAUDE.md § 디자인 토큰 (UI v2)
• 어노테이션 사전: docs/conventions/annotation-dictionary.md
• next-intl 공식 문서: https://next-intl-docs.vercel.app/
• Next.js Metadata API: https://nextjs.org/docs/app/api-reference/functions/generate-metadata