# gt-react: General Translation React SDK: Migrating
URL: https://generaltranslation.com/en-US/docs/react/guides/migration.mdx
---
title: Migrating
description: Learn how to migrate a project to gt-react
---
{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */}


## Overview

This guide will cover the steps needed to migrate a project that's already using an i18n library to `gt-react`.

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-react` library.

## Why migrate?

There are many reasons why you might want to migrate your project to `gt-react`.

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

<Steps>
  <Step>
    Install `gt-react` and the `gtx-cli` CLI tool.


<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
  ```bash
  npm i gt-react
  npm i gtx-cli
  ```
  </Tab>
  <Tab value="yarn">
  ```bash
  yarn add gt-react
  yarn add --dev gtx-cli
  ```
  </Tab>

  <Tab value="bun">
  ```bash
  bun add gt-react
  bun add --dev gtx-cli
  ```
  </Tab>
  <Tab value="pnpm">
  ```bash
  pnpm add gt-react
  pnpm add --save-dev gtx-cli
  ```
  </Tab>
</Tabs>
  </Step>
  <Step>
    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"]
    }
    ```

    Add the `<GTProvider>` component to the root of your app, and spread the `config` object as props.

    ```tsx
    import { GTProvider } from 'gt-react'
    import config from './gt.config.json'

    <GTProvider {...config}>
      <App />
    </GTProvider>
    ```
    For more detailed steps, see the [project quickstart](/docs/react) guide.
  </Step>
  <Step>
    At this point, you have 3 options:

    1. Fully migrate your entire project to `gt-react`, 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-react`.

    For more details on each option, see the [migration strategies](#strategies) section.
  </Step>
</Steps>

## 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-react`.

If your app is using React hooks such as `useTranslation`, search for all instances of `useTranslation` 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 <div>{t('hello.description')}</div>
}
```

You'll need to replace it with:

```tsx
export default function MyComponent() {
  const { t } = useGT()
  return <div>{t('Hello, world!')}</div>
}
// OR
export default function MyComponent() {
  return <T>Hello, world!</T>
}
```

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-react`, 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 `useTranslation` hooks, and replace them with `useTranslations` hooks.

The `useTranslations` hook behaves very similarly to `useTranslation` hooks, and you can use it in the same way.

<Tabs items={['Before', 'After']}>
  <Tab value="Before">
  ```tsx
  import { useTranslation } from 'react-i18next'
  export default function MyComponent() {
    const { t } = useTranslation()
    return <div>{t('hello.description')}</div>
  }
  ```
  </Tab>
  <Tab value="After">
  ```tsx
  import { useTranslations } from 'gt-react'
  export default function MyComponent() {
    const t = useTranslations()
    return <div>{t('hello.description')}</div>
  }
  ```
  </Tab>
</Tabs>

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, then pass it to the `GTProvider` component.

```tsx
import { GTProvider } from 'gt-react'
import dictionary from './dictionary.json'
import config from './gt.config.json'

<GTProvider {...config} dictionary={dictionary}>
  <App />
</GTProvider>
```

See the [dictionaries](/docs/react/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-react`

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-react`.

For example, you can keep using the old i18n library for some components, and only use `gt-react` for others and for new content.

<Callout type="warn">
  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.
</Callout>

## Migration tips

### 1. Use the `useGT` hook or `<T>` component as much as possible

Wherever possible, we recommend using the `useGT` hook or `<T>` 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)

These files contain the full content of these docs, so your AI tool will have access to all the information it needs to help you migrate your project.