Sprint 122 — i18n UX Path Completion and Full Page Translation

Background

Sprint 121 built the next-intl-based i18n architecture and completed Landing/Auth demo 2-page translations. However, the following UX defects were confirmed post-merge and transferred to Sprint 122 as top priority work.

Transfer reasons (discovered after Sprint 121 close):

• LanguageSwitcher was only integrated into AppLayout (post-login screens), making unauthenticated users (landing/Auth screen visitors) unable to switch language via UI
• Directly entering /en/* URL renders landing in English, but other pages (dashboard, problems, etc.) remain untranslated
• Hardcoded Korean strings remain in app/[locale]/layout.tsx (skip-nav), not-found.tsx, */error.tsx (21 files), components/ad/AdBanner.tsx, etc.

Sprint 122 goal: On the i18n foundation built by Sprint 121, transition to an actually globally-serviceable state via unauthenticated UX path completion + full major page translation + SEO hreflang support.

Key Decisions (D1~D3)

D1. LanguageSwitcher Placement Strategy

Problem: In Sprint 121, LanguageSwitcher was placed in AppLayout's sidebar/topbar. The landing page (LandingContent.tsx) and auth layout (app/[locale]/(auth)/layout.tsx) have no toggle button, so unauthenticated users cannot switch language via UI.

Selected:

generateMetadata placement: Auth layout's generateMetadata stays in Server Component layout.tsx. AuthShell is separated as Client Component handling only interaction (LanguageSwitcher). Clearly separating Server/Client boundary maintains metadata SEO benefit.

Comparison:

Trade-off: Separating AuthShell as Client Component enables using client hooks like useSearchParams, usePathname in the Auth layout tree. However, getTranslations() server function cannot be called directly inside AuthShell — translations must use useTranslations() hook.

D2. Namespace Domain Grouping

Problem: The 4 namespaces (common/landing/auth/difficulty) confirmed in Sprint 121 cannot accommodate translations for major pages like dashboard, problems, submissions, reviews. Namespace structure needs expansion for Sprint 122's full translation scope.

Selected — keep existing 4 + create 6 new:

common.nav.* extension detail:

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 wrapper strategy:

Korean hardcoded strings are scattered across 21 */error.tsx files and not-found.tsx. Instead of modifying each file individually, create a LocalizedErrorPage common wrapper component and batch-replace all error.tsx files to import it.

components/error/LocalizedErrorPage.tsx  ← Client Component
  - uses useTranslations('errors')
  - props: errorCode (404|403|500|...), retry?: boolean
  - 21 error.tsx files replaced with <LocalizedErrorPage errorCode={...} />

errors.json key structure:

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

Rationale: Modifying 21 error.tsx files individually creates excessive changed files and makes consistency hard to maintain. Centralized error UI management via single LocalizedErrorPage wrapper means only one file needs modification for future error message changes (OCP). Configured as Client Component to use useTranslations hook.

Trade-off: account namespace integrating profile and settings may result in larger file sizes. If both pages expand independently in the future, split account.profile.*/account.settings.* sub-keys into separate files.

D3. SEO Strategy — hreflang + metadataBase + sitemap

Problem: sitemap.xml hreflang tags, robots.txt, and metadataBase configuration are incomplete as Sprint 121 carry-overs. As English pages are added, SEO support is needed for search engines to correctly index locale-specific URLs.

Selected:

1) metadataBase — NEXT_PUBLIC_BASE_URL environment variable

Manage base URL for all metadata via environment variable:

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

Rationale: Remove hardcoded domain strings and separate URLs per staging/production environment via environment variables.

2) buildLocaleAlternates helper — src/lib/i18n/metadata.ts

Create a new helper function that generates locale-specific alternates.languages objects for reuse in each page's 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
 */

/**
 * Generates hreflang alternates object per locale.
 * @param locale - current locale ('ko' | 'en')
 * @param path - path (e.g., '/problems', '/dashboard')
 * @returns Next.js Metadata alternates.languages format
 */
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}`,
  };
}

Usage example:

// 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

Auto-generate locale-specific URL pairs in Next.js App Router's sitemap.ts:

// app/sitemap.ts (conceptual)
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) New app/robots.ts

Dynamically generate robots.txt specifying allowed/disallowed search engine crawling paths:

// 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`,
  };
}

Comparison:

Trade-off: Dynamic page URLs (problem detail, submission detail, etc.) require DB queries, so Sprint 122 scope only includes static paths. Dynamic path hreflang is handled via generateSitemaps extension in Sprint 123.

Scope Decisions

Sprint 122 Scope — Page Level + P0 Processing

Component 53 Sprint 123 Carry-Over Rationale

Korean hardcoding within components identified during Sprint 121 Phase B app/[locale]/* reorganization spans 53 files. Batch-processing in Sprint 122 would:

• Excessive changed files → reduced PR review quality
• No verification baseline for component pre-processing before page-level translations are complete

Principle: Apply sequentially, starting from components whose page-level translations (+ namespaces) are complete. Proceed alongside renderWithI18n test migration in Sprint 123.

Phase Plan (A~H)

Phase Execution Results

Cumulative namespaces 10: common, landing, auth, difficulty, errors, dashboard, problems, submissions, reviews, account Wave D total commits: 14 commits Final commit: 37c8eb2 (Phase E)

Critic Review History

Verification

Sprint 123 Carry-Over Seeds

List of items intentionally excluded from Sprint 122 scope and transferred to Sprint 123.

Component Translations (53 files)

In priority order:

• AppLayout / TopNav / StudySidebar / NotificationBell
• Dashboard* / Analytics* widget components
• Feedback* / Review* / Submission*
• ShareLinkManager and other shared components

Untranslated Pages

i18n Quality Improvements

Security and Backend

Critic-Identified Anti-patterns

Related Documents

• Previous sprint: sprint-121.md
• Next sprint: sprint-123.md
• Current sprint window: memory/sprint-window.md
• Design tokens: CLAUDE.md § Design Tokens (UI v2)
• Annotation dictionary: docs/conventions/annotation-dictionary.md
• next-intl official docs: https://next-intl-docs.vercel.app/
• Next.js Metadata API: https://nextjs.org/docs/app/api-reference/functions/generate-metadata