npm package: @i18now/nuxt
Description: Nuxt module for [i18now](https://i18now.com) — loads translations from the i18now CDN and automatically syncs new keys to your project during development.
Latest version: 0.0.1

# @i18now/nuxt

Nuxt module for [i18now](https://i18now.com) — loads translations from the i18now CDN and automatically syncs new keys to your project during development.

## Features

- Loads published translations from the i18now CDN at SSR time
- Reloads translations on locale switch (client-side)
- In development: detects missing translation keys and syncs them to i18now automatically
- Suppresses vue-i18n missing-key warnings in dev — missing keys are expected until published
- API key is only present in development builds — never shipped to production
- Zero bundle impact in production — dev-only code is tree-shaken at build time

## Installation

```bash
npm install @i18now/nuxt @nuxtjs/i18n
# or
pnpm add @i18now/nuxt @nuxtjs/i18n
```

## Setup

Add the module to `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n', '@i18now/nuxt'],

  i18now: {
    projectId: process.env.I18NOW_PROJECT_ID ?? '',
    apiKey: process.env.I18NOW_API_KEY ?? '',
  },

  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    bundle: {
      optimizeTranslationDirective: false, // buggy, deprecated in v10
    },
  },
})
```

## Configuration

| Option        | Type       | Default                    | Description                                                                 |
|---------------|------------|----------------------------|-----------------------------------------------------------------------------|
| `projectId`   | `string`   | —                          | **Required.** Your i18now project ID.                                       |
| `apiKey`      | `string`   | —                          | **Required.** Your i18now API key. Only used in dev builds.                 |
| `host`        | `string`   | `https://i18now.com`       | i18now server URL. Set to `http://localhost:3220` for local development.    |
| `cdnUrl`      | `string`   | `https://cdn.i18now.com`   | CDN base URL where published translations are served.                       |
| `environment` | `string`   | `'dev'`                    | Which published environment to load translations from (`dev`, `stage`, `prod`). |
| `syncIn`      | `string[]` | `['development']`          | Node environments where missing-key sync is active. Keep as `['development']`. |
| `locale`      | `string`   | `'en'`                     | Fallback locale used before `@nuxtjs/i18n` initialises.                     |

### Environment variables

Store secrets in `.env`:

```env
I18NOW_PROJECT_ID=your-project-id
I18NOW_API_KEY=your-api-key
```

## How it works

### Production

The server plugin fetches the published translation JSON from the CDN (`{cdnUrl}/{projectId}/publish/{environment}/{locale}.json`) during SSR and injects it into vue-i18n. Translations are refreshed on locale switch.

### Development

The client plugin intercepts every `$t()` and `useI18now().t()` call. When a key is missing from the CDN snapshot it batches that key (with its default value) and POSTs it directly to the i18now sync endpoint.

```
Browser $t('key', 'Default text')
  → client plugin detects missing key
  → POST i18now /api/v1/projects/:id/sync  { apiKey, keys }
  → i18now creates the key with source value
```

The `useI18now` composable is auto-imported by the module. Use it in place of `useI18n` from vue-i18n — it adds sync detection on top of the standard `t()` function.

Vue-i18n's missing-key and fallback warnings are suppressed automatically in dev. Keys are expected to be absent until they are published from the i18now dashboard, at which point they load from CDN and no longer trigger warnings.

## Security

- `apiKey` is only included in `runtimeConfig.public` during **development** builds (`nuxt.options.dev`). In production, the API key is never serialised into the client bundle or `__NUXT__` payload.
- The `syncIn` option defaults to `['development']`. **Never add `'production'` or `'staging'`** — doing so would expose your API key to end users and flood your project with traffic.
- The client sync plugin is only registered in dev mode — it is completely absent from production builds.

## Local development against a local i18now server

```ts
// nuxt.config.ts
i18now: {
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  host: 'http://localhost:3220',
  environment: 'dev',
},
```

## Playground

A minimal playground is included in `playground/`. It runs on **port 3227**.

```bash
pnpm dev:playground
```

### Framework playground ports

All SDK playgrounds use fixed ports so they can run simultaneously alongside the i18now server (port 3220):

| Package | Port |
|---|---|
| `@i18now/react` | 3224 |
| `@i18now/vue` | 3225 |
| `@i18now/next` | 3226 |
| `@i18now/nuxt` | 3227 |

## Building locally

```bash
pnpm build
```

To use the built package in another local project, add a `file:` reference:

```json
{
  "dependencies": {
    "@i18now/nuxt": "file:../path/to/i18now/packages/nuxt"
  }
}
```