Local Translations

What are local translations?

Local translations are stored in your app's bundle, as opposed to being fetched from a CDN (Content Distribution Network).

Let's say that you have added the gtx-cli translate command to your CD process. This will generate translations in JSON format for your app. The final step is to get these translations out of our API and into your app, where they can be used.

There are two ways to do this:

In your app's bundle: After translations are generated, save them to your app's bundle.
In a CDN (default): Fetch translations from a CDN at runtime.

By default, gt-react will fetch translations from the General Translation CDN, and when translating your app using our API, translations will be automatically saved to our CDN.

In React, we especially recommend using the CDN option. Using a CDN will minimize the size of your app bundle.

Overview

This guide will show you how to store translations in your React app bundle, rather than using an external CDN, such as ours. This means that translations will live in your app bundle and avoids reliance on external infrastructure.

In this guide, we will walk you through:

The trade-offs of using local translations.

How to set up local translations for your React app.

Trade-offs

What are the benefits?

Faster load times: Local translations are served directly from your app, meaning that they will load faster than translations served from a CDN.
No reliance on external services: Your app's ability to load translations is not dependent on CDN uptime. With gt-react, if translations are not found for a given locale, the app will automatically fall back to the default language and display the original content.

What are the drawbacks?

Increased bundle size: Local translations will increase your app's bundle size as they will be served alongside your app. This means that your app may take longer to load on the client.
Content management: If you want to edit a translation (i.e., you do not like how your content has been phrased in a different language), you must redeploy your app with the new translation every time you make changes.

Setup

Prerequisites

Make sure that you have already setup your React app with GT. If not, please complete the Quick Start Guide or Project Setup first.

Steps

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

src/loadTranslations.ts

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

src/loadTranslations.js

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

Pass loadTranslations as a prop to the <GTProvider> component.

src/App.tsx

import { GTProvider } from 'gt-react';
import loadTranslations from './loadTranslations'; 

export default function App() {
  return (
    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
      <YourApp />
    </GTProvider>
  );
}

Run the following command, and when asked if you want to save translations on the GT CDN, select the "No" option.

npx gtx-cli configure

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

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

npx gtx-cli translate

The loadTranslations function will then be used to load these translations into your app.

Depending on the specific framework you are using, translation JSONs may not be automatically included in the final bundle. Please refer to the documentation for your specific framework to ensure that the JSONs are included.

That's it! Your app will now only load translations from your local files.

Further customization

You can further customize the loadTranslations function to load translations from other sources, such as your database or your own CDN. See the loadTranslations() docs for more information.

Notes

Local translations are an alternative to fetching translations from a CDN.
There are benefits and drawbacks to using local translations, which are discussed in the Trade-offs section.

Next steps

See loadTranslations() for more information on writing a custom translation loader.

Local Translations

On this page