# gt-next: General Translation Next.js SDK: Dictionaries
URL: https://generaltranslation.com/en-US/docs/next/guides/dictionaries.mdx
---
title: Dictionaries
description: How to use traditional dictionary-based translation patterns
---

Dictionaries provide a traditional approach to organizing translations in nested objects with key-value pairs. While [`<T>` components](/docs/next/guides/t) are the recommended approach, dictionaries can be useful for migration from other i18n libraries or when you prefer centralized translation storage.

<Callout>
  **Recommendation:** Use [`<T>` components](/docs/next/guides/t) for new projects. Dictionaries are supported primarily for migration and compatibility with existing translation workflows.
</Callout>

## Dictionary vs Component Translation

### Dictionary pattern
```tsx
// dictionary.ts
export default {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome, {name}!'
  }
};

// Component usage
function MyComponent() {
  const t = useTranslations();
  return <div>{t('greetings.hello')}</div>;
}
```

### Component pattern
```tsx
// Direct component usage - recommended
function MyComponent() {
  return <T><div>Hello, world!</div></T>;
}
```

## Trade-offs

### Dictionary advantages
- **Centralized storage** - All translations in one place
- **Industry standard** - Familiar pattern from other i18n libraries
- **Migration friendly** - Easy to port existing translations

### Dictionary disadvantages
- **Complexity** - More setup and configuration required
- **Maintainability** - Content separated from usage makes updates harder
- **Debuggability** - Harder to trace translations back to components
- **Readability** - Keys don't show actual content

## Quick start

### Step 1: Create Dictionary
Create a dictionary file in your project root or `src` directory:

```ts title="dictionary.ts"
const dictionary = {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome to our app!'
  },
  navigation: {
    home: 'Home',
    about: 'About',
    contact: 'Contact'
  }
};

export default dictionary;
```

Or use JSON format:
```json title="dictionary.json"
{
  "greetings": {
    "hello": "Hello, world!",
    "welcome": "Welcome to our app!"
  },
  "navigation": {
    "home": "Home", 
    "about": "About",
    "contact": "Contact"
  }
}
```

The [`withGTConfig`](/docs/next/api/config/with-gt-config) function will automatically pick up the dictionary file in your project root or `src` directory.

### Step 2: Use in Components

The [`useTranslations`](/docs/next/api/dictionary/use-translations) hook lets you access dictionary entries:

#### Client Components
```tsx
import { useTranslations } from 'gt-next';

function MyComponent() {
  const t = useTranslations();
  
  return (
    <div>
      <h1>{t('greetings.hello')}</h1>
      <p>{t('greetings.welcome')}</p>
    </div>
  );
}
```

#### Server Components
```tsx
import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{t('greetings.hello')}</h1>
      <p>{t('greetings.welcome')}</p>
    </div>
  );
}
```

## Using variables

Add variables to dictionary entries using `{variable}` syntax:

```ts title="dictionary.ts"
const dictionary = {
  user: {
    greeting: 'Hello, {name}!',
    itemCount: 'You have {count} items',
    orderTotal: 'Total: ${amount}'
  }
};
```

```tsx
function UserDashboard() {
  const t = useTranslations();
  
  return (
    <div>
      <h1>{t('user.greeting', { name: 'Alice' })}</h1>
      <p>{t('user.itemCount', { count: 5 })}</p>
      <p>{t('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}
```

## Using prefixes

Scope dictionary access to specific sections using prefixes:

```ts title="dictionary.ts"
const dictionary = {
  dashboard: {
    header: {
      welcome: 'Welcome back!',
      lastLogin: 'Last login: {date}'
    },
    stats: {
      totalUsers: 'Total Users: {count}',
      activeUsers: 'Active Users: {count}'
    }
  }
};
```

```tsx
function DashboardHeader() {
  // Prefix limits access to 'dashboard.header'
  const t = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{t('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{t('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Different prefix for stats section
  const t = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{t('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{t('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}
```

## Multiple language support

### Automatic translation (recommended)
Most users should use [`loadTranslations`](/docs/next/api/config/load-translations) to automatically generate translations from your base dictionary:

```ts title="dictionary.ts"  
const dictionary = {
  common: {
    save: 'Save',
    cancel: 'Cancel',
    delete: 'Delete'
  },
  forms: {
    required: 'This field is required',
    email: 'Please enter a valid email'
  }
};

export default dictionary;
```

Create a `loadTranslations` function to load generated translation files:

```js title="src/loadTranslations.ts"
export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}
```

[`withGTConfig`](/docs/next/api/config/with-gt-config) automatically picks up the `loadTranslations.[js|ts]` file from your `src/` directory or project root.

GT automatically generates translations for other languages based on your base dictionary. Run `npx gtx-cli translate` to generate translations for all configured languages.

### Manual translation files (migration)
For migration from other i18n libraries or manual translation management, use [`loadDictionary`](/docs/next/api/config/load-dictionary):

```ts title="src/loadDictionary.ts"
export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}
```

This loads JSON translation files from your `public/locales/` directory:

<Files>
  <Folder name="my-app" defaultOpen={true}>
    <Folder name="public" defaultOpen={true}>
      <Folder name="locales" defaultOpen={true}>
        <File name="es.json" />
        <File name="fr.json" />
        <File name="de.json" />
      </Folder>
    </Folder>
    <Folder name="src">
      <File name="loadDictionary.ts" />
    </Folder>
  </Folder>
</Files>

<Callout>
  **Choose the right approach:** Use [`loadTranslations`](/docs/next/api/config/load-translations) for new projects with automatic translation generation, or [`loadDictionary`](/docs/next/api/config/load-dictionary) when migrating existing translation files.
</Callout>

## Production setup

### Build process
Add translation to your build pipeline:

```json title="package.json"
{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}
```

### Development vs Production Behavior
- **Development**: Dictionary entries translated on-demand with dev API key
- **Production**: All dictionary translations pre-built during build step

## Combining with Components

Dictionaries and [`<T>` components](/docs/next/guides/t) can work together:

```tsx
function MixedApproach() {
  const t = useTranslations();
  
  return (
    <div>
      {/* Dictionary for simple strings */}
      <h1>{t('page.title')}</h1>
      
      {/* T component for complex JSX */}
      <T>
        <p>This is a <strong>complex message</strong> with <a href="/link">links</a>.</p>
      </T>
      
      {/* Dictionary for form labels */}
      <label>{t('forms.email')}</label>
    </div>
  );
}
```

## Next steps

- [Languages Guide](/docs/next/guides/languages) - Configure supported languages and locale settings
- [Dynamic Content Guide](/docs/next/guides/dynamic-content) - Handle runtime translation needs
- API References:
  - [`useTranslations` Hook](/docs/next/api/dictionary/use-translations)
  - [`getTranslations` Function](/docs/next/api/dictionary/get-translations)