Migrating

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.

npm i gt-next
npm i --save-dev gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

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.

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["en", "fr", "es"]
}

Then, add the <GTProvider> component to the root layout of your app.

app/layout.tsx

import { GTProvider } from 'gt-next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  )
}

Next, add withGTConfig to your next.config.js file.

next.config.ts

import withGTConfig from 'gt-next/next-config'
const nextConfig = {
  // Your next.config.ts options
}
export default withGTConfig(nextConfig, {
  // Your GT configuration
})

For more detailed steps, see the quickstart guide.

At this point, you have 3 options:

Fully migrate your entire project to gt-next, and remove the old i18n library.
Fully migrate your project, but keep using dictionaries from the old i18n library.
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 section.

Migration 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 setup 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 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:

dictionary.json

{
  "hello": {
    "description": "Hello, world!"
  }
}

export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}

You'll need to replace it with:

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

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

import { useTranslation } from 'react-i18next'
export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}

import { useDict } from 'gt-next'
export default function MyComponent() {
  const t = useDict()
  return <div>{t('hello.description')}</div>
}

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

Migrating

Overview

Prerequisites

Why migrate?

Setup

Migration strategies

Option 1: Fully migrate your entire project

Option 2: Fully migrate your project, but keep using dictionaries from the old i18n library

Option 3: Keep using the old i18n library for now, and only migrate part of your project to `gt-next`

Migration tips

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

2. Use the `useDict` hook for existing content

3. Using AI

On this page