Refactor languages module: separate client and server code (#57949)

Co-authored-by: Copilot <[email protected]>

Author: heiskr

next.config.ts

@@ -4,14 +4,9 @@ import type { NextConfig } from 'next'
 
 import frontmatter from '@gr2m/gray-matter'
 import { getLogLevelNumber } from '@/observability/logger/lib/log-levels'
+import { languageKeys } from '@/languages/lib/languages'
 
 const ROOT = process.env.ROOT || '.'
-
-// Language keys are defined here because Next.js config compilation doesn't resolve the @/ path alias
-// Importing from src/languages/lib/languages.ts would fail when it tries to import @/frame/lib/constants
-// This must match the languages defined in src/languages/lib/languages.ts
-const languageKeys = ['en', 'es', 'ja', 'pt', 'zh', 'ru', 'fr', 'ko', 'de']
-
 const homepage = path.posix.join(ROOT, 'content/index.md')
 const { data } = frontmatter(fs.readFileSync(homepage, 'utf8'))
 const productIds = data.children as string[]

src/app/client-layout.tsx

@@ -10,7 +10,7 @@ import { initializeEvents } from '@/events/components/events'
 import { CTAPopoverProvider } from '@/frame/components/context/CTAContext'
 import { SharedUIContextProvider } from '@/frame/components/context/SharedUIContext'
 import { LanguagesContext, LanguagesContextT } from '@/languages/components/LanguagesContext'
-import { clientLanguages, type ClientLanguageCode } from '@/languages/lib/client-languages'
+import { languages, type LanguageCode } from '@/languages/lib/languages'
 import { MainContextProvider } from '@/app/components/MainContextProvider'
 import { createMinimalMainContext } from '@/app/lib/main-context-adapter'
 import type { AppRouterContext } from '@/app/lib/app-router-context'
@@ -31,16 +31,11 @@ interface ClientLayoutProps {
 
 export function ClientLayout({ children, appContext, pageData }: ClientLayoutProps): JSX.Element {
   const { theme } = useTheme()
-  const locale: ClientLanguageCode = useDetectLocale()
+  const locale: LanguageCode = useDetectLocale()
   const [isInitialized, setIsInitialized] = useState(false)
   const [initializationError, setInitializationError] = useState<Error | null>(null)
 
-  const languagesContext: LanguagesContextT = useMemo(
-    () => ({
-      languages: clientLanguages,
-    }),
-    [],
-  )
+  const languagesContext: LanguagesContextT = useMemo(() => ({ languages }), [])
 
   // Create MainContext-compatible data for App Router
   const mainContext = useMemo(

src/app/components/AppRouterLanguagesContext.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import { createContext, useContext } from 'react'
-import { clientLanguages, type ClientLanguageCode } from '@/languages/lib/client-languages'
+import { languages, type LanguageCode } from '@/languages/lib/languages'
 
 export type AppRouterLanguageItem = {
   name: string
@@ -12,7 +12,7 @@ export type AppRouterLanguageItem = {
 
 export type AppRouterLanguagesContextT = {
   languages: Record<string, AppRouterLanguageItem>
-  currentLanguage?: ClientLanguageCode
+  currentLanguage?: LanguageCode
 }
 
 export const AppRouterLanguagesContext = createContext<AppRouterLanguagesContextT | null>(null)
@@ -34,15 +34,15 @@ export const useAppRouterLanguages = (): AppRouterLanguagesContextT => {
  */
 interface AppRouterLanguagesProviderProps {
   children: React.ReactNode
-  currentLanguage?: ClientLanguageCode
+  currentLanguage?: LanguageCode
 }
 
 export function AppRouterLanguagesProvider({
   children,
   currentLanguage,
 }: AppRouterLanguagesProviderProps) {
   const value: AppRouterLanguagesContextT = {
-    languages: clientLanguages,
+    languages,
     currentLanguage,
   }
 

src/app/components/ServerFooter.tsx

@@ -1,10 +1,10 @@
 import { getUIDataMerged } from '@/data-directory/lib/get-data'
 import { createTranslationFunctions } from '@/languages/lib/translation-utils'
 import { LinkExternalIcon } from '@primer/octicons-react'
-import type { ClientLanguageCode } from '@/languages/lib/client-languages'
+import type { LanguageCode } from '@/languages/lib/languages'
 
 interface ServerFooterProps {
-  currentLanguage: ClientLanguageCode
+  currentLanguage: LanguageCode
 }
 
 export function ServerFooter({ currentLanguage }: ServerFooterProps) {

src/app/lib/app-router-context.ts

@@ -1,10 +1,10 @@
 import { getUIDataMerged } from '@/data-directory/lib/get-data'
-import { type ClientLanguageCode } from '@/languages/lib/client-languages'
+import { type LanguageCode } from '@/languages/lib/languages'
 import { translate } from '@/languages/lib/translation-utils'
 import { extractLanguageFromPath } from '@/app/lib/language-utils'
 
 export interface AppRouterContext {
-  currentLanguage: ClientLanguageCode
+  currentLanguage: LanguageCode
   currentVersion: string
   sitename: string
   site: {
@@ -19,7 +19,7 @@ export interface AppRouterContext {
  */
 export function createAppRouterContext(
   pathname: string = '/',
-  fallbackLanguage?: ClientLanguageCode,
+  fallbackLanguage?: LanguageCode,
 ): AppRouterContext {
   let language = extractLanguageFromPath(pathname)
 

src/app/lib/language-utils.ts

@@ -1,16 +1,16 @@
-import { clientLanguageKeys, type ClientLanguageCode } from '@/languages/lib/client-languages'
+import { languageKeys, type LanguageCode } from '@/languages/lib/languages'
 
 /**
  * Extract language from URL path
  * Handles paths like /en/something, /es/articles, etc.
  */
-export function extractLanguageFromPath(path: string): ClientLanguageCode {
+export function extractLanguageFromPath(path: string): LanguageCode {
   try {
     const pathSegments = path.split('/')
     const firstSegment = pathSegments[1]
 
-    if (firstSegment && clientLanguageKeys.includes(firstSegment)) {
-      return firstSegment as ClientLanguageCode
+    if (firstSegment && languageKeys.includes(firstSegment)) {
+      return firstSegment as LanguageCode
     }
   } catch (error) {
     console.warn('Failed to extract language from path:', error)
@@ -24,7 +24,7 @@ export function extractLanguageFromPath(path: string): ClientLanguageCode {
 export function hasLanguagePrefix(path: string): boolean {
   const pathSegments = path.split('/')
   const firstSegment = pathSegments[1]
-  return Boolean(firstSegment && clientLanguageKeys.includes(firstSegment))
+  return Boolean(firstSegment && languageKeys.includes(firstSegment))
 }
 
 /**
@@ -43,7 +43,7 @@ export function stripLanguagePrefix(path: string): string {
  * Add language prefix to path if it doesn't have one
  * e.g., /articles/example + 'es' -> /es/articles/example
  */
-export function addLanguagePrefix(path: string, language: ClientLanguageCode): string {
+export function addLanguagePrefix(path: string, language: LanguageCode): string {
   if (hasLanguagePrefix(path)) {
     return path
   }

src/app/lib/locale-context.tsx

@@ -1,55 +1,51 @@
 'use client'
 
 import { createContext, useContext, ReactNode, useMemo } from 'react'
-import {
-  clientLanguages,
-  clientLanguageKeys,
-  type ClientLanguageCode,
-} from '@/languages/lib/client-languages'
+import { languages, languageKeys, type LanguageCode } from '@/languages/lib/languages'
 
 interface LocaleContextType {
-  readonly locale: ClientLanguageCode
-  readonly isValidLocale: (locale: string) => locale is ClientLanguageCode
-  readonly getSupportedLocales: () => readonly ClientLanguageCode[]
-  readonly getLocaleDisplayName: (locale: ClientLanguageCode) => string
-  readonly getLocaleNativeName: (locale: ClientLanguageCode) => string
+  readonly locale: LanguageCode
+  readonly isValidLocale: (locale: string) => locale is LanguageCode
+  readonly getSupportedLocales: () => readonly LanguageCode[]
+  readonly getLocaleDisplayName: (locale: LanguageCode) => string
+  readonly getLocaleNativeName: (locale: LanguageCode) => string
 }
 
 const LocaleContext = createContext<LocaleContextType | null>(null)
 
 interface LocaleProviderProps {
   readonly children: ReactNode
-  readonly locale: ClientLanguageCode
+  readonly locale: LanguageCode
 }
 
 // Use client languages as the source of truth for supported locales
-const SUPPORTED_LOCALES: readonly ClientLanguageCode[] = clientLanguageKeys as ClientLanguageCode[]
+const SUPPORTED_LOCALES: readonly LanguageCode[] = languageKeys as LanguageCode[]
 
 /**
  * Validates if a string is a supported locale
  */
-function isValidLocale(locale: string): locale is ClientLanguageCode {
-  return clientLanguageKeys.includes(locale)
+function isValidLocale(locale: string): locale is LanguageCode {
+  return languageKeys.includes(locale)
 }
 
 /**
- * Gets display name for a locale from client languages data
+ * Gets display name for a locale from languages module
  */
-function getLocaleDisplayName(locale: ClientLanguageCode): string {
-  return clientLanguages[locale]?.name || locale
+function getLocaleDisplayName(locale: LanguageCode): string {
+  return languages[locale]?.name || locale
 }
 
 /**
- * Gets native name for a locale from client languages data
+ * Gets native name for a locale from languages module
  */
-function getLocaleNativeName(locale: ClientLanguageCode): string {
-  return clientLanguages[locale]?.nativeName || clientLanguages[locale]?.name || locale
+function getLocaleNativeName(locale: LanguageCode): string {
+  return languages[locale]?.nativeName || languages[locale]?.name || locale
 }
 
 /**
  * Gets browser language preference as a valid locale
  */
-function getBrowserLocale(): ClientLanguageCode {
+function getBrowserLocale(): LanguageCode {
   if (typeof window === 'undefined') return 'en'
 
   const browserLang = window.navigator.language.split('-')[0]
@@ -77,7 +73,7 @@ export function LocaleProvider({ children, locale }: LocaleProviderProps): JSX.E
 /**
  * Hook to get current locale with enhanced error handling
  */
-export function useLocale(): ClientLanguageCode {
+export function useLocale(): LanguageCode {
   const context = useContext(LocaleContext)
 
   if (context) {
@@ -118,4 +114,4 @@ export function useLocaleContext(): LocaleContextType {
 }
 
 export { isValidLocale, getLocaleDisplayName, getLocaleNativeName }
-export type { LocaleContextType, ClientLanguageCode }
+export type { LocaleContextType, LanguageCode }

src/app/lib/server-context-utils.ts

@@ -1,11 +1,11 @@
 import { extractLanguageFromPath } from '@/app/lib/language-utils'
 import { extractVersionFromPath } from '@/app/lib/version-utils'
 import { getUIDataMerged } from '@/data-directory/lib/get-data'
-import { type ClientLanguageCode } from '@/languages/lib/client-languages'
+import { type LanguageCode } from '@/languages/lib/languages'
 import { createTranslationFunctions, translate } from '@/languages/lib/translation-utils'
 
 export interface ServerAppRouterContext {
-  currentLanguage: ClientLanguageCode
+  currentLanguage: LanguageCode
   currentVersion: string
   sitename: string
   site: { data: { ui: any } }
@@ -33,7 +33,7 @@ export function createServerAppRouterContext(pathname: string): ServerAppRouterC
 /**
  * Create server-side footer with translations
  */
-export function createServerFooterContent(language: ClientLanguageCode) {
+export function createServerFooterContent(language: LanguageCode) {
   const uiData = getUIDataMerged(language)
   const { t } = createTranslationFunctions(uiData, 'footer')
 

src/app/lib/use-detect-locale.tsx

@@ -2,24 +2,24 @@
 
 import { usePathname } from 'next/navigation'
 import { useMemo, useEffect, useState } from 'react'
-import { clientLanguageKeys, type ClientLanguageCode } from '@/languages/lib/client-languages'
+import { languageKeys, type LanguageCode } from '@/languages/lib/languages'
 import Cookies from '@/frame/components/lib/cookies'
 import { USER_LANGUAGE_COOKIE_NAME } from '@/frame/lib/constants'
 
 /**
  * Validates if a string is a supported locale using client languages
  */
-function isValidLocale(locale: string): locale is ClientLanguageCode {
-  return clientLanguageKeys.includes(locale)
+function isValidLocale(locale: string): locale is LanguageCode {
+  return languageKeys.includes(locale)
 }
 
 /**
  * Hook to detect locale from various sources with fallback logic
  */
-export function useDetectLocale(): ClientLanguageCode {
+export function useDetectLocale(): LanguageCode {
   const pathname = usePathname()
-  const [cookieLanguage, setCookieLanguage] = useState<ClientLanguageCode | null>(null)
-  const [browserLanguage, setBrowserLanguage] = useState<ClientLanguageCode | null>(null)
+  const [cookieLanguage, setCookieLanguage] = useState<LanguageCode | null>(null)
+  const [browserLanguage, setBrowserLanguage] = useState<LanguageCode | null>(null)
 
   // Read cookie and browser language on client-side mount
   useEffect(() => {
@@ -71,7 +71,7 @@ export function useDetectLocale(): ClientLanguageCode {
 /**
  * Utility function to detect locale from pathname (for server-side use)
  */
-export function detectLocaleFromPath(pathname: string): ClientLanguageCode {
+export function detectLocaleFromPath(pathname: string): LanguageCode {
   const pathSegments = pathname.split('/')
   const firstSegment = pathSegments[1]
 
@@ -82,8 +82,8 @@ export function detectLocaleFromPath(pathname: string): ClientLanguageCode {
   return 'en'
 }
 
-export function getSupportedLocales(): readonly ClientLanguageCode[] {
-  return clientLanguageKeys as ClientLanguageCode[]
+export function getSupportedLocales(): readonly LanguageCode[] {
+  return languageKeys as LanguageCode[]
 }
 
 export { isValidLocale }

src/app/types.ts

@@ -2,14 +2,14 @@
  * Enhanced type definitions for the app router with strict validation
  */
 
-import type { ClientLanguageCode } from '@/languages/lib/client-languages'
+import type { LanguageCode } from '@/languages/lib/languages'
 
 // Core theme types with strict validation
 export type Theme = 'light' | 'dark' | 'auto'
 export type ColorMode = 'light' | 'dark'
 
-// Re-export locale type from client-languages for consistency
-export type Locale = ClientLanguageCode
+// Re-export locale type from languages.ts for consistency
+export type Locale = LanguageCode
 
 // Version and product identifiers with validation
 export type VersionId = string