npm package: @fastlocalize/nextjs
Description: FastLocalize Next.js plugin for seamless i18n integration
Author: FastLocalize
Latest version: 0.1.0-alpha.2

# @fastlocalize/nextjs

FastLocalize Next.js plugin for seamless i18n integration with automatic translation management.

## Features

- Zero-config setup with Next.js 13+ App Router support
- Automatic translation key collection in development
- TypeScript-first with complete type safety
- Built-in locale routing and detection
- Performance optimized with minimal overhead

## Installation

```bash
npm install @fastlocalize/nextjs next-intl
```

## Quick Start

### 1. Environment Variables

```env
NEXT_PUBLIC_FASTLOCALIZE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FASTLOCALIZE_TOKEN=your_token
```

### 2. Configuration

Create `i18n/config.ts`:
```typescript
import { LocaleConfig } from "@fastlocalize/nextjs";

export const localeConfig: LocaleConfig = {
  locales: ["en", "zh-CN", "ja"],
  defaultLocale: "en",
};
```

### 3. Setup Files

**`i18n/request.ts`**:
```typescript
import { createFastLocalizeRequestConfig } from "@fastlocalize/nextjs";
import { localeConfig } from "./config";

export default createFastLocalizeRequestConfig(
  localeConfig,
  async (locale: string) => {
    return (await import(`./locales/${locale}.json`)).default;
  }
);
```

**`middleware.ts`**:
```typescript
import { createFastLocalizeMiddleware, defaultMiddlewareConfig } from "@fastlocalize/nextjs";
import { localeConfig } from "./i18n/config";

export default createFastLocalizeMiddleware(localeConfig);
export const config = defaultMiddlewareConfig;
```

**`next.config.js`**:
```javascript
const { withFastLocalize } = require("@fastlocalize/nextjs");
module.exports = withFastLocalize("./i18n/request")(nextConfig);
```

### 4. App Layout

```typescript
import { FastLocalizeProvider, getFastLocalizeConfig } from "@fastlocalize/nextjs";
import { getMessages, setRequestLocale } from "next-intl/server";

export default async function RootLayout({ children, params: { locale } }) {
  setRequestLocale(locale);
  const messages = await getMessages();
  const config = getFastLocalizeConfig();

  return (
    <html lang={locale}>
      <body>
        <FastLocalizeProvider locale={locale} messages={messages} config={config}>
          {children}
        </FastLocalizeProvider>
      </body>
    </html>
  );
}
```

### 5. Usage

```typescript
import { useTranslations } from "@fastlocalize/nextjs";

export default function HomePage() {
  const t = useTranslations("HomePage");
  return <h1>{t("title")}</h1>;
}
```

## API Reference

### Main Exports

```typescript
// Components
export { FastLocalizeProvider } from "@fastlocalize/nextjs";

// Configuration
export { createFastLocalizeRouting, createFastLocalizeMiddleware, createFastLocalizeRequestConfig } from "@fastlocalize/nextjs";

// Utilities  
export { getFastLocalizeConfig, withFastLocalize } from "@fastlocalize/nextjs";

// Hooks (re-exports from next-intl)
export { useTranslations, useLocale, useMessages } from "@fastlocalize/nextjs";

// Types
export type { LocaleConfig, FastLocalizeConfig } from "@fastlocalize/nextjs";
```

## Configuration Options

### Environment Variables
```env
NEXT_PUBLIC_FASTLOCALIZE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FASTLOCALIZE_TOKEN=your_token
NEXT_PUBLIC_FASTLOCALIZE_API_URL=https://api.fastlocalize.com  # optional
NEXT_PUBLIC_FASTLOCALIZE_LIVEBOX=latest                        # optional
NEXT_PUBLIC_FASTLOCALIZE_ENABLE_MISSING_KEY_SUBMISSION=true    # optional
```

### Custom Message Loading
```typescript
export default createFastLocalizeRequestConfig(
  localeConfig,
  async (locale: string) => {
    // Load from API or merge multiple sources
    const response = await fetch(`/api/translations/${locale}`);
    return await response.json();
  }
);
```

## Migration from next-intl

1. Replace `NextIntlClientProvider` with `FastLocalizeProvider`
2. Replace `createNavigation` with `createFastLocalizeRouting`  
3. Replace `createMiddleware` with `createFastLocalizeMiddleware`
4. Add FastLocalize environment variables

## License

MIT