[RFC]: Add internationalization (i18n) support — starting with Korean 🚀

[kss2002]

Summary

The Devup UI landing site is currently English-only (except for the footer which contains Korean company information). This RFC proposes adding i18n infrastructure to support multiple languages, with Korean (ko) as the first translation target.

Motivation

Devup UI originates from a Korean company (데브파이브) and has a growing Korean developer community. Korean documentation and UI would significantly lower the barrier to adoption for Korean-speaking developers. The architecture we propose is also extensible for future languages (Japanese, Chinese, etc.).

Technical Constraints

The landing app uses output: 'export' in next.config.ts, which means:

• No Next.js Middleware (locale detection via middleware is not available)
• All pages must be statically generated at build time
• Locale must be encoded in the URL path (e.g., /en/docs/overview, /ko/docs/overview)

Proposed Approach

1. Routing Architecture

Move all routes under a [locale] dynamic segment using the Next.js App Router:

src/app/
  [locale]/          ← new top-level wrapper
    page.tsx         ← home page
    (detail)/
      docs/
        overview/page.tsx  (locale-aware, loads correct .mdx)
        ...

Static params generated via generateStaticParams():

export function generateStaticParams() {
  return [{ locale: 'en' }, { locale: 'ko' }]
}

A root page.tsx handles / → /en as the default locale.

2. i18n Library

Recommended: next-intl (no-middleware mode)

• Official support for output: 'export'
• Works with React Server Components
• TypeScript-safe message keys
• Minimal bundle overhead

Alternative: a lightweight custom solution using plain JSON dictionaries — lower dependency cost, but more manual work.

3. UI String Translations

All hardcoded English strings in .tsx files (e.g., TopBanner, Feature, Header/Menu, LeftMenu) would be extracted into locale dictionaries:

src/
  locales/
    en.json
    ko.json

4. MDX Documentation Strategy

Locale-aware file convention:

docs/overview/
  page.en.mdx   ← current content, renamed
  page.ko.mdx   ← new Korean translation
  page.tsx      ← loads correct .mdx based on [locale]

This makes English→Korean diffs easy to review when source content changes.

5. Language Switcher UI

A locale toggle (e.g., EN | 한국어) in the Header component, linking to the equivalent page in the other locale.

Phased Rollout

Phase	Scope	Effort
1	i18n infra: [locale] routing, next-intl setup, language switcher	Medium
2	UI string translations (TSX files) — en + ko	Medium
3	MDX documentation translation — ko	High (content work)

Phase 1 and 2 can be done without any translated content yet (en is the default). Phase 3 is incremental — pages can show a "Translation in progress" fallback until the Korean version is ready.

Maintenance Considerations

For a sustainable open-source i18n workflow:

• English is source of truth — all changes start in en, Korean follows
• CI check: Verify all English translation keys exist in every locale file
• Contributing guide: Add a "Translations" section to CONTRIBUTING.md
• Stale translation notice: Display a banner on Korean pages when the English source has been updated but the translation has not been synced

Files Affected

• apps/landing/next.config.ts — add i18n config
• apps/landing/src/app/ — restructure under [locale]
• All *.mdx documentation files (86+) — need Korean counterparts eventually
• apps/landing/src/components/Header/ — add language switcher
• New: apps/landing/src/locales/en.json, ko.json

Questions for Maintainers

1. Is next-intl acceptable as a new dependency, or do you prefer a custom/zero-dependency solution?
2. Should the default locale (/) be en, or should it attempt browser language detection?
3. Are there plans to support other languages (e.g., ja, zh) in parallel, or Korean-first?
4. Who would own ongoing Korean translation accuracy? (Community-driven via PRs, or a dedicated maintainer?)

References

• next-intl static export docs
• Next.js i18n routing docs