@weglot/translate-react

다음 내용을 번역해 주세요:
React, Next.js 또는 Vite 앱

t() 래퍼도, JSON 파일도 필요 없습니다. 빌드 플러그인과 Weglot API 키를 추가하기만 하면, 앱이 빌드될 때 JSX 내의 텍스트가 번역되며, 팀원들은 코드를 건드리지 않고도 Weglot 에서 번역 내용을 편집할 수 있습니다.

API 키를 발급받으세요

다음 프롬프트를 복사하세요. · · · 문서를 읽어보세요 · npm에서 보기

필수 React 19 Next.js 15 / 16.0.4 이상 (App Router) 또는 Vite Node 20.9 이상

// how it works

네 단계. 구성 요소는 그대로 유지됩니다.

원문과 대상 언어는 코드가 아닌 ‘ Weglot ’ 프로젝트에서 가져옵니다. 이 플러그인은 빌드 시점에 JSX 내의 텍스트를 읽어와 해당 번역을 가져옵니다.

  1. 패키지를 설치하고 API 키를 추가하세요

    Weglot 2.0 프로젝트를 생성한 다음, 프로젝트 설정에서 API 키를 복사하세요. API 키는 다음과 같이 시작합니다. pk_. 계속 .env 버전 관리 시스템에서 제외됨.

    터미널 · .env
    $ npm install @weglot/translate-react

# .env
WEGLOT_API_KEY=pk_your_weglot_api_key

  2. 플러그인 추가하기

    Next.js 구성을 다음 코드로 감싸세요. withWeglot. 포인트 sourceRoot 페이지와 컴포넌트가 들어 있는 폴더로.

    next.config.ts
    import type { NextConfig } from "next";
import { withWeglot } from "@weglot/translate-react/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withWeglot(nextConfig, { sourceRoot: "./app" });
}

  3. 제공자 추가하기

    루트 레이아웃을 다음으로 감싸세요. WeglotProvider Next.js의 진입점에서 호출되도록 하여, 언어를 변경하면 서버 컴포넌트가 새로고침되도록 합니다.

    app/layout.tsx
    import { WeglotProvider } from "@weglot/translate-react/react/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <WeglotProvider>{children}</WeglotProvider>
      </body>
    </html>
  );
}

  4. 프로젝트의 모든 언어로 빌드하고 배포하세요

    각 빌드에서는 Weglot 에서 누락된 번역 내용을 가져와 다음을 기록합니다. public/translations/<locale>.json. 그 폴더는 무시하세요. 다음 코드를 사용하여 언어 선택기를 추가하세요. LocaleSwitcher 또는 useWeglotContext.

    .gitignore
    public/translations/

// compare

왜 기존의 i18n 라이브러리를 사용하지 않는 걸까요?

i18n 라이브러리는 모든 문자열을 키로 대체하고 언어별로 하나의 파일을 유지하도록 요구합니다. Weglot 는 사용자가 이미 작성한 문자열을 읽어옵니다. 다음은 두 옵션의 비교입니다.

각 프로젝트의 공개 문서(Weglot, next-intl, Paraglide JS, Contentful, Sanity, Strapi)를 바탕으로 한 것으로, 2026년 11월 기준입니다.
기준 Weglot
@weglot/translate-react		 next-intl / i18next 패러글라이드 JS CMS 원어 현지화
문자열을 t() 또는 메시지 함수로 감싸기 아니요JSX 내의 텍스트는 빌드 시점에 감지됩니다. 네t("key") 모든 문자열에 대해. 네m.key() 메시지 기능. 콘텐츠만코드에 포함된 문자열을 처리하려면 여전히 라이브러리가 필요합니다.
언어별 번역 파일 유지 관리할 항목 없음빌드 시 생성되며, git에서 무시됨. 네일반적으로 로케일당 하나의 JSON 파일이 있습니다. 네로케일당 하나의 메시지 파일입니다. 아니요CMS에 저장되어 있지 않습니다.
다국어 라우팅 및 SEO (언어별 URL, hreflang) 아직 아닙니다쿠키에 저장된 언어. 모든 언어에 대해 동일한 URL을 사용하며, 원본 언어가 색인화되어 있습니다. next-intl: 예로케일 라우팅이 내장되어 있습니다. i18next: 프레임워크 설정을 통해 구현됩니다. 예내장된 지역화된 URL: 지역 코드 접두사, 번역된 경로 또는 도메인. hreflang 태그는 직접 추가해 주세요. 프론트엔드헤드리스 CMS는 로케일별로 콘텐츠를 저장합니다. URL과 hreflang은 프론트엔드에서 제공됩니다.
사용자님을 위해 생성된 번역 결과 네Weglot 빌드 과정에서 LLM을 통해 번역됩니다. 아니요직접 번역한 내용이나 TMS를 가져오세요. 툴링inlang CLI 기계 번역 또는 귀하의 코딩 에이전트를 통해. 유료 애드온유료 요금제의 AI 번역 기능: Contentful AI Actions, Sanity AI Assist, Strapi AI Translations.
개발자 없이 번역 수정하기 예Weglot 대시보드에서 검토하고 편집하세요. 아니요JSON 파일을 편집하거나 별도의 TMS를 추가하십시오. Fink를 사용하면inlang의 웹 편집기를 사용하여, GitHub 계정이 필요합니다. 예CMS 편집기에서.
코딩 에이전트가 하나의 프롬프트로 설정함 네설치는 한 번, 설정 편집은 두 번입니다. 아래에 복사 가능한 프롬프트가 있습니다. 시간이 오래 걸리는 작업에이전트는 모든 문자열을 키와 파일로 변환합니다. 시간이 오래 걸리는 작업init 에이전트에 대한 입력 요청 없이 실행되면, 모든 문자열이 m.key() 메시지. 해당 사항 없음CMS에서 설정되었습니다.

