# General Translation React SDKs (gt-react, gt-next, gt-react-native): React Router Quickstart
URL: https://generaltranslation.com/en-US/docs/react/react-router-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Add General Translation to a React Router framework app, including Shopify Hydrogen storefronts, and translate your first content.
`gt-react` runs in React Router framework mode through your root route. You initialize the library in `app/root.tsx`, resolve each visitor's locale in the root loader, and render [`GTProvider`](/docs/react/reference/components/gt-provider) from the root `Layout`.
Use this quickstart for apps built with `@react-router/dev`. If you use React Router as a library inside a Vite single-page app, follow the [React SPA Quickstart](/docs/react/react-spa-quickstart) instead.
Run [`npx gt@latest init`](/docs/cli/reference/commands/init) from the app root to automate the setup. The wizard installs `gt-react`, creates the config and translation loader, and configures an `app/root.tsx` from the create-react-router or Hydrogen starter. It leaves other roots unchanged and lists any manual actions; this guide covers the same setup by hand.
*Note: This setup requires `gt-react` 11.1.3 or later and an app that renders on each request. SPA mode (`ssr: false`), pre-rendering, and RSC Framework Mode are not supported.*
## Quickstart [#quickstart]
### 1. Install the packages
`gt-react` is the library that powers translations in your app. `gt` is the CLI that generates them.
```bash
npm install gt-react && npm install gt --save-dev
```
```bash
yarn add gt-react && yarn add --dev gt
```
```bash
bun add gt-react && bun add --dev gt
```
```bash
pnpm add gt-react && pnpm add --save-dev gt
```
### 2. Create `gt.config.json`
Create a `gt.config.json` file in your project root. It declares your source language, your target locales, and where translation files are written.
```json title="gt.config.json"
{
"defaultLocale": "en",
"locales": ["es", "ja"],
"files": {
"gt": {
"output": "app/_gt/[locale].json"
}
}
}
```
- `defaultLocale` — the language your app is written in.
- `locales` — the languages to translate into. Pick from the [supported locales](/docs/platform/dashboard/reference/supported-locales).
- `files.gt.output` — where the CLI writes translation files. Keep them under `app/` so Vite bundles them with your server and client code.
### 3. Create a translation loader
Create `app/loadTranslations.ts`. It imports a locale's translation file when the root loader requests it.
```ts title="app/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
const translations = await import(`./_gt/${locale}.json`);
return translations.default;
}
```
Then create an empty `{}` file for each target locale, such as `app/_gt/es.json` and `app/_gt/ja.json`; [`gt init`](/docs/cli/reference/commands/init) creates these for you. A locale without a translation file renders in your default language.
### 4. Set up the root route
Call [`initializeGT`](/docs/react/reference/config#initialize) once at module scope in `app/root.tsx`, return the locale and a translations snapshot from the root loader, and wrap the `Layout` content in [`GTProvider`](/docs/react/reference/components/gt-provider). Add the highlighted lines to your existing root:
```tsx title="app/root.tsx"
import {
Links,
Meta,
Outlet,
Scripts,
ScrollRestoration,
useRouteLoaderData, // [!code ++]
} from 'react-router';
import { GTProvider, getTranslationsSnapshot, initializeGT, parseLocale } from 'gt-react'; // [!code ++]
import type { Route } from './+types/root';
import gtConfig from '../gt.config.json'; // [!code ++]
import loadTranslations from './loadTranslations'; // [!code ++]
import './app.css';
initializeGT({ ...gtConfig, loadTranslations }); // [!code ++]
// [!code ++:11]
// Error pages have no loader data. Skip GTProvider there so it doesn't
// replace the visitor's saved locale with the default.
function RootGTProvider({ children }: { children: React.ReactNode }) {
const data = useRouteLoaderData('root');
if (!data) return <>{children};
return (
{children}
);
}
// [!code ++:4]
export async function loader({ request }: Route.LoaderArgs) {
const locale = parseLocale(request);
return { locale, translations: await getTranslationsSnapshot(locale) };
}
export function Layout({ children }: { children: React.ReactNode }) {
const locale = useRouteLoaderData('root')?.locale ?? gtConfig.defaultLocale; // [!code ++]
return (
// [!code ++]
{/* [!code ++] */}
{children}
{/* [!code ++] */}
);
}
export default function App() {
return ;
}
```
`parseLocale` reads the locale cookie, then the `Accept-Language` header, and falls back to `defaultLocale`. If your root already has a `loader`, add `locale` and `translations` to the object it returns.
*Note: Error pages without root loader data, such as a direct 404 or a root loader error, render without [`GTProvider`](/docs/react/reference/components/gt-provider). Translation components and hooks, such as [``](/docs/react/reference/components/t) and [`useLocale`](/docs/react/reference/hooks/use-locale), throw there and turn the error page into a server error, so keep the root `ErrorBoundary` untranslated.*
### 5. Mark content for translation
Wrap JSX in the [``](/docs/react/reference/components/t) component to translate it in place, and use [`useGT`](/docs/react/reference/hooks/use-gt) for plain strings such as `aria-label` values. Add a [``](/docs/react/reference/components/locale-selector) so visitors can switch languages.
```tsx title="app/routes/home.tsx"
import { LocaleSelector, T, useGT } from 'gt-react';
export default function Home() {
const gt = useGT();
return (