# General Translation React SDKs (gt-react, gt-next): Translating with dictionaries
URL: https://generaltranslation.com/en-GB/docs/react/guides/translating-with-dictionaries.mdx
---

title: Translating with dictionaries
description: How to translate strings from a central dictionary with the General Translation useTranslations hook across React, Next.js, TanStack Start, and React Native.
related:
  links:
    - /docs/react/guides/translating-strings
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/handling-plurals-and-branches
    - /docs/react/guides/formatting-variables

---

A dictionary keeps your translatable strings in one place, keyed by id, rather than inline in components. This suits teams that prefer centralised copy or are migrating from a key-based i18n library. Most apps can use [`<T>`](/docs/react/guides/translating-jsx) and [`useGT`](/docs/react/guides/translating-strings) instead.

## Provide a dictionary [#provide]

How you register your per-locale dictionaries depends on the framework.

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    Pass your dictionaries to `GTProvider` through the `dictionaries` prop, alongside the required `locale` and `translations`.

    ```tsx
    <GTProvider locale={locale} translations={translations} dictionaries={dictionaries}>
      <App />
    </GTProvider>;
    ```
  </Tab>

  <Tab value="Next.js">
    In Next.js, you do not pass dictionaries to `GTProvider`. Create a dictionary file at your project root and register it with the config plugin, or let it be auto-detected.

    ```json title="dictionary.json"
    {
      "home": { "title": "Welcome back" }
    }
    ```

    ```ts title="next.config.ts"
    import { withGTConfig } from 'gt-next/config';

    export default withGTConfig(nextConfig, { dictionary: './dictionary.json' });
    ```
  </Tab>

  <Tab value="TanStack Start">
    Pass your dictionaries to `GTProvider` through the `dictionaries` prop, alongside the required `locale` and `translations`.

    ```tsx
    <GTProvider locale={locale} translations={translations} dictionaries={dictionaries}>
      <App />
    </GTProvider>;
    ```
  </Tab>

  <Tab value="React Native">
    Pass your dictionaries to `GTProvider` through the `dictionaries` prop, alongside the active `locale`.

    ```tsx
    <GTProvider locale={locale} dictionaries={dictionaries}>
      <App />
    </GTProvider>;
    ```
  </Tab>
</Tabs>

## Look up entries with `useTranslations` [#use-translations]

Call [`useTranslations`](/docs/react/reference/hooks/use-translations) to get a lookup function, then pass an entry id. Interpolate values with an options object.

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    ```tsx
    import { useTranslations } from 'gt-react';

    function Greeting() {
      const t = useTranslations();
      return <h1>{t('home.title')}</h1>;
    }
    ```
  </Tab>

  <Tab value="Next.js">
    ```tsx title="Synchronous components"
    import { useTranslations } from 'gt-next';

    function Greeting() {
      const t = useTranslations();
      return <h1>{t('home.title')}</h1>;
    }
    ```

    ```tsx title="Async App Router components"
    import { getTranslations } from 'gt-next/server';

    async function Greeting() {
      const t = await getTranslations();
      return <h1>{t('home.title')}</h1>;
    }
    ```
  </Tab>

  <Tab value="TanStack Start">
    ```tsx
    import { useTranslations } from 'gt-tanstack-start';

    function Greeting() {
      const t = useTranslations();
      return <h1>{t('home.title')}</h1>;
    }
    ```
  </Tab>

  <Tab value="React Native">
    ```tsx
    import { useTranslations } from 'gt-react-native';

    function Greeting() {
      const t = useTranslations();
      return <Text>{t('home.title')}</Text>;
    }
    ```
  </Tab>
</Tabs>

Pass a root id to scope all lookups under a prefix. This works the same in every framework (`getTranslations('home')` on the Next.js server):

```tsx
const t = useTranslations('home');
t('title'); // resolves home.title
```

*Note: Looking up an id that does not exist in the dictionary throws, so keep ids and dictionary entries in sync.*

## Read nested objects [#objects]

Use `.obj(id)` to read a nested group of entries — for example, to map over a set of labels.

```tsx
const t = useTranslations();
const labels = t.obj('nav.links');
```
## Next steps

- /docs/react/guides/translating-strings
- /docs/react/guides/translating-jsx
- /docs/react/guides/handling-plurals-and-branches
- /docs/react/guides/formatting-variables