What are local translations?

Local translations are stored in your app's bundle, as opposed to being fetched from a CDN (Content Distribution Network). When you add the gtx-cli translate command to your build process, this generates translations in JSON format. The final step is getting these translations into your app where they can be used.

There are two ways to do this:

1. In your app's bundle (local): Save translations to your app's bundle after generation
2. In a CDN (default): Fetch translations from a CDN at runtime

By default, gt-next fetches translations from the General Translation CDN. When translating your app using our API, translations are automatically saved to our CDN.

Trade-offs

Benefits of Local Translations

• Faster load times: Local translations are served directly from your app, loading faster than translations served from a CDN
• No reliance on external services: Your app's ability to load translations isn't dependent on CDN uptime. If translations aren't found for a locale, the app automatically falls back to the default language
• Works offline: Translations are bundled with your app

Drawbacks of Local Translations

• Increased bundle size: Local translations increase your app's bundle size, potentially making the app slower to load initially
• Content management: To edit a translation, you must redeploy your app with the new translation every time you make changes

Setup

Step 1: Create Load Function

Add a loadTranslations.[js|ts] file under ./src with the following content:

export default async function loadTranslations(locale: string) {
  const translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}

withGTConfig automatically picks up the loadTranslations.[js|ts] file from your src/ directory or project root.

Step 2: Configure CLI

Run the configuration command and select local storage:

npx gtx-cli configure

When prompted:

• Save to CDN? Select "No"
• Translation directory: Enter ./public/_gt

Alternatively, you can manually configure the gt.config.json file to use local translations. See the CLI Configuration docs for more information.

Step 3: Generate Translations

Now when you run the translate command, translations will be automatically downloaded and included in your codebase:

npx gtx-cli translate

Translations will be stored in public/_gt/ and bundled with your app.

Build Integration

Next.js Build Process

Add translation generation to your build script:

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

CI/CD Pipeline

# .github/workflows/deploy.yml
- name: Generate Translations
  run: npx gtx-cli translate
  
- name: Build Application  
  run: npm run build

Common Issues

Missing Translation Files

Ensure translations are generated before building:

# ❌ Build without translations
<...YOUR_BUILD_COMMAND...>

# ✅ Generate translations first
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

Import Path Errors

Match your directory structure in the load function:

// ❌ Wrong path
const t = await import(`../translations/${locale}.json`);

// ✅ Correct path for public/_gt
const t = await import(`../public/_gt/${locale}.json`);

Large Bundle Size

Consider code splitting for apps with many languages:

// Load translations only when needed
export default async function loadTranslations(locale: string) {
  // Only load if locale is active
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Next Steps

• Middleware Guide - Language detection and routing
• Languages Guide - Configure supported languages
• API References: