Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Getting started

Install the Weglot package on your Next.js or Vite app.

Requirements

Requirement
Version

Node.js

20.9 or later

React

19

Next.js (App Router), if you use Next.js

15, or 16.0.4 or later

You also need a Weglot 2.0 project. Sign in to Weglot 2.0, create a project with its source and target languages, then copy its API key: in your project settings, under API key. It starts with pk_.

1. Install the package

npm install @weglot/translate-react

2. Add your API key

Add it to the .env file at the root of your app, and keep this file out of version control:

# .env
WEGLOT_API_KEY=pk_your_weglot_api_key

3. Add the plugin

Wrap your Next.js configuration with withWeglot. Set sourceRoot to the folder that contains all your pages and components:

// 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" });
}
// vite.config.ts
import { defineConfig } from "vite";
import { weglotPlugin } from "@weglot/translate-react/vite";

export default defineConfig({
  plugins: [weglotPlugin({ sourceRoot: "src" })],
});

With Webpack, use weglotPlugin from @weglot/translate-react/webpack the same way.

4. Add the provider

Wrap your app with WeglotProvider, as early as possible:

Import the Next.js provider, from @weglot/translate-react/react/next, so that changing language refreshes your server components:

5. Ignore the generated files

Each build writes public/translations/<locale>.json: add this folder to your .gitignore.

The translations received from Weglot are kept in <sourceRoot>/weglot/cache/<locale>.json. Commit this folder to build without calling the API (see Build modes), or ignore it and let each build fetch the translations it lacks.

Text written in your code is now translated. To let visitors change language, add a language switcher. To translate content from a CMS or an API, see Dynamic content.

Last updated