// built for coding agents

AI 코딩 에이전트를 위해 설계됨

Claude Code, Cursor 또는 Codex를 사용하여 모델을 구축하면, 에이전트가 스스로 ‘ Weglot ’를 추가할 수 있습니다. 재작성해야 할 문자열이 없기 때문에 변경 사항이 적고 검토하기도 쉽습니다.

01 · 설정

에이전트가 이를 설치하고 구성합니다

하나 npm install, 플러그인 하나, 제공자 하나, 한 줄의 코드 .gitignore. 담당자는 API 키만 요청합니다.

02 · 문서

LLM이 읽을 수 있는 문서

문서에는 llms.txt 목차, 그리고 모든 페이지에는 마크다운 버전이 있습니다: 추가 .md 해당 URL에.

03 · 프롬프트

복사할 수 있는 프롬프트

이 프롬프트의 각 단계는 실제 임포트 경로를 포함하여 시작 가이드와 일치합니다. 아래에 복사해 두세요.

클로드 코드에 붙여넣기

      

      
      
      
    

  

  







  

    
// for your team

    
코드를 건드리지 않고 편집 및 검토하기

    
모든 번역 내용은 ‘ Weglot ’ 프로젝트에 반영됩니다. 제품, 마케팅 담당자 및 번역가들은 풀 리퀘스트를 생성하지 않고도 해당 프로젝트에서 문구를 검토하고 수정할 수 있습니다.

    
    
      
  • Weglot 가 앱에 대해 생성한 번역 내용을 검토하세요.
    • 
      
  • Weglot 대시보드에서 번역 내용을 편집할 수 있습니다.
    • 
      
  • 제외 다음과 같은 코드에 포함된 모든 것 translate="no" 또는 data-weglot-skip.
    • 
    

  







  

    
// fit

    
Weglot 를 사용할 때와 사용하지 말아야 할 때

    
이 패키지는 현재 미리보기 단계에 있습니다. 현재 이 패키지가 어떤 위치에 있는지 살펴보겠습니다.

    

      

        
다음과 같은 경우 @weglot/translate-react를 사용하세요.

        
    
          
  • 귀하의 앱은 Next.js(App Router) 또는 Vite에서 React 19를 실행합니다.
    • 
          
  • 문자를 t()로 감싸거나 언어마다 별도의 파일을 관리하고 싶지는 않을 것입니다.
    • 
          
  • 코딩 에이전트가 코드의 대부분을 작성하므로, 번역도 그 속도를 따라잡을 수 있도록 하고 싶습니다.
    • 
          
  • 코딩을 하지 않는 분들도 번역 내용을 검토하고 수정해 주셔야 합니다.
    • 
          
  • UI 텍스트는 코드에 포함되어 있으며, CMS 콘텐츠의 경우 서버 측에서 번역할 수 있습니다.
    • 
        

      

      

        
다음과 같은 경우에는 다른 것을 사용하십시오.

        
    
          
  • 언어별로 하나의 URL이 필요하며, 번역된 페이지가 검색 엔진에 즉시 색인되어야 합니다. next-intl 또는 Paraglide JS를 사용하세요.
    • 
          
  • 번역 내용을 리포지토리에 파일 형태로 저장하고, 풀 리퀘스트를 통해 검토받기를 원하신다면, Paraglide JS 또는 i18next와 함께 inlang을 사용하세요.
    • 
          
  • 귀하의 앱은 React 18, Next.js Pages Router 또는 Next.js 14 이하 버전을 사용하고 있습니다.
    • 
          
  • 귀하의 사이트는 React가 아닌 CMS 또는 웹사이트 빌더로 제작되었습니다. Weglot 의 CMS 연동 기능을 이용해 보세요.
    • 
        

      

    

  







  

    
