# gt-next: General Translation Next.js SDK: Migrating
URL: https://generaltranslation.com/en-US/docs/next/guides/migration.mdx
---
title: Migrating
description: Learn how to migrate a project to gt-next
---
## Overview
This guide will cover the steps needed to migrate a project that's already using an i18n library to gt-next.
We'll also provide some tips and suggestions for how to make the migration as smooth as possible.
## Prerequisites
- A project that is currently using another i18n library.
- A basic understanding of the `gt-next` library.
## Why migrate?
There are many reasons why you might want to migrate your project to gt-next.
Here are just a few:
- **No more JSON files:** Never manage translations in JSON files again.
All of your content lives in-line with your code, where it belongs.
- **Automatic translations:** Generate high quality, context-aware translations with our CLI tool.
You'll never have to wait for translations again.
- **Experiment in dev:** Easily experiment with translations in development with translation hot-reloading.
## Setup
Install `gt-next` and the `gtx-cli` CLI tool.
```bash
npm i gt-next 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
```
Create a `gt.config.json` file in the root of your project containing a `defaultLocale` property and a `locales` array.
```json title="gt.config.json" copy
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}
```
Then, add the `` component to the root layout of your app.
```tsx title="app/layout.tsx" copy
import { GTProvider } from 'gt-next'
export default function RootLayout({ children }) {
return (
{children}
)
}
```
Next, add `withGTConfig` to your `next.config.js` file.
```js title="next.config.ts" copy
import { withGTConfig } from 'gt-next/config'
const nextConfig = {
// Your next.config.ts options
}
export default withGTConfig(nextConfig, {
// Your GT configuration
})
```
For more detailed steps, see the [quickstart guide](/docs/next).
At this point, you have 3 options:
1. Fully migrate your entire project to `gt-next`, and remove the old i18n library.
2. Fully migrate your project, but keep using dictionaries from the old i18n library.
2. Keep using the old i18n library for now, and only migrate part of your project to `gt-next`.
For more details on each option, see the [migration strategies](#strategies) section.
## Migration strategies [#strategies]
### Option 1: Fully migrate your entire project
This option is the most straightforward, and will also require the most code changes in one go.
After you've set up your project, you'll need to search for all instances of your old i18n library and replace them with `gt-next`.
If your app is using React hooks such as `useTranslations`, search for all instances of `useTranslations` in your codebase and replace them with `useGT`.
Then, you'll need to replace all the string keys with their actual string values.
For example, if your old code looks like this:
```json title="dictionary.json"
{
"hello": {
"description": "Hello, world!"
}
}
```
```tsx
export default function MyComponent() {
const { t } = useTranslation()
return {t('hello.description')}
}
```
You'll need to replace it with:
```tsx
export default function MyComponent() {
const gt = useGT()
return {gt('Hello, world!')}
}
// OR
export default function MyComponent() {
return Hello, world!
}
```
Do this for all instances of your old i18n library.
### Option 2: Fully migrate your project, but keep using dictionaries from the old i18n library
Let's say that you want to migrate your project to `gt-next`, but you want to keep using dictionaries from the old i18n library
and only use GT in-line features for new content.
In this case, you can do something similar to Option 1:
Find all instances of your old i18n library, such as `useTranslations` hooks, and replace them with `useTranslations` hooks from `gt-next`.
The `useTranslations` hook behaves very similarly to `useTranslations` hooks in other i18n libraries, and you can use it in the same way.
```tsx
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
const { t } = useTranslation()
return {t('hello.description')}
}
```
```tsx
import { useTranslations } from 'gt-next'
export default function MyComponent() {
const t = useTranslations()
return {t('hello.description')}
}
```
In terms of configuration, you'll need to create a `dictionary.[js|ts|json]` file in your project root or `src` directory.
Copy the contents of your old dictionary file into this new file.
The initialization `withGTConfig` function in `next.config.js` will automatically pick up the dictionary file in your project root or `src` directory.
See the [dictionaries](/docs/next/guides/dictionaries) guide for more details.
### Option 3: Keep using the old i18n library for now, and only migrate part of your project to `gt-next`
This option is the most flexible, and will require the least code changes in one go.
In this case, you can do something similar to Option 2, but only migrate part of your project to `gt-next`.
For example, you can keep using the old i18n library for some components, and only use `gt-next` for others and for new content.
This option is not recommended, as you will have to manage two different i18n libraries in your project, which may be complex and lead to bugs.
## Migration tips
### 1. Use the `useGT` hook or `` component as much as possible
Wherever possible, we recommend using the `useGT` hook or `` component.
This will make editing your content much easier in the future, and make your codebase much more readable.
### 2. Use the `useTranslations` hook for existing content
The `useTranslations` hook is a great way to keep using your existing dictionaries.
We offer it as a way to make migration easier, but we don't recommend using it for new content.
### 3. Using AI
If you are using AI to help you migrate your project, we have a `LLMs.txt` and `LLMs-full.txt` available at:
- [LLMs.txt](/llms.txt)
- [LLMs-full.txt](/llms-full.txt)