Skip to main content

Gasket Intl Quick Start Guide

Get up and running with internationalization in your Gasket app in minutes. These packages can be used for a variety of apps, including APIs, however this document will focus on use with React components in a Next.js App.

Prerequisites​

  • A Gasket app created with create-gasket-app
  • Node.js 20 or higher

Step 1: Install Packages​

npm install @gasket/plugin-intl @gasket/intl @gasket/react-intl

Step 2: Configure Gasket​

Add the intl plugin to your gasket.js:

// gasket.js
import { makeGasket } from '@gasket/core';
import pluginIntl from '@gasket/plugin-intl';

export default makeGasket({
  plugins: [
    pluginIntl
    // ... your other plugins
  ],
  intl: {
    locales: ['en-US', 'es-ES', 'fr-FR'],
    defaultLocale: 'en-US'
  }
});

Step 3: Create Locale Files​

Create your locale files in the locales/ directory:

locales/
├── en-US.json
├── es-ES.json
└── fr-FR.json

locales/en-US.json:

{
  "welcome": "Welcome to our app!",
  "hello": "Hello, {name}!",
  "navigation": {
    "home": "Home",
    "about": "About"
  }
}

locales/es-ES.json:

{
  "welcome": "¡Bienvenido a nuestra aplicación!",
  "hello": "¡Hola, {name}!",
  "navigation": {
    "home": "Inicio", 
    "about": "Acerca de"
  }
}

Step 4: Set Up Your App Component​

pages/_app.js (Next.js):

import { useRouter } from 'next/router';
import { IntlProvider } from 'react-intl';
import { withMessagesProvider } from '@gasket/react-intl';
import intlManager from '../intl.js'; // Generated by the plugin

const IntlMessagesProvider = withMessagesProvider(intlManager)(IntlProvider);

export default function App({ Component, pageProps }) {
  const router = useRouter();
  
  return (
    <IntlMessagesProvider locale={router.locale}>
      <Component {...pageProps} />
    </IntlMessagesProvider>
  );
}

Step 5: Use Translations in Components​

// pages/index.js
import { FormattedMessage } from 'react-intl';

export default function Home() {
  return (
    <div>
      <h1>
        <FormattedMessage id="welcome" />
      </h1>
      <p>
        <FormattedMessage 
          id="hello" 
          values={{ name: 'World' }} 
        />
      </p>
    </div>
  );
}

Step 6: Build and Run​

npm run build
npm run start

Your app is now internationalized! Users will see content in their browser's preferred language (if supported), or the default locale.

Next Steps​

Common Issues​

Build fails with "intl.js not found"​

Run npm run build first. The intl.js file is generated during the build process.

Translations not loading​

Ensure your locale files are in locales/ and match the exact locale codes in your configuration.

Learn More​