Migrating
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 currently uses another i18n library.
- A basic understanding of the
gt-nextlibrary.
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 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 in development with hot reloading.
Set-up
Install gt-next and the gtx-cli CLI tool.
npm i gt-next gtx-cliyarn add gt-next
yarn add --dev gtx-clibun add gt-next
bun add --dev gtx-clipnpm add gt-next
pnpm add --save-dev gtx-cliCreate a gt.config.json file in the root of your project containing a defaultLocale property and a locales array.
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}Then add the <GTProvider> component to the root layout of your app.
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.
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 quick-start guide.
At this point, you have three options:
- Fully migrate your entire project to
gt-nextand 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 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:
{
"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 you want to migrate your project to gt-next, but you’d like 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.
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}import { useTranslations } from 'gt-next'
export default function MyComponent() {
const t = useTranslations()
return <div>{t('hello.description')}</div>
}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 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 fewest 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 use gt-next only for others and for new content.
This option isn’t recommended, as you’ll 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 <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 future, and make your codebase far 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 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, we have LLMs.txt and LLMs-full.txt available at:
How is this guide?