Spring Boot에서 i18next로 다국어 구현하기 - localStorage SWR 캐싱 아키텍처

@Configuration
public class MessageConfig {
 
    private final Locale defaultLocale = Locale.KOREAN;
 
    @Bean
    public MessageSource messageSource() {
        ReloadableResourceBundleMessageSource messageSource =
            new ReloadableResourceBundleMessageSource();
        messageSource.setBasenames("classpath:messages/messages");
        messageSource.setDefaultEncoding("UTF-8");
        messageSource.setFallbackToSystemLocale(false);
        return messageSource;
    }
 
    @Bean
    public MessageSourceAccessor messageSourceAccessor() {
        return new MessageSourceAccessor(messageSource(), defaultLocale);
    }
}

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
 
    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver("lang");
        resolver.setDefaultLocale(Locale.KOREAN);
        resolver.setCookieMaxAge(Duration.ofDays(365));
        resolver.setCookieHttpOnly(true);
        resolver.setCookieSecure(true);
        resolver.setCookiePath("/");
        return resolver;
    }
 
    @Bean
    public LocaleChangeInterceptor localeChangeInterceptor() {
        LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
        interceptor.setParamName("lang");
        interceptor.setIgnoreInvalidLocale(true);
        return interceptor;
    }
 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localeChangeInterceptor());
    }
}

src/main/resources/messages/
├── messages_ko.properties   # 한국어 (기본)
└── messages_en.properties   # 영어

# 공통 버튼
common.btn.save=저장
common.btn.cancel=취소
 
# 메뉴
menu.dashboard=대시보드
 
# Toast 메시지
toast.save.success=저장되었습니다.
 
# 파라미터 치환 ({0}, {1})
auth.error.login.locked=로그인 제한시간 적용됨. {0}분 후 재시도하세요.
 
# 서버 전용 메시지 (클라이언트 미노출)
_server.error.db.connection=DB 연결 실패
_server.audit.login.success=로그인 성공

private static final Set<String> DENIED_PREFIXES = Set.of("_server.");

private String computeHash(Map<String, String> messages) {
    TreeMap<String, String> sorted = new TreeMap<>(messages);
    StringBuilder sb = new StringBuilder();
    sorted.forEach((k, v) -> sb.append(k).append('=').append(v).append('\n'));
 
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(sb.toString().getBytes(StandardCharsets.UTF_8));
    return HexFormat.of().formatHex(hash); // 64자 hex 문자열
}

@RestController
@RequiredArgsConstructor
public class I18nRestController {
 
    private final I18nMessageProvider i18nMessageProvider;
 
    @GetMapping("/api/i18n/messages")
    public ResponseEntity<Map<String, Object>> getMessages(
            @RequestParam(value = "lang", defaultValue = "ko") String lang) {
        return ResponseEntity.ok(Map.of(
                "hash", i18nMessageProvider.messagesHash(lang),
                "messages", i18nMessageProvider.messagesMap(lang)
        ));
    }
}

const cached = loadFromCache();
 
if (cached && cached.fresh) {
    // Cache hit: 해시 일치, 네트워크 불필요
    initI18next(cached.messages);
} else if (cached) {
    // Stale: 해시 불일치 (배포 후), 기존 메시지로 우선 init → 백그라운드 갱신
    initI18next(cached.messages);
    fetchAndUpdate();
} else {
    // Cold start: 캐시 없음 (첫 방문), 빈 객체로 init → 백그라운드 갱신
    initI18next({});
    fetchAndUpdate();
}

function initI18next(messages) {
    i18next.init({
        lng: window.__i18nLocale,
        fallbackLng: 'ko',
        resources: {
            [window.__i18nLocale]: { translation: messages }
        },
        interpolation: {
            prefix: '{',
            suffix: '}',
            escapeValue: false
        },
        keySeparator: false,
        nsSeparator: false,
        initImmediate: false
    });
}

function fetchAndUpdate() {
    fetch(`/api/i18n/messages?lang=${window.__i18nLocale}`)
        .then(function(response) { return response.json(); })
        .then(function(data) {
            saveToCache(data.messages, data.hash);
            i18next.addResourceBundle(
                window.__i18nLocale, 'translation',
                data.messages, true, true
            );
        })
        .catch(function(error) {
            console.warn('[i18n] fetch failed:', error);
        });
}

<span th:text="#{menu.dashboard}">대시보드</span>
<input type="text" th:placeholder="#{common.placeholder.search}">
<span th:text="#{server.count.info(${total}, ${selected})}"></span>

<!--i18next library-->
<script type="text/javascript" src="/static/lib/i18next/i18next.min.js"></script>
 
<script th:inline="javascript">
    window.__i18nLocale = /*[[${#locale.language}]]*/ 'ko';
    window.__i18nHash = /*[[${@i18nMessageProvider.messagesHash(#locale.language)}]]*/ '';
</script>
 
<script type="text/javascript" src="/static/javascript/common/i18n-init.js"></script>

// common.html 내 DataTable defaults
$.extend(true, $.fn.dataTable.defaults, {
    language: {
        emptyTable: '[[#{datatable.empty}]]',
        info: '[[#{datatable.info}]]',
        lengthMenu: '[[#{datatable.lengthMenu}]]',
        // ...
    }
});

@Override
protected void doFilterInternal(
        HttpServletRequest request,
        HttpServletResponse response,
        FilterChain chain) throws ServletException, IOException {
 
    String path = request.getRequestURI();
    if (path.startsWith("/static/")) {
        response.setHeader("Cache-Control",
            "public, max-age=" + THIRTY_DAYS_SECONDS);
    } else {
        response.setHeader("Cache-Control",
            "no-store, no-cache, must-revalidate, max-age=0");
        response.setHeader("Pragma", "no-cache");
    }
    chain.doFilter(request, response);
}