npm package: @lightspeed/i18n-next-app
Description: React i18next Next.js app bindings
Latest version: 0.5.6

# `@lightspeed/i18n-next-app`

[![npm version](https://badge.fury.io/js/%40lightspeed%2Fi18n-next-app.svg)](https://badge.fury.io/js/%40lightspeed%2Fi18n-next-app)

## Introduction

Libraries for easily integrating `react-i18next` into your `Next.js` application. Supports serverside rendering of localized content, isomorphic lazy loading of translation files, and message event handling for changing languages (i.e.: in Retail context iframe).

## Quick Start

1. Install the dependency in your webapp.

```sh
yarn add @lightspeed/i18n-next-app
```

2. Create your translation files using Transifex. The i18n instance is configured to load translations from `static/locales/<language>.json`.

```json
{
  "the dog": "le chien",
  "the cat": "le chat"
}
```

3. Enhance your `_app.tsx` component with the `withLocalizeApp` HOC.

```tsx
import React from 'react';
import App, { Container } from 'next/app';
import { withLocalizeApp, LocaleMessageListener } from '@lightspeed/i18n-next-app';

class MyApp extends App {
  render() {
    const { Component, pageProps } = this.props;

    return (
      <Container>
        <Component {...pageProps} />
        {/* Optional; listens to message events from Retail for locale change */}
        <LocaleMessageListener />
      </Container>
    );
  }
}

export default withLocalizeApp({
  // Optional; set the i18n instance to debug mode; default: false
  debug: false,
  // Optional; resolve language on the client from browser; default: false
  clientLanguageDetection: false,
  // Optional; resolve language on the server from request; default: false
  serverLanguageDetection: false,
  // Optional; fallback language when not using language detection; default: 'en'
  fallbackLanguage: 'en',
  // Optional; path to translation files; default: 'static/locales'
  translationFilesPath: 'public/locales',
})(NextApp);
```

4. Consume translations with the `useTranslation` hook. Langauges that are not preloaded on the client are fetched lazily from the server.

```tsx
import React from 'react';
import { useTranslation } from '@lightspeed/i18n-next-app';

const MyPage = () => {
  const [t, i18n] = useTranslation();

  return (
    <div>
      <button onClick={() => i18n.changeLanguage('en')}>English</button>
      <button onClick={() => i18n.changeLanguage('fr')}>French</button>
      <div>{t('the dog')}</div>
      <div>{t('the cat')}</div>
    </div>
  );
};

// Must be defined to disable static file optimization in Next 9
MyPage.getInitialProps = () => ({});

export default MyPage;
```

5. (Optional) Enhance your `_document.tsx` component with the `withLocalizeDocument` HOC to set the document language on the `html` tag.

```tsx
import React from 'react';
import Document, { Head, Main, NextScript } from 'next/document';
import { withLocalizeDocument } from '@lightspeed/i18n-next-app';

type MyDocumentProps = {
  language: string; // from `withLocalizeDocument` HOC
};

class MyDocument extends Document<MyDocumentProps> {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx);
    return { ...initialProps };
  }

  render() {
    return (
      <html lang={this.props.language}>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </html>
    );
  }
}

export default withLocalizeDocument(MyDocument);
```