자주 묻는 질문

    

      

        
SEO를 지원하나요? 언어별로 하나의 URL을 제공하고 hreflang을 지원하나요?

        

          
오늘은 아닙니다. 방문자의 언어는 쿠키에 저장되며, 모든 언어가 동일한 URL에서 제공되므로 검색 엔진은 원본 언어만 색인화합니다.

          
다음과 같이 페이지 제목과 설명을 번역할 수 있습니다. tDynamicAll 에서 generateMetadata. 지금 당장 언어별로 색인된 URL이 필요하다면, next-intl이나 Paraglide JS와 같이 로케일 라우팅 기능을 지원하는 라이브러리를 사용하세요.

        

      

      

        
CMS, API 또는 사용자가 제공하는 동적 콘텐츠를 어떻게 번역하나요?

        

          
이 플러그인은 코드 내에 작성된 텍스트만 번역합니다. 코드에서 전혀 처리하지 않는 콘텐츠의 경우, 다음을 호출하십시오. tDynamic, tDynamicAll 또는 tDynamicHtml 출처: @weglot/translate-react/dynamic Next.js 서버 컴포넌트에서.

          
API 처리 시간이 500ms를 초과하거나, 특정 텍스트에 대한 요청이 처음 이루어지는 경우, 원본 텍스트를 반환합니다. 번역 결과는 이후 요청 시 제공됩니다. 데이터를 직접 캐시하는 경우, 캐시를 방문자의 언어에 따라 다르게 설정해야 합니다.

        

      

      

        
Next.js와 Vite: 무엇이 달라지나요?

        

          
Next.js는 다음을 사용합니다. withWeglot 출처: @weglot/translate-react/next 그리고 WeglotProvider 출처: @weglot/translate-react/react/next. Vite는 weglotPlugin 출처: @weglot/translate-react/vite 그리고 WeglotProvider 출처: @weglot/translate-react/react. Webpack은 weglotPlugin 출처: @weglot/translate-react/webpack.

          
동적 콘텐츠 기능은 Next.js 서버 컴포넌트에서만 실행됩니다.

        

      

      

        
React 서버 컴포넌트와 호환되나요?

        
네, Next.js 앱 라우터를 사용하면 됩니다. 가져오기 WeglotProvider 출처: @weglot/translate-react/react/next 이를 통해 언어를 변경하면 서버 구성 요소가 새로 고쳐집니다. tDynamic, tDynamicAll 그리고 tDynamicHtml 서버 측에서, 서버 구성 요소 내에서 실행됩니다.

      

      

        
빌드하면 어떻게 되나요?

        

          
이 플러그인은 다음 위치의 JSX에서 텍스트를 찾습니다. sourceRoot 그리고 Weglot API에 누락된 번역 내용을 요청합니다. Weglot 는 LLM을 통해 번역문을 생성하며, 빌드 과정은 최대 translationTimeout (기본값은 300초입니다). 그런 다음 다음 내용을 기록합니다. public/translations/<locale>.json.

          
번역에 실패하면 빌드가 실패하고, 수신한 내용을 로컬 캐시에 저장합니다. 계속 진행하려면 다시 빌드하십시오. buildMode: "cache-only", 이 빌드는 네트워크 호출을 수행하지 않습니다.

        

      

      

        
번역본은 어디에 저장되어 있나요?

        
Weglot 프로젝트에서 해당 내용을 검토하고 편집할 수 있습니다. 또한 각 빌드에서는 수신한 번역 내용을 <sourceRoot>/weglot/cache/<locale>.json. API를 호출하지 않고 해당 폴더를 빌드에 포함시키거나, 무시하십시오. public/translations/ 생성되어 다음으로 이동합니다 .gitignore.

      

      

        
어떤 내용이 번역되며, 특정 내용을 제외하려면 어떻게 해야 하나요?

        
JSX 내의 텍스트, JSX 표현식 내의 문자열 리터럴, 상수에서 읽어온 문자열, 그리고 다음과 같은 속성들: title, alt, placeholder 그리고 aria-label. JSX 외부의 코드, URL, 클래스 이름 및 문자열은 변경되지 않습니다. 추가 translate="no" 또는 data-weglot-skip 요소를 원본 언어로 유지하려면. 다음을 사용하여 사용자 정의 텍스트 속성을 선언하세요. translatableAttributes.

      

    

  







  

    
React 앱을 다시 작성하지 않고도 다국어 지원이 가능하게 만드세요

    
패키지를 설치하고, API 키를 추가한 다음 빌드하세요.

    

      
터미널

      
$ npm install @weglot/translate-react

    

    

      
      API 키를 발급받으세요
    

    
직접 해보고 싶으신가요? 문서를 읽어보거나 npm에서 패키지를 확인해 보세요.