Dashboard

Dictionaries

How to use traditional dictionary-based translation patterns

Dictionaries offer a traditional way to organise translations in nested objects with key–value pairs. While <T> components are the recommended approach, dictionaries can be useful when migrating from other i18n libraries or if you prefer centralised translation storage.

Recommendation: Use <T> components for new projects. Dictionaries are supported primarily for migration and compatibility with existing translation workflows.

Dictionary vs Component Translation

Dictionary pattern

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

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

Component Pattern

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

Trade-offs

Dictionary advantages

  • Centralised storage — all translations in one place
  • Industry standard — familiar pattern from other i18n libraries
  • Migration‑friendly — easy to port existing translations

Dictionary disadvantages

  • Complexity - Requires more setup and configuration
  • Maintainability - Separating content from usage makes updates harder
  • Debuggability - Harder to trace translations back to components
  • Readability - Keys don’t reveal the actual content

Quick start

Step 1: Create a dictionary

Create a dictionary file in your project root or src directory:

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:

dictionary.json
{
  "greetings": {
    "hello": "Hello, world!",
    "welcome": "Welcome to our app!"
  },
  "navigation": {
    "home": "Home", 
    "about": "About",
    "contact": "Contact"
  }
}

The withGTConfig function will automatically pick up the dictionary file in your project root or src directory.

Step 2: Use in Components

The useTranslations hook lets you access dictionary entries:

Client Components

import { useTranslations } from 'gt-next';

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

Server Components

import { getTranslations } from 'gt-next/server';

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

Using variables

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

dictionary.ts
const dictionary = {
  user: {
    greeting: 'Hello, {name}!',
    itemCount: 'You have {count} items',
    orderTotal: 'Total: ${amount}'
  }
};
function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Using prefixes

Limit dictionary access to specific sections using prefixes:

dictionary.ts
const dictionary = {
  dashboard: {
    header: {
      welcome: 'Welcome back!',
      lastLogin: 'Last login: {date}'
    },
    stats: {
      totalUsers: 'Total users: {count}',
      activeUsers: 'Active users: {count}'
    }
  }
};
function DashboardHeader() {
  // Prefix restricts access to 'dashboard.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

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

Multiple Language Support

Most users should use loadTranslations to automatically generate translations from your base dictionary:

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

export default dictionary;

Create a loadTranslations function to load the generated translation files:

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

withGTConfig automatically picks up the loadTranslations.[js|ts] file from your src/ directory or the 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 migrations from other i18n libraries, or for managing translations manually, use loadDictionary:

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:

es.json
fr.json
de.json

Choose the right approach: Use loadTranslations for new projects with automatic translation generation, or loadDictionary when migrating existing translation files.

Production setup

Build process

Add translation to your build pipeline:

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

Development vs Production Behaviour

  • Development: Dictionary entries translated on demand with a dev API key
  • Production: All dictionary translations prebuilt during the build step

Combining with components

Dictionaries and <T> components can work together:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Dictionary for simple strings */}
      <h1>{d('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>{d('forms.email')}</label>
    </div>
  );
}

Next Steps

How is this guide?

Dynamic content

How to translate runtime content using server-side translation APIs

Changing languages

How to configure and switch between languages in your Next.js app

On this page

Dictionary vs Component Translation
Dictionary pattern
Component Pattern
Trade-offs
Dictionary advantages
Dictionary disadvantages
Quick start
Step 1: Create a dictionary
Step 2: Use in Components
Client Components
Server Components
Using variables
Using prefixes
Multiple Language Support
Automatic translation (recommended)
Manual Translation Files (Migration)
Production setup
Build process
Development vs Production Behaviour
Combining with components
Next Steps
Dictionaries