i18n-boost 0.1.0

package/README.md

@@ -0,0 +1,838 @@
+# i18n-boost
+
+Automate i18n in TypeScript and JavaScript projects. Mark strings with `tt()`, run one command, and get translated locale JSON files — no manual key management, no copy-paste, no drift.
+
+**Works with:** i18next · next-intl · Express · Fastify · NestJS · React · Next.js · Vue · any Node.js framework
+
+```bash
+npm install --save-dev i18n-boost
+```
+
+---
+
+## How it works
+
+1. **Mark** strings in your source code with `tt(key, defaultText)`
+2. **Run** `npx i18n-boost generate --translate`
+3. **Get** locale JSON files written to your output directory
+
+```typescript
+// Before
+const message = tt('auth.welcome', 'Welcome back, {{name}}!');
+
+// After generate (src/locales/en-US.json)
+{ "auth.welcome": "Welcome back, {{name}}!" }
+
+// After generate (src/locales/es-ES.json)
+{ "auth.welcome": "¡Bienvenido de nuevo, {{name}}!" }
+```
+
+i18n-boost is a **build-time tool only** — it never runs in production. Declare it as `devDependency`.
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Backend setup](#backend-setup)
+  - [Express](#express)
+  - [Fastify](#fastify)
+  - [NestJS](#nestjs)
+- [Frontend setup](#frontend-setup)
+  - [React + i18next (via backend)](#react--i18next--via-backend)
+  - [React + i18next (direct, CI/CD)](#react--i18next--direct-cicd)
+  - [Next.js + next-intl (SSR)](#nextjs--next-intl-ssr)
+  - [Next.js + next-intl (via backend)](#nextjs--next-intl-via-backend)
+- [CI/CD](#cicd)
+- [The `tt()` function](#the-tt-function)
+- [Configuration reference](#configuration-reference)
+- [Translation providers](#translation-providers)
+- [Supported locales](#supported-locales)
+- [CLI reference](#cli-reference)
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install --save-dev i18n-boost
+
+# pnpm
+pnpm add -D i18n-boost
+
+# yarn
+yarn add -D i18n-boost
+
+# bun
+bun add -d i18n-boost
+```
+
+After install, the setup wizard runs automatically. You can also run it manually:
+
+```bash
+npx i18n-boost init
+```
+
+---
+
+## Backend setup
+
+In a backend project, i18n-boost extracts `tt()` keys from your source code and writes a source locale file (`en-US.json`). It also exposes a `/sync` endpoint that your frontend can call to get translations.
+
+### Express
+
+**1. Install and configure**
+
+```bash
+npx i18n-boost init
+# Choose: Back-End
+# Choose your translation provider
+```
+
+This creates `.i18nrc.json`:
+
+```json
+{
+  "type": "backend",
+  "sourceLocale": "en-US",
+  "outputDir": "src/locales",
+  "provider": { "name": "deepl" }
+}
+```
+
+**2. Mark your strings**
+
+```typescript
+import { tt } from 'i18n-boost/tt';
+
+export function notFoundError() {
+  return tt('errors.notFound', 'Resource not found');
+}
+
+export function welcomeMessage(name: string) {
+  return tt('auth.welcome', 'Welcome back, {{name}}!').replace('{{name}}', name);
+}
+```
+
+**3. Mount the sync endpoint**
+
+```typescript
+import express from 'express';
+import { createI18nRouter } from 'i18n-boost/server';
+import { createProvider } from 'i18n-boost';
+
+const app = express();
+
+// Only mount in development — throws in production/staging automatically
+app.use(
+  '/api/i18n',
+  createI18nRouter({
+    provider: createProvider({ name: 'deepl' }),
+    secret: process.env.I18N_SECRET,
+    localesDir: './src/locales',
+    sourceLocale: 'en-US',
+  }),
+);
+```
+
+> The router throws at startup if `NODE_ENV` is `production` or `staging`. It is safe to leave in your codebase — it will never run in production.
+
+**4. Generate locale files**
+
+```bash
+# Extract keys only (no translation)
+npx i18n-boost generate
+
+# Extract and translate
+I18NBOOST_KEY=your-key npx i18n-boost generate --translate
+```
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "i18gen": "i18n-boost generate --translate"
+  }
+}
+```
+
+---
+
+### Fastify
+
+```typescript
+import Fastify from 'fastify';
+import { createI18nPlugin } from 'i18n-boost/server';
+import { createProvider } from 'i18n-boost';
+
+const fastify = Fastify();
+
+await fastify.register(
+  createI18nPlugin({
+    provider: createProvider({ name: 'deepl' }),
+    secret: process.env.I18N_SECRET,
+    localesDir: './src/locales',
+    sourceLocale: 'en-US',
+  }),
+  { prefix: '/api/i18n' },
+);
+```
+
+---
+
+### NestJS
+
+NestJS does not have a built-in adapter — use `handleSync` directly:
+
+```typescript
+import { Controller, Post, Body, Headers, HttpException } from '@nestjs/common';
+import { handleSync, I18nHandlerError } from 'i18n-boost/server';
+import { createProvider } from 'i18n-boost';
+
+@Controller('api/i18n')
+export class I18nController {
+  private provider = createProvider({ name: 'deepl' });
+
+  @Post('sync')
+  async sync(
+    @Body() body: unknown,
+    @Headers('x-i18n-secret') secret?: string,
+  ) {
+    try {
+      return await handleSync(body, {
+        provider: this.provider,
+        secret: process.env.I18N_SECRET,
+        localesDir: './src/locales',
+        sourceLocale: 'en-US',
+        requestSecret: secret,
+      });
+    } catch (err) {
+      if (err instanceof I18nHandlerError) {
+        throw new HttpException(err.message, err.statusCode);
+      }
+      throw err;
+    }
+  }
+}
+```
+
+Set the env var for your translation provider:
+
+```bash
+# .env (development only)
+I18NBOOST_KEY=your-deepl-key
+I18N_SECRET=a-random-secret-string
+```
+
+---
+
+## Frontend setup
+
+In a frontend project, i18n-boost extracts `tt()` keys and either calls your backend's `/sync` endpoint for translations, or calls a translation provider directly (for SSR or CI/CD builds).
+
+### React + i18next — via backend
+
+Best for: React SPA where your backend handles translation. API keys never leave the server.
+
+**1. Configure**
+
+```bash
+npx i18n-boost init
+# Choose: Front-End
+# Preset: i18next
+# Strategy: Via backend
+# Backend URL: http://localhost:3001/api/i18n/sync
+```
+
+`.i18nrc.json`:
+
+```json
+{
+  "type": "frontend",
+  "preset": "i18next",
+  "sourceLocale": "en-US",
+  "targetLocales": ["es-ES", "pt-BR", "fr-FR"],
+  "outputDir": "src/locales",
+  "provider": {
+    "name": "backend",
+    "url": "http://localhost:3001/api/i18n/sync",
+    "secret": "a-random-secret-string"
+  }
+}
+```
+
+**2. Mark your strings**
+
+```typescript
+import { tt } from 'i18n-boost/tt';
+
+// In components (before transform)
+export function SubmitButton() {
+  return <button>{tt('ui.submit', 'Submit')}</button>;
+}
+
+// With variables
+const label = tt('greeting', 'Hello, {{name}}!');
+```
+
+**3. Generate**
+
+```bash
+npx i18n-boost generate --translate
+```
+
+This calls your backend's `/sync` endpoint and writes:
+
+```
+src/locales/
+  en-US.json
+  es-ES.json
+  pt-BR.json
+  fr-FR.json
+  .i18n-meta.json
+```
+
+**4. Wire up i18next** (standard setup)
+
+```typescript
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import en from './locales/en-US.json';
+import es from './locales/es-ES.json';
+
+i18n.use(initReactI18next).init({
+  resources: {
+    'en-US': { translation: en },
+    'es-ES': { translation: es },
+  },
+  lng: 'en-US',
+  fallbackLng: 'en-US',
+});
+```
+
+**Compatible i18next packages:**
+- `i18next` ≥ 23.0.0
+- `react-i18next` ≥ 14.0.0
+- `i18next-browser-languagedetector` ≥ 8.0.0
+- `i18next-http-backend` ≥ 2.0.0
+- `i18next-fs-backend` ≥ 2.0.0
+
+---
+
+### React + i18next — direct (CI/CD)
+
+Best for: React apps built in CI/CD pipelines where you can set env vars. No backend needed.
+
+**1. Configure**
+
+```bash
+npx i18n-boost init
+# Choose: Front-End
+# Preset: i18next
+# Strategy: Direct
+# Provider: DeepL (or any)
+```
+
+`.i18nrc.json`:
+
+```json
+{
+  "type": "frontend",
+  "preset": "i18next",
+  "sourceLocale": "en-US",
+  "targetLocales": ["es-ES", "pt-BR", "de-DE"],
+  "outputDir": "src/locales",
+  "provider": { "name": "deepl" }
+}
+```
+
+**2. Generate in CI/CD**
+
+```bash
+npx i18n-boost generate --translate
+npm run build
+```
+
+The locale files are generated before your bundler runs — no `tt()` in the production bundle.
+
+**With `--transform`** (recommended): rewrites `tt()` calls to `t()` before bundling:
+
+```bash
+npx i18n-boost generate --translate --transform
+npm run build
+```
+
+After transform, `tt()` is gone from your source code and `i18n-boost` has zero footprint in production.
+
+---
+
+### Next.js + next-intl (SSR)
+
+Best for: Next.js App Router with server-side rendering. Set env vars in `.env.local` — they stay server-side.
+
+**1. Configure**
+
+```bash
+npx i18n-boost init
+# Choose: Front-End
+# Preset: next-intl
+# Strategy: Direct
+# Provider: Anthropic (or any)
+```
+
+`.i18nrc.json`:
+
+```json
+{
+  "type": "frontend",
+  "preset": "next-intl",
+  "sourceLocale": "en-US",
+  "targetLocales": ["es-ES", "pt-BR", "de-DE", "fr-FR"],
+  "outputDir": "src/locales",
+  "provider": {
+    "name": "anthropic",
+    "model": "claude-haiku-4-5-20251001"
+  }
+}
+```
+
+**2. Set env var** (server-side only, safe)
+
+```bash
+# .env.local — never exposed to the browser
+I18NBOOST_KEY=<your-api-key>
+```
+
+**3. Mark strings in server components**
+
+```typescript
+import { tt } from 'i18n-boost/tt';
+import { getTranslations } from 'next-intl/server';
+
+export default async function HomePage() {
+  const t = await getTranslations();
+  return <h1>{t(tt('home.title', 'Welcome'))}</h1>;
+}
+```
+
+**4. Generate** (run before `next build` or during dev)
+
+```bash
+npx i18n-boost generate --translate --transform
+```
+
+**5. Wire up next-intl** (standard setup)
+
+```typescript
+// get-request-config.ts
+import { getRequestConfig } from 'next-intl/server';
+
+export default getRequestConfig(async ({ locale }) => ({
+  messages: (await import(`./locales/${locale}.json`)).default,
+}));
+```
+
+```json
+// next.config.ts
+import createNextIntlPlugin from 'next-intl/plugin';
+const withNextIntl = createNextIntlPlugin();
+export default withNextIntl({});
+```
+
+**Compatible next-intl versions:** ≥ 3.0.0
+
+---
+
+### Next.js + next-intl — via backend
+
+Best for: monorepos where Next.js and the backend are separate apps.
+
+`.i18nrc.json` on the frontend:
+
+```json
+{
+  "type": "frontend",
+  "preset": "next-intl",
+  "sourceLocale": "en-US",
+  "targetLocales": ["es-ES", "de-DE"],
+  "outputDir": "src/locales",
+  "provider": {
+    "name": "backend",
+    "url": "http://localhost:3001/api/i18n/sync",
+    "secret": "a-random-secret-string"
+  }
+}
+```
+
+Run on the frontend:
+
+```bash
+npx i18n-boost generate --translate --transform
+```
+
+The backend handles the API keys. The frontend never sees them.
+
+---
+
+## CI/CD
+
+### GitHub Actions
+
+```yaml
+name: Build
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate translations
+        run: npx i18n-boost generate --translate --transform
+        env:
+          I18NBOOST_KEY: ${{ secrets.I18NBOOST_KEY }}
+
+      - name: Build
+        run: npm run build
+```
+
+### GitLab CI
+
+```yaml
+build:
+  script:
+    - npm ci
+    - npx i18n-boost generate --translate --transform
+    - npm run build
+  variables:
+    I18NBOOST_KEY: $I18NBOOST_KEY  # set in GitLab CI/CD settings
+```
+
+### Tip: cache locale files
+
+If translation keys rarely change, cache `src/locales/` and only regenerate when source files change:
+
+```yaml
+- name: Cache locales
+  uses: actions/cache@v4
+  with:
+    path: src/locales
+    key: locales-${{ hashFiles('src/**/*.ts', 'src/**/*.tsx') }}
+```
+
+---
+
+## The `tt()` function
+
+`tt()` is a zero-dependency marker function (~200 bytes minified). It returns the `defaultText` at runtime and is picked up by the scanner at build time.
+
+```typescript
+import { tt } from 'i18n-boost/tt';
+
+// Signature
+tt(key: string, defaultText: string): string
+
+// Examples
+tt('ui.submit', 'Submit')
+tt('errors.notFound', 'Resource not found')
+tt('greeting', 'Hello, {{name}}!')        // i18next interpolation
+tt('greeting', 'Hello, {name}!')          // next-intl interpolation
+tt('count', '{count, plural, one {# item} other {# items}}')  // ICU plurals
+```
+
+**Rules:**
+- Both arguments must be **string literals** — no variables, no template literals
+- Keys use dot notation: `'section.subsection.key'`
+- The `defaultText` is your source language (usually English)
+- `tt()` in test files is ignored by default (`**/*.test.*` is excluded)
+
+**With `--transform`**, after running `generate --transform`, all `tt()` calls are rewritten to your i18n library's function:
+
+```typescript
+// Before transform
+const label = tt('ui.submit', 'Submit');
+
+// After transform (i18next preset)
+const label = t('ui.submit');
+
+// After transform (next-intl preset, server component)
+const label = t('ui.submit');
+```
+
+---
+
+## Configuration reference
+
+Create `.i18nrc.json` at your project root (or run `npx i18n-boost init`):
+
+```json
+{
+  "type": "frontend",
+  "sourceLocale": "en-US",
+  "targetLocales": ["es-ES", "pt-BR", "de-DE", "fr-FR"],
+  "include": ["src/**/*.{ts,tsx}"],
+  "exclude": ["**/*.test.*", "**/*.spec.*"],
+  "outputDir": "src/locales",
+  "preset": "i18next",
+  "provider": {
+    "name": "deepl"
+  },
+  "transform": {
+    "enabled": false,
+    "importSource": "i18next",
+    "functionName": "t"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"backend"` \| `"frontend"` | Project type. Backend only writes source locale. Frontend writes all locales. |
+| `sourceLocale` | `string` | BCP-47 code of the language you write in (e.g. `"en-US"`). |
+| `targetLocales` | `string[]` | Languages to translate into. Backend type ignores this. |
+| `include` | `string[]` | Glob patterns for files to scan. Default: `["src/**/*.{ts,tsx,js,jsx}"]`. |
+| `exclude` | `string[]` | Glob patterns to skip. Default includes test and spec files. |
+| `outputDir` | `string` | Where to write locale JSON files. |
+| `preset` | `"i18next"` \| `"next-intl"` | Sets interpolation syntax and file format for the transform step. |
+| `provider` | `object` | Translation provider config. See [Translation providers](#translation-providers). |
+| `transform.enabled` | `boolean` | Enable rewriting `tt()` to `t()` after generation. |
+| `transform.importSource` | `string` | Import source for the injected import. Default: `"i18next"`. |
+| `transform.functionName` | `string` | Function name to replace `tt()` with. Default: `"t"`. |
+
+### Alternative config locations
+
+```js
+// .i18nrc.js
+module.exports = {
+  type: 'frontend',
+  sourceLocale: 'en-US',
+  // ...
+};
+```
+
+```json
+// package.json
+{
+  "i18n-boost": {
+    "type": "frontend",
+    "sourceLocale": "en-US"
+  }
+}
+```
+
+---
+
+## Translation providers
+
+### DeepL
+
+Fast, high quality, free tier available (500K chars/month).
+
+```json
+{ "provider": { "name": "deepl" } }
+```
+
+```bash
+export I18NBOOST_KEY=<your-api-key>
+```
+
+Requires: `npm install --save-dev` (no extra packages — uses native `fetch`)
+
+---
+
+### OpenAI-compatible API
+
+Works with OpenAI, DeepSeek, Groq, Mistral, Ollama, and any OpenAI-compatible endpoint.
+
+```json
+{ "provider": { "name": "openai", "model": "gpt-4o-mini" } }
+```
+
+```bash
+export I18NBOOST_KEY=your-api-key
+```
+
+Requires: `npm install --save-dev openai`
+
+**Custom endpoints:**
+
+```json
+// DeepSeek
+{ "provider": { "name": "openai", "model": "deepseek-chat", "baseUrl": "https://api.deepseek.com" } }
+
+// Groq
+{ "provider": { "name": "openai", "model": "llama-3.1-8b-instant", "baseUrl": "https://api.groq.com/openai/v1" } }
+
+// Ollama (local, no key needed)
+{ "provider": { "name": "openai", "model": "llama3", "baseUrl": "http://localhost:11434/v1" } }
+```
+
+---
+
+### Anthropic
+
+Claude models — excellent at preserving interpolation markers and ICU syntax.
+
+```json
+{ "provider": { "name": "anthropic", "model": "claude-haiku-4-5-20251001" } }
+```
+
+```bash
+export I18NBOOST_KEY=<your-api-key>
+```
+
+Requires: `npm install --save-dev @anthropic-ai/sdk`
+
+---
+
+### LibreTranslate
+
+Open source, self-hosted. No API key required for local instances.
+
+```json
+{ "provider": { "name": "libre-translate", "apiUrl": "http://localhost:5000" } }
+```
+
+No env var required. Run locally with Docker:
+
+```bash
+docker run -ti --rm -p 5000:5000 libretranslate/libretranslate
+```
+
+---
+
+### Backend (frontend only)
+
+Frontend delegates translation to your own backend. API keys stay server-side.
+
+```json
+{
+  "provider": {
+    "name": "backend",
+    "url": "http://localhost:3001/api/i18n/sync",
+    "secret": "a-random-secret-string"
+  }
+}
+```
+
+No env var needed on the frontend. The backend holds the provider keys.
+
+---
+
+### None
+
+Extracts keys and writes source locale only. Useful when setting up or in environments without API keys.
+
+```json
+{ "provider": { "name": "none" } }
+```
+
+---
+
+## Supported locales
+
+30 BCP-47 codes supported:
+
+| Code | Language |
+|------|----------|
+| `en-US` | English (US) |
+| `en-GB` | English (UK) |
+| `es-ES` | Spanish (Spain) |
+| `es-419` | Spanish (Latin America) |
+| `pt-BR` | Portuguese (Brazil) |
+| `pt-PT` | Portuguese (Portugal) |
+| `fr-FR` | French |
+| `fr-CA` | French (Canada) |
+| `de-DE` | German |
+| `it-IT` | Italian |
+| `nl-NL` | Dutch |
+| `zh-CN` | Chinese (Simplified) |
+| `zh-TW` | Chinese (Traditional) |
+| `ja-JP` | Japanese |
+| `ko-KR` | Korean |
+| `ar-SA` | Arabic |
+| `hi-IN` | Hindi |
+| `ru-RU` | Russian |
+| `tr-TR` | Turkish |
+| `id-ID` | Indonesian |
+| `vi-VN` | Vietnamese |
+| `th-TH` | Thai |
+| `pl-PL` | Polish |
+| `sv-SE` | Swedish |
+| `da-DK` | Danish |
+| `nb-NO` | Norwegian |
+| `fi-FI` | Finnish |
+| `cs-CZ` | Czech |
+| `ro-RO` | Romanian |
+| `uk-UA` | Ukrainian |
+
+---
+
+## CLI reference
+
+```bash
+npx i18n-boost --help
+```
+
+### `npx i18n-boost init`
+
+Interactive wizard. Creates `.i18nrc.json` in the current directory.
+
+```bash
+npx i18n-boost init
+npx i18n-boost init --cwd /path/to/project
+```
+
+### `npx i18n-boost generate`
+
+Extract `tt()` keys from source files, write locale JSON files.
+
+```bash
+npx i18n-boost generate                   # extract only, no translation
+npx i18n-boost generate --translate        # extract + translate
+npx i18n-boost generate --translate --transform  # extract + translate + rewrite tt() calls
+npx i18n-boost generate --dry-run         # preview without writing files
+```
+
+| Flag | Description |
+|------|-------------|
+| `--translate` | Call the configured provider to translate new/changed strings |
+| `--no-translate` | Skip translation — only write source locale JSON (default) |
+| `--dry-run` | Preview what would change without writing any files |
+| `--transform` | Rewrite `tt()` calls to `t()` (or configured `functionName`) after generating |
+| `--cwd <dir>` | Working directory (default: `process.cwd()`) |
+
+### `npx i18n-boost scan`
+
+List all `tt()` keys found in source files. No files written.
+
+```bash
+npx i18n-boost scan
+```
+
+---
+
+## Environment variables
+
+| Variable | Used by | Notes |
+|----------|---------|-------|
+| `I18NBOOST_KEY` | `anthropic`, `openai`, `deepl`, `libre-translate` | API key for the configured translation provider |
+| `I18N_SECRET` | server endpoint | Shared secret between frontend and backend |
+
+API keys are **never stored** in `.i18nrc.json`. Always read from environment variables at generate time.
+
+---
+
+## License
+
+MIT