i18n 대신, 자동 번역 기능을 도입 - Weglot

📅2026년 1월 23일 8:58 AM

#junmannn#Kyurasi#Weglot#Weglot Next.js#Weglot SPA#Weglot 사용법#자동번역#자동번역 모듈#자동번역 솔루션#큐라시

💡이 글의 요약

다국어 지원(i18n)은 글로벌 서비스를 지향한다면 피할 수 없는 숙명과도 같습니다. 하지만 수많은 번역 리소스(JSON, yml 등) 파일 관리와 텍스트 하나 바뀔 때마다 번역팀을 찾는 과정은 개발자에게 적지 않은 피로감을 줍니다. 오늘은 기존의 레거시 i18n 라이브러리를 전면 제거하고, Weglot이라는 자동 번역 솔루션을 도입하며 겪은 트러블슈팅과 그 과정을 공유하려 합니다.왜 i18n을 제거하고 weglot 을 선택했는가?기존처럼 번역 키를 하나하나 매핑하고 JSON 파일을 관리한다.Weglot을 활용해 DOM 기반의 자동 번역을 적용한다.우리는 유지보수 효율성과 기술 부채 제거를 위해 2번을 택했습니다. 특히 추후 진행될 전체 프로젝트 통합 마이그레이션을 고려했을 때, 복잡한 i18n 의존성을..

다국어 지원(i18n)은 글로벌 서비스를 지향한다면 피할 수 없는 숙명과도 같습니다. 하지만 수많은 번역 리소스(JSON, yml 등) 파일 관리와 텍스트 하나 바뀔 때마다 번역팀을 찾는 과정은 개발자에게 적지 않은 피로감을 줍니다.

오늘은 기존의 레거시 i18n 라이브러리를 전면 제거하고, Weglot이라는 자동 번역 솔루션을 도입하며 겪은 트러블슈팅과 그 과정을 공유하려 합니다.

왜 i18n을 제거하고 weglot 을 선택했는가?

기존처럼 번역 키를 하나하나 매핑하고 JSON 파일을 관리한다.
Weglot을 활용해 DOM 기반의 자동 번역을 적용한다.

우리는 유지보수 효율성과 기술 부채 제거를 위해 2번을 택했습니다. 특히 추후 진행될 전체 프로젝트 통합 마이그레이션을 고려했을 때, 복잡한 i18n 의존성을 제거하고 텍스트를 직관적으로 관리하는 것이 더 유리하다고 판단했습니다.

Weglot 생성과 사이트에 연결하기

1. https://dashboard.weglot.com/login 에 접속
2. 워드프레스나 shopify 이런게 아니라 Next.js, vue, 이런 자체 개발을 했다면 other 을 선택합니다!

3. 기존 언어, 자동 번역되길 원하는 대상 언어를 선택합니다. 저는 한글로 다 적어놨고, 이게 영어로 자동 번역 되기를 원해서 한글과 대상은 영어로 정했습니다
4. 사이트 인증하기. 웹사이트 인증은 진짜 복잡할 줄 알았는데, 그냥 도메인만 입력하면 아래에 Looking for the easiest setup? Get started 부분이 있습니다! 이 링크를 눌러야만 빠른 설정이 가능해요!!!

5. 최상위 index.html 에 코드 추가. localhost 에서 진행해도 됩니다. 코드 입력한 후에 반드시 브라우저 상 우측 하단에서 클릭해서 언어를 바꿔 주셔야 인증이 됩니다!

만일 Next.js 를 사용하신다면 index.html 이 없을 수 있습니다.

그런 경우에는 app/layout.tsx 파일에서 코드를 추가해주시면 됩니다. 아래의 코드를 return 의 <html> 안의 <body> 안에다가 넣습니다.

{/* Weglot Script */}
<Script
    src="https://cdn.weglot.com/weglot.min.js"
    strategy="afterInteractive"
/>
<Script id="weglot-init" strategy="afterInteractive">
    {`
        (function() {
            function initWeglot() {
                if (window.Weglot) {
                    window.Weglot.initialize({
                        api_key: '여기에_API키_라고_나왔던_값을_넣으세요'
                    });
                } else {
                    setTimeout(initWeglot, 100);
                }
            }
            initWeglot();
        })();
    `}
</Script>

라우트 이동간에도 번역이 되도록 설정

Vue, Next 같은 SPA 환경에서는 반드시 확인해야 하는 부분이있습니다. 이 설정을 하지 않으면 페이지 이동마다 번역이 자동 적용되질 않습니다. 반드시 Weglot 공식 문서에는 SPA 환경에서의 동적 콘텐츠 처리에 대한 설명이 부족해 애를 먹었습니다. 페이지 이동 시 텍스트가 번역되지 않는 현상이 있다면 아래 설정을 확인해야 합니다.

해결 방법: Weglot 대시보드 → 좌측 aside 에서 스크롤 내려서 Settings → App Settings → Add Dynamic 메뉴에서 body를 입력하여 동적으로 변하는 DOM 요소를 감지하도록 설정해야 합니다.
이 설정을 거쳐야만 SPA 환경에서도 깜빡임 없이 매끄러운 다국어 전환이 가능합니다.