# gt-next: General Translation Next.js SDK: Migrating
URL: https://generaltranslation.com/en-GB/docs/next/guides/migration.mdx
---
title: Migrating
description: Learn how to migrate a project to gt-next
---
## Overview
This guide covers 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 to help make the migration as smooth as possible.
## Prerequisites
* A project that's 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 your content lives inline 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 during development with hot reloading.
## Setup
Install `gt-next` and the `gt` CLI tool.
```bash
npm i gt-next gt
```
```bash
yarn add gt-next
yarn add --dev gt
```
```bash
bun add gt-next
bun add --dev gt
```
```bash
pnpm add gt-next
pnpm add --save-dev gt
```
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.
3. 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 uses 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 every instance of your old i18n library.
### Option 2: Fully migrate your project, but keep using dictionaries from the old i18n library
Suppose 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 inline 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')}
}
```
For 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 initialisation function `withGTConfig` 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 fewest code changes at once.
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 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're using AI to help migrate your project, `LLMs.txt` and `LLMs-full.txt` are available at:
* [LLMs.txt](/llms.txt)
* [LLMs-full.txt](/llms-full.txt)