Next.js 초기 렌더링 시 다국어 문구가 비어 보이는 문제 해결하기

Next.js 애플리케이션에서 다국어를 localStorage 기반으로 처리할 때 다음과 같은 문제가 발생했습니다.

• 초기 화면 로딩 시 버튼 텍스트가 비어 있음
• 새로고침 후에는 정상적으로 다국어 문구가 표시됨

위 문제의 원인을 분석하고 클라이언트 환경에서 다국어를 불러오도록 수정하고, 성능 최적화 작업을 해보았습니다.

---

문제 원인

const DUMMY_DATA = [
  {
    id: 0,
    name: getLang("WD000266"),
    ...
  },
  ...
];

getLang(code)는 localStorage에서 다국어 문자열을 불러오는 함수입니다.

export const getLang = (code) => {
  if (typeof window !== "undefined") {
    const langList = JSON.parse(localStorage.getItem("langList"));
    return langList?.[code] || "";
  }
  return code;
};

주요 원인

1. SSR 환경에서 window, localStorage는 존재하지 않음
   서버 측 렌더링 중 getLang()이 실행되면 빈 문자열 반환
2. 컴포넌트 외부 전역 스코프에서 실행됨
   클라이언트에서 localStorage가 준비되기 전 호출되므로 다국어 데이터를 불러오지 못함

 

해결 방법

1. 클라이언트 전용 훅 생성

// hooks/useLang.js
import { useEffect, useState } from "react";
import { loadLangList } from "/utils";

const useLang = (code) => {
  const [lang, setLang] = useState("");

  useEffect(() => {
    const langList = loadLangList();
    setLang(langList?.[code] || "");
  }, [code]);

  return lang;
};

export default useLang;

• 클라이언트 마운트 이후에만 localStorage 접근
• React lifecycle에 안전하게 대응

2. 컴포넌트 내부에서 데이터 구성

const Component = () => {
  const nameDownload = useLang("WD000266");
  const namePrint = useLang("WD000258");
  const nameRefresh = useLang("WD000265");
  const nameAction = useLang("WD000264");
  const nameRemove = useLang("WD000227");

  const buttonPanelItems = useMemo(
    () => [
      { id: 0, name: nameDownload, key: "download" },
      { id: 1, name: namePrint, key: "print" },
      { id: 2, name: nameRefresh, key: "refresh" },
      { id: 3, name: nameAction, key: "action" },
      { id: 4, name: nameRemove, key: "remove" },
      { id: 5, name: "bar", key: "bar" },
    ],
    [nameDownload, namePrint, nameRefresh, nameAction, nameRemove]
  );

  return buttonPanelItems.map((item) => (
    <button key={item.key}>{item.name}</button>
  ));
};

• 전역이 아닌 컴포넌트 내부에서 데이터를 정의
• useMemo를 통해 성능 최적화

3. 캐시 적용으로 성능 최적화

// utils/utils.js
let cachedLangList = null;

export const loadLangList = () => {
  if (cachedLangList !== null) return cachedLangList;

  try {
    const stored = localStorage.getItem("langList");
    cachedLangList = stored ? JSON.parse(stored) : {};
  } catch {
    cachedLangList = {};
  }

  return cachedLangList;
};

• localStorage는 최초 1회만 접근
• 이후 메모리 캐시된 객체 사용

---

성능 측정

useEffect(() => {
  console.time("Original");
  for (let i = 0; i < 1000; i++) {
    getLangOriginal("WD000258");
  }
  console.timeEnd("Original");

  console.time("Optimized");
  for (let i = 0; i < 1000; i++) {
    getLang("WD000258");
  }
  console.timeEnd("Optimized");
}, []);

 

기존 방식	약 103.9ms
최적화 방식	약 0.059ms

> 약 1,700배 성능 향상 확인

 

캐시 동작 원리

• cachedLangList는 모듈 스코프에 저장되며, JavaScript의 Heap 메모리에 유지됨
• SPA 환경에서는 페이지 이동 시에도 캐시 유지
• 페이지 새로고침이나 브라우저 종료 시 캐시 초기화

 

주의사항

• 외부에서 localStorage 데이터가 수정되면 캐시 무효화가 필요함
• 대용량 데이터일 경우 메모리 점유를 고려해야 함

 

정리

	개선 전	개선 후
SSR 대응	window, localStorage 오류 발생	클라이언트 사이드에서 안전하게 처리
성능	매번 JSON 파싱 및 localStorage 접근	캐시 적용으로 한 번만 접근
구조	전역 스코프에서 실행	컴포넌트 내부에서 다국어 데이터 구성
렌더링 안정성	초기 빈 문자열 렌더링 가능성 있음	클라이언트 마운트 후 정확하게 렌더링 가능

 

---

 

 

 

 

(로컬스토리지 대신 정적 JSON 파일을 사용하면 서버 사이드 렌더링 시 문제가 없었겠지만,
백엔드에서도 다국어 데이터가 필요한 점과 정적 파일 방식은 배포 시에만 다국어 수정이 가능하다는 제약이 있어
절충안(CSR)을 통해 문제를 해결했습니다.)