# 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

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

## Step 2: Configure Gasket

Add the intl plugin to your `gasket.js`:

```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:**
```json
{
  "welcome": "Welcome to our app!",
  "hello": "Hello, {name}!",
  "navigation": {
    "home": "Home",
    "about": "About"
  }
}
```

**locales/es-ES.json:**
```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):**
```jsx
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

```jsx
// 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

```bash
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

- **Dynamic Loading**: Learn about [dynamic locale files] for better performance
- **Server-Side Rendering**: Configure [static locale file paths] for SSR
- **Advanced Components**: Use [withLocaleFileRequired] for component-specific translations
- **Custom Routing**: This example uses [Next.js i18n routing], however a user's locale can be
  determined with other approaches, such as with [withLocaleInitialProps] from `@gasket/nextjs`.

## 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

- [@gasket/plugin-intl] - Full configuration options
- [@gasket/react-intl] - React components and hooks
- [@gasket/intl] - Core intl manager usage

<!-- LINKS -->
[dynamic locale files]: /packages/gasket-plugin-intl/README.md#dynamic-locale-files
[static locale file paths]: /packages/gasket-plugin-intl/README.md#options
[withLocaleFileRequired]: /packages/gasket-react-intl/README.md#withlocalefilerequired
[withLocaleInitialProps]: /packages/gasket-nextjs/README.md#withlocaleinitialprops
[Next.js i18n routing]: /packages/gasket-plugin-intl/README.md#nextjs-routing
[@gasket/plugin-intl]: /packages/gasket-plugin-intl/README.md
[@gasket/react-intl]: /packages/gasket-react-intl/README.md
[@gasket/intl]: /packages/gasket-intl/README.md