# gt-next: General Translation Next.js SDK: Next.js Quickstart
URL: https://generaltranslation.com/en-US/docs/next.mdx
---
title: Next.js Quickstart
description: Easily internationalize your Next.js App with gt-next
---
**Prerequisites:** Next.js 13+ with App Router
**Quick Setup:** Try `npx gtx-cli@latest` for automatic configuration. Run the
[Setup Wizard](/docs/cli/init) or use [Locadex](/docs/locadex/next) to set it up for you.
## Installation
Install the `gt-next` and `gtx-cli` packages:
```bash
npm i gt-next
npm i -D gtx-cli
```
```bash
yarn add gt-next
yarn add --dev gtx-cli
```
```bash
bun add gt-next
bun add --dev gtx-cli
```
```bash
pnpm add gt-next
pnpm add --save-dev gtx-cli
```
## Configuration
### `withGTConfig`
The [`withGTConfig`](/docs/next/api/config/with-gt-config) function initializes the SDK in your NextJS application. Add it to your `next.config.[js|ts]` file:
```tsx title="next.config.ts"
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Your existing Next.js config
};
export default withGTConfig(nextConfig, {
// Additional GT configuration options
});
```
### `GTProvider`
The [`GTProvider`](/docs/next/api/components/gtprovider) component provides translation context to client-side components. It manages locale state, translations, and enables the [`useGT`](/docs/next/api/strings/use-gt) and [`useTranslations`](/docs/next/api/dictionary/use-translations) hooks.
Add the [`GTProvider`](/docs/next/api/components/gtprovider) to your root layout(s):
```tsx title="app/layout.tsx"
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
{children}
);
}
```
Create a [`gt.config.json`](/docs/cli/reference/config) file in your project root:
```json title="gt.config.json"
{
"defaultLocale": "en",
"locales": ["fr", "es", "de"]
}
```
Customize the locales for your project. See [supported locales](/docs/platform/supported-locales) for options.
### Environment variables
Add to your `.env.local` file for development hot-reloading and on-demand translations:
```bash title=".env.local"
GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"
```
**Dev vs prod keys:** Use a `gtx-dev-` key locally. Use a `gtx-api-` key in CI/CD if you run `gtx-cli translate` during deploy.
Never expose `GT_API_KEY` to the browser or commit it to source control.
Get your free API keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or run:
```bash
npx gtx-cli auth
```
`gt-next` is an i18n library that can work standalone without any environment variables.
Without them, the library will act very similarly to other i18n libraries, and will still have core internationalization functionality.
However, `gt-next` also offers a native integration with the General Translation platform.
This integration unlocks additional functionality in the library, such as:
- Translation Hot Reloading in Development
- Automatic AI translations
- Syncing translations with the General Translation platform
- On-demand translation of React components in production (on the server side)
To avoid using the General Translation platform, just don't set any environment variables.
---
## Usage
Now you can start internationalizing your content. There are two main approaches:
### JSX content with T
Wrap JSX elements to translate them using the [``](/docs/next/api/components/t) component:
```tsx
import { T } from 'gt-next';
function Welcome() {
return (
Welcome to our app!
);
}
```
For dynamic content, use [variable components](/docs/next/guides/variables) like [``](/docs/next/api/components/var):
```tsx
import { T, Var } from 'gt-next';
function Greeting({ user }) {
return (
Hello, {user.name}!
);
}
```
See the guide on [using the `` component](/docs/next/guides/t) for more information.
### Plain strings with useGT
For attributes, labels, and plain text using the [`useGT`](/docs/next/api/strings/use-gt) hook:
```tsx
import { useGT } from 'gt-next';
function ContactForm() {
const gt = useGT();
return (
);
}
```
For server components, use [`getGT`](/docs/next/api/strings/get-gt) instead of [`useGT`](/docs/next/api/strings/use-gt).
See the guide on [translating strings](/docs/next/guides/strings) for more information.
---
## Testing your app
Test your translations by switching languages:
1. **Add a locale selection dropdown** using [``](/docs/next/api/components/locale-selector):
```tsx
import { LocaleSelector } from 'gt-next';
function App() {
return ;
}
```
2. **Start your dev server**:
```bash
npm run dev
```
```bash
yarn run dev
```
```bash
bun run dev
```
```bash
pnpm run dev
```
3. **Visit [localhost:3000](http://localhost:3000)** and change languages via the locale selection dropdown.
In development, translations happen on-demand (you'll see a brief loading time). In production, translations are pre-generated by the CLI.
### Troubleshooting
**Browser Cookies**
If you are deciding to test different languages by changing your browser's language, this issue may occur.
Check your browser's cookies for your app.
General translation uses cookies to store the user's language preference.
The cookie is called `generaltranslation.locale`, and all you need to do is delete it.
Then, just double check you are using the desired perferred language and then
refresh the page.
How to check cookies:
* [Chrome](https://support.google.com/chrome/answer/95647)
* [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
* [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
* [Edge](https://support.microsoft.com/en-us/microsoft-edge/delete-cookies-in-microsoft-edge-63947406-40ac-c3b8-57b9-2a946a29ae09)
**On-Demand Translation**
You may notice when loading languages in development, translations will take a few seconds to be displayed.
This happens because your app is being translated in real time.
We refer to this process as an "on-demand translation".
This **only happens in dev** so you can easily prototype your website in different languages.
All translations are preloaded in production, so there will be no delay.
Follow our guide on [shipping to production](/docs/next/tutorials/quickdeploy).
The most likely cause of an inaccurate translation is ambiguous wording.
For example, "apple" can be a fruit or a technology company.
To fix this, you can provide more context to the translation with the `context` prop.
The [``](/docs/next/api/components/t), [`useGT`](/docs/next/api/strings/use-gt), and [`getGT`](/docs/next/api/strings/get-gt) functions all support a `context` prop.
For example:
```jsx
Apple
```
---
## Deployment
For production, you need to pre-translate content since runtime translation is disabled (except for [``](/docs/next/api/components/tx) and [`tx`](/docs/next/api/strings/tx) functions).
1. **Get a production API key** from [dash.generaltranslation.com](https://dash.generaltranslation.com).
Production keys begin with `gtx-api-` (different from dev keys which start with `gtx-dev-`). Learn more about [environment differences](/docs/next/concepts/environments).
2. **Add to your CI/CD environment**:
```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
**Never** prefix production keys with `NEXT_PUBLIC_` - they should remain
server-side only.
3. **Run the translate command** to translate your content:
```bash
npx gtx-cli translate
```
You can configure the behavior of the translate command with the [`gt.config.json`](/docs/cli/reference/config) file.
See the [CLI Tool](/docs/cli/translate) reference guide for more information.
4. **Update your build script** to translate before building:
```json title="package.json"
{
"scripts": {
"build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
}
}
```
If you're not using the General Translation platform, you can still use `gt-next` in production.
However, you'll need to manually translate your content before deploying your application.
Instead of running `translate`, run the `generate` command to generate JSON files containing all of your translation data (in your source language).
```bash
npx gtx-cli generate
```
Then, you'll need to manually edit / translate these files, and load them into your application with [`loadTranslations`](/docs/next/guides/local-tx).
## Next steps
- [`` Component Guide](/docs/next/guides/t) - Deep dive into the [``](/docs/next/api/components/t) component and JSX translation
- [String Translation Guide](/docs/next/guides/strings) - Using [`useGT`](/docs/next/api/strings/use-gt) and [`getGT`](/docs/next/api/strings/get-gt)
- [Variable Components](/docs/next/guides/variables) - Handle dynamic content with [``](/docs/next/api/components/var), [``](/docs/next/api/components/num), etc.