@translation-cms/sync 1.1.69 → 1.1.71

package/README.md

@@ -1,28 +1,17 @@
-# React TranslationProvider
+# @translation-cms/sync
 
-Wrap je app of componenten met de TranslationProvider om i18n context te
-leveren:
+Scan translation keys in your codebase, sync them to the Translations CMS, and
+pull translations back as local JSON files. Built for Next.js + i18next.
 
-```tsx
-import { TranslationProvider } from '@translation-cms/sync';
-
-export default function RootLayout({
-    children,
-}: {
-    children: React.ReactNode;
-}) {
-    return <TranslationProvider locale="nl">{children}</TranslationProvider>;
-}
-```
+## How it works
 
-De provider initialiseert i18n en zorgt dat de context beschikbaar is voor alle
-onderliggende componenten.
-
-# @translation-cms/sync
+```
+1. sync-translations sync   → scans your code, pushes new keys to CMS
+2. sync-translations pull   → fetches translations, writes public/locales/{locale}/{ns}.json
+3. i18next loads the files  → useTranslation('auth') works as normal
+```
 
-Automatically scan translation keys in your codebase and sync them to the
-Translations CMS. Features type-safe translation functions, server-side
-stale-while-revalidate caching, and a live in-context preview.
+---
 
 ## Installation
 
@@ -30,121 +19,69 @@ stale-while-revalidate caching, and a live in-context preview.
 pnpm add @translation-cms/sync
 ```
 
+---
+
 ## Configuration
 
-### Option A — `.env.local`
+### `.env.local`
 
 ```bash
-# CMS location
 NEXT_PUBLIC_CMS_URL=https://cms.example.com
-
-# Your project ID from the CMS dashboard
 NEXT_PUBLIC_CMS_PROJECT_ID=your-project-id
-
-# API key (project settings → environments → api_key)
-# Used for both CLI syncing and client-side translation fetching
 NEXT_PUBLIC_CMS_ANON_KEY=your-api-key
 ```
 
-### Option B — `.translationsrc.json`
+### `.translationsrc.json` (optional)
 
-Create a `translations.config.json` (or `.translationsrc.json`) in your project
-root. Values here are merged with env vars — CLI args take highest priority.
+Run `sync-translations init` to generate it interactively, or create it
+manually:
 
 ```json
 {
     "outputDir": "./public/locales",
     "pullTtlMs": 300000,
     "excludedDirs": ["e2e", "fixtures"],
-    "reservedCssNamespaces": ["after", "before"],
     "previewRoutes": {
-        "namespace:key": [
-            {
-                "route": "/[locale]/blog/[slug]",
-                "params": { "slug": "first-post" }
-            }
+        "blog:post.title": [
+            { "route": "/blog/[slug]", "params": { "slug": "first-post" } }
         ]
     }
 }
 ```
 
-Use `previewRoutes` to define default preview routes per translation key. Each
-entry maps a `namespace:key` to one or more routes. For dynamic routes, use an
-object with a `params` field so the CMS can construct the correct preview URL:
-
-```json
-"previewRoutes": {
-    "blog:meta.author": [
-        { "route": "/[locale]/blog/[slug]", "params": { "slug": "first-post" } }
-    ],
-    "common:button.back": [
-        { "route": "/[locale]/blog/[slug]", "params": { "slug": "first-post" } },
-        { "route": "/[locale]/products/[slug]", "params": { "slug": "product-a" } }
-    ]
-}
-```
-
-Plain strings are also accepted for static routes or when segment values are
-resolved via the project's global preview params:
-
-```json
-"previewRoutes": {
-    "home:hero.title": ["/"],
-    "about:intro": ["/about"]
-}
-```
-
-> `previewRoutes` in `.translationsrc.json` is a fallback for keys that lack
-> `@preview` annotations in source code. Per-key `@preview` annotations always
-> take priority.
-
-> Keep API keys in `.env.local`, not in the config file. Add
-> `.translationsrc.json` to `.gitignore` if it contains the `apiKey` field.
-
-Run `sync-translations init` to generate the file interactively.
-
-### Environment priority
-
-`CLI args` → `.env.local` → `apps/web/.env.local` → `.translationsrc.json`
+**Priority:** CLI args → `.env.local` → `.translationsrc.json`
 
 ---
 
-## CLI Usage
-
-### Subcommands
+## CLI
 
 ```bash
-# Full sync: scan keys + push to CMS + pull translations locally
-pnpm sync-translations
-
-# Same, explicit
-pnpm sync-translations sync
-
-# Preview what would change — no network calls
-pnpm sync-translations sync --dry-run
+# Scan keys + push to CMS + pull translations
+sync-translations
 
-# Write a JSON report of all discovered keys
-pnpm sync-translations sync --report ./scan-report.json
+# Only pull (respects TTL cache)
+sync-translations pull
+sync-translations pull --force            # ignore TTL
+sync-translations pull --output ./locales # custom output dir
+sync-translations pull --env staging      # pull staging environment
+sync-translations pull --ttl 600000       # custom TTL in ms
 
-# Only pull translations (respects TTL cache)
-pnpm sync-translations pull
+# Preview changes without touching the CMS
+sync-translations sync --dry-run
 
-# Pull with options
-pnpm sync-translations pull --force            # ignore TTL
-pnpm sync-translations pull --output ./locales # custom output dir
-pnpm sync-translations pull --env staging      # pull staging environment
-pnpm sync-translations pull --ttl 600000       # custom TTL in ms
+# Show diff vs last sync (no network)
+sync-translations status
 
-# Show diff vs last sync without touching the CMS
-pnpm sync-translations status
+# Watch + auto-sync on file save
+sync-translations watch
 
-# Watch for file changes and auto-sync on save
-pnpm sync-translations watch
-
-# Interactive setup — creates .translationsrc.json
-pnpm sync-translations init
+# Interactive setup
+sync-translations init
 ```
 
+**Output:** `public/locales/{locale}/{namespace}.json` — one file per locale per
+namespace, flat key/value pairs. Compatible with `i18next-http-backend`.
+
 ### Flags
 
 | Flag              | Applies to     | Description                           |
@@ -159,428 +96,77 @@ pnpm sync-translations init
 | `--api-key`       | all            | Override API key                      |
 | `--cms-url`       | all            | Override CMS URL                      |
 
-### Example output
-
-```
-Scanning project: /path/to/project
-Scanned 127 files.
-Found 45 key(s) across 3 namespace(s): common, post, nav
-Posting to https://cms.example.com/api/sync/abc123...
-Synced: 3 created, 1 routes updated, 41 existing
-
-[CMS] Fetching from: https://cms.example.com/api/translations/abc123
-[CMS] ✓ Refresh complete: wrote 4 JSON files, updated .last-pulled
-```
-
 ---
 
-## CMS Client
-
-Fetch translations with the same API as your app's own i18n library.
-
-```typescript
-import { getCMSClient } from '@translation-cms/sync';
-
-// Reads NEXT_PUBLIC_CMS_URL + NEXT_PUBLIC_CMS_PROJECT_ID from env
-const client = getCMSClient();
-
-// Or configure explicitly
-import { CMSClient } from '@translation-cms/sync';
-
-const client = new CMSClient({
-    cmsUrl: 'https://cms.example.com',
-    projectId: 'your-project-id',
-    anonKey: 'optional-api-key',
-    defaultLocale: 'nl',
-    fallbackLocale: 'en',
-});
-```
-
-### `getTranslation()` — Server Components & async contexts
-
-Mirrors `getTranslation(ns)` from your app's `@/lib/i18n/server`.
-
-```typescript
-// Single namespace — uses defaultLocale
-const { t, tDynamic } = await client.getTranslation('post');
-t('post:first_post.title'); // ✓ type-safe
-t('common:submit'); // ✗ Type error — wrong namespace
-
-// Explicit locale
-const { t } = await client.getTranslation('post', 'en');
-
-// Multiple namespaces
-const { t } = await client.getTranslation(['post', 'common'] as const);
-t('post:first_post.title'); // ✓
-t('common:submit'); // ✓
-t('nav:home'); // ✗ Type error
-
-// tDynamic: for keys from variables or data structures
-const post = { titleKey: 'post:title' };
-tDynamic(post.titleKey); // ✓ accepts any string
-t(post.titleKey); // ✗ Type error — not a literal
-
-// Interpolation and plurals — same as real t()
-t('common:greeting', { name: 'Rick' }); // "Hello Rick"
-t('common:items', { count: 3 }); // "3 items"
-```
-
-### `useTranslation()` — React Client Components
-
-Mirrors `useTranslation(ns)` from your app's `@/lib/i18n/client`. Import from
-the `/react` subpath to keep React out of the server bundle.
-
-```tsx
-'use client';
-import { useTranslation } from '@translation-cms/sync/react';
-
-export function MyComponent() {
-    const { t, tDynamic, isLoading } = useTranslation('about');
-
-    return <h1>{t('about:hero.title')}</h1>;
-}
-
-// Multiple namespaces
-const { t } = useTranslation(['about', 'common'] as const);
-t('about:hero.title'); // ✓
-t('common:submit'); // ✓
-```
-
-Translations load asynchronously. The `isLoading` flag is `true` until the first
-fetch completes — keys return their raw key string in the meantime.
-
-### `getAllNamespaces()` — all namespaces for a locale
-
-Useful in build scripts or getStaticProps to prefetch everything at once.
+## i18next integration
 
-```typescript
-const all = await client.getAllNamespaces('nl');
-// { common: { 'button.save': 'Opslaan' }, nav: { ... }, ... }
+The package ships a native i18next backend plugin as an alternative to
+`i18next-http-backend`. It reads `NEXT_PUBLIC_*` env vars automatically.
 
-// Uses defaultLocale when omitted
-const all = await client.getAllNamespaces();
-```
-
-### Auto-refresh caching (server-side)
+```ts
+// lib/i18n.ts
+import i18next from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import { CMSBackend } from '@translation-cms/sync';
 
-When `autoRefresh` is enabled the client uses a **stale-while-revalidate**
-strategy: if local files exist but are older than the TTL, they are returned
-immediately while a background refresh updates them for the next request. Only
-the very first request (no local files yet) blocks.
-
-```typescript
-const client = new CMSClient({
-    cmsUrl: 'https://cms.example.com',
-    projectId: 'abc123',
-    localDir: './public/locales', // required for auto-refresh
-    autoRefresh: true,
-    autoRefreshTtlMs: 5 * 60 * 1000, // 5 minutes (default)
-});
+i18next
+    .use(CMSBackend)
+    .use(initReactI18next)
+    .init({
+        lng: 'nl',
+        fallbackLng: 'en',
+        ns: ['common', 'auth'],
+        defaultNS: 'common',
+    });
 ```
 
-Only runs server-side (Node.js). Browser requests skip auto-refresh entirely.
+Or use `i18next-http-backend` directly — both work with the files `sync pull`
+writes:
 
-### `serverBaseUrl` — custom SSR base URL
+```ts
+import HttpBackend from 'i18next-http-backend';
 
-When building local file URLs server-side the client defaults to
-`http://localhost:${PORT}`. Override this if your dev server runs on a different
-host or port:
-
-```typescript
-const client = new CMSClient({
-    // ...
-    serverBaseUrl: 'http://localhost:3001',
+i18next.use(HttpBackend).init({
+    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
 });
 ```
 
----
-
-## Scanner Patterns
-
-The CLI scanner recognises four translation key patterns.
-
-### Pattern 1: CMS client style
-
-```typescript
-const { t } = await client.getTranslation('post');
-const { t } = useTranslation('post');
-t('post:key'); // ✓
-```
-
-### Pattern 2: react-i18next style
-
-```typescript
-const { t } = useTranslation('namespace');
-t('namespace:key'); // ✓ explicit namespace prefix required
-```
-
-### Pattern 3: `<Trans>` component
+Then in any component:
 
 ```tsx
-// Both JSX attribute formats are supported
-<Trans i18nKey="blog:post.title" />
-<Trans i18nKey={'blog:post.title'} />
-```
+import { useTranslation } from 'react-i18next';
 
-### Pattern 4: Standalone `namespace:key` string literals
-
-```typescript
-const posts = [
-    { titleKey: 'post:first_post.title' }, // ✓
-    { bodyKey: 'post:1.body' }, // ✓
-];
+const { t } = useTranslation('auth');
+t('signIn');
 ```
 
-**All keys must use `namespace:key` format.** Bare keys (`t('save')`) and
-dot-notation standalones (`"post.1.title"`) are rejected with a warning.
-
-### Pattern 5: Per-route preview parameters with `@preview`
-
-When a translation key appears on multiple routes or with dynamic parameters,
-use the `@preview` annotation to specify which route(s) and parameter values
-should be used in the live preview.
-
-```typescript
-// Single route with parameters
-// @preview /blog/[slug] { "slug": "first-post" }
-t('blog:post.1.title');
-
-// Multiple routes (same parameters applied to both)
-// @preview ["/blog/[slug]", "/posts/[slug]"] { "slug": "my-post" }
-t('blog:title');
-
-// Route without parameters
-// @preview /about
-t('common:section.title');
-
-// Multiple parameters
-// @preview /[locale]/category/[id]/item/[itemId] { "locale": "en", "id": "tech", "itemId": "42" }
-t('catalog:item.name');
-```
-
-**Annotation placement:** Place `@preview` on the line immediately before or on
-the same line as the translation call. Multiple annotations are allowed for the
-same key:
-
-```typescript
-// @preview /blog/[slug] { "slug": "post-1" }
-const title1 = t('blog:post.title');
-
-// @preview /blog/[slug] { "slug": "post-2" }
-const title2 = t('blog:post.title'); // Same key, different route params
-```
-
-**Parameter values:** Parameters must be valid JSON and match the dynamic
-segments in your route. They're used by the CMS preview to construct the correct
-URL and pass to your app.
-
-**Priority:** Route-specific parameters > global project parameters > fallback.
-Global parameters are configured in the CMS project settings (Preview URL
-section).
-
 ---
 
-## Using Preview Routes with Parameters
-
-### Why you need this
-
-When a translation key is used on **multiple pages with different URL
-patterns**, the preview system needs to know which preview URL to load. Without
-parameters, CMS editors cannot properly preview the content in context.
-
-### Example: Blog posts
-
-Imagine you have the same blog post translations used across multiple places:
-
-```typescript
-// src/app/blog/[slug]/page.tsx
-const { t } = useTranslation('blog');
-
-export default function BlogPost({ params: { slug } }) {
-    return (
-        <article>
-            {/* @preview /blog/[slug] { "slug": "my-first-post" } */}
-            <h1>{t('blog:post.title')}</h1>
-            {/* @preview /blog/[slug] { "slug": "my-first-post" } */}
-            <p>{t('blog:post.excerpt')}</p>
-        </article>
-    );
-}
-```
-
-### How annotations work
-
-The `@preview` annotation tells the sync CLI **which routes and parameters** to
-associate with a translation key. When synced to the CMS, editors can preview
-each key on the specified routes.
-
-### Syntax
-
-```
-// @preview <route> [{ <json-params> }]
-// @preview [<routes>] [{ <json-params> }]
-```
-
-**Single route:**
-
-```typescript
-// @preview /contact
-t('contact:form.submit');
-
-// @preview /blog/[slug] { "slug": "hello-world" }
-t('blog:post.title');
-```
-
-**Multiple routes (optional):**
-
-```typescript
-// @preview ["/blog/[slug]", "/news/[slug]"] { "slug": "my-post" }
-t('common:share.text');
-```
-
-**No parameters needed:**
-
-```typescript
-// @preview /about
-t('about:hero.title');
-```
-
-### Best practices
-
-1. **Place the annotation above or on the same line** as the call that uses the
-   key.
-
-    ✓ Good:
-
-    ```typescript
-    // @preview /blog/[slug] { "slug": "post-1" }
-    t('blog:title');
-    ```
-
-    ✗ Avoid:
-
-    ```typescript
-    t('blog:title');
-    // @preview /blog/[slug] { "slug": "post-1" }  // Too far away
-    ```
-
-2. **Use representative values** in parameters — these become the default
-   preview values editors see.
-
-    ```typescript
-    // Use actual example values that make sense for testing
-    // @preview /blog/[slug] { "slug": "integration-guide" }
-    t('blog:post.title');
-
-    // Avoid placeholder-like values
-    // ✗ @preview /blog/[slug] { "slug": "xyz" }
-    ```
-
-3. **One annotation per key usage** when the same key is used on different
-   routes with different parameters.
-
-    ```typescript
-    // src/components/blog-card.tsx
-    // @preview /blog/[slug] { "slug": "post-1" }
-    export function BlogCard({ post }) {
-        return <h3>{t('blog:post.title')}</h3>
-    }
-
-    // src/components/featured-post.tsx
-    // @preview /featured/[id] { "id": "top-story" }
-    export function FeaturedPost() {
-        return <h2>{t('blog:post.title')}</h2>
-    }
-    ```
-
-4. **Global project parameters** are a fallback — use `@preview` for exact
-   control. You can configure default parameters in the CMS project settings,
-   but route-specific `@preview` annotations override them.
-
-### Common patterns
-
-**Category + item pages:**
-
-```typescript
-// @preview /shop/[category]/[itemId] { "category": "electronics", "itemId": "laptop-pro" }
-t('shop:item.price');
-```
-
-**Locale in the route:**
-
-```typescript
-// @preview /[locale]/blog/[slug] { "locale": "en", "slug": "getting-started" }
-t('blog:meta.description');
-
-// Locale placeholders are auto-replaced
-// The system understands [locale], [lang], [language] as special identifiers
-```
-
-**No-parameter routes (CMS defaults to `/`):**
-
-```typescript
-// @preview /
-t('home:hero.headline');
-```
-
-### Syncing to the CMS
-
-After adding annotations, run sync:
+## Server Components (RSC)
 
-```bash
-pnpm sync-translations sync
-```
-
-The CLI will:
-
-1. Scan your code and extract routes + parameters from `@preview` annotations
-2. Show a summary of what changed:
-    ```
-    Found 12 key(s) across 2 namespace(s): blog, common
-    Synced: 2 created, 1 routes updated, 9 existing
-    ```
-3. Upload to the CMS, making routes available for preview
+```ts
+import { getTranslation, getTranslations } from '@translation-cms/sync';
 
-### Verifying in the CMS
+// Type-safe t() for a single namespace
+const { t } = await getTranslation('common', 'nl');
+t('common:nav.home');
 
-In the CMS editor:
-
-1. Select a translation key
-2. Open the **Preview** panel
-3. You'll see a dropdown of available routes (from your `@preview` annotations)
-4. Click a route to load a live preview iframe
-5. Edit the translation and see changes live
-
----
-
-### Configurable scan options
-
-Via `.translationsrc.json`:
-
-```json
-{
-    "excludedDirs": ["e2e", "test-fixtures"],
-    "sourceExtensions": [".ts", ".tsx", ".js", ".jsx", ".vue"],
-    "reservedCssNamespaces": ["after", "before", "placeholder"]
-}
+// Raw translations for passing as props
+const translations = await getTranslations(['common', 'auth'], 'nl');
 ```
 
 ---
 
 ## Preview Listener
 
-Enable live in-context preview of translations. When an editor selects a key in
-the CMS, the listener highlights the matching element in your app (loaded in an
-iframe). While in preview mode, **all navigation and interactions are blocked**
-— links, buttons, and forms are disabled so the editor can focus on editing
-content without accidentally navigating away.
-
-### Setup in Next.js
+Enable live in-context preview. When an editor selects a key in the CMS, the
+matching element in your app (loaded in an iframe) is highlighted. Navigation
+and interactions are blocked during preview.
 
 ```tsx
 'use client';
 import { useEffect } from 'react';
-import { initPreviewListener } from '@translation-cms/sync/preview';
+import { initPreviewListener } from '@translation-cms/sync';
 
 export function CMSPreview() {
     useEffect(() => {
@@ -594,91 +180,91 @@ export function CMSPreview() {
 
 Add `<CMSPreview />` to your root layout.
 
-### Precise highlighting with `data-cms-key`
+### `data-cms-key`
 
-By default the listener finds elements by matching text content. For more
-precise highlighting — especially useful with interpolated values or split
-siblings — add a `data-cms-key` attribute to the element that renders the
-translation:
+For precise element targeting — useful with interpolated values:
 
 ```tsx
-<h1 data-cms-key="blog:post.title">
-    {t('blog:post.title')}
-</h1>
-
-<p data-cms-key="common:welcome">
-    {t('common:welcome', { name })}
-</p>
+<h1 data-cms-key="blog:post.title">{t('blog:post.title')}</h1>
+<p data-cms-key="common:welcome">{t('common:welcome', { name })}</p>
 ```
 
-When the attribute is present, text-search heuristics are skipped entirely.
+### Locale switching
 
-### Custom styling
+```ts
+initPreviewListener({
+    onLocaleSwitch: locale => i18n.changeLanguage(locale),
+});
+```
+
+### Custom highlight styles
 
-```typescript
+```ts
 initPreviewListener({
     highlightStyles: {
         outline: '3px solid #3b82f6',
         outlineOffset: '4px',
-        borderRadius: '8px',
         backgroundColor: 'rgba(59, 130, 246, 0.1)',
     },
 });
 ```
 
-### Locale switching
+### Cleanup
 
-The CMS can request a locale change without a page reload. Wire it up with your
-i18n library:
+```ts
+import { cleanupPreviewListener } from '@translation-cms/sync';
+cleanupPreviewListener();
+```
 
-```typescript
-// react-i18next
-initPreviewListener({
-    onLocaleSwitch: locale => i18n.changeLanguage(locale),
-});
+---
 
-// Or set a global handler (useful when initPreviewListener is called elsewhere)
-window.__cmsSetLocale = locale => i18n.changeLanguage(locale);
-```
+## Scanner
 
-### How it works
+The CLI scans your source files for translation keys. Recognised patterns:
 
-1. Editor opens the preview panel in the CMS for a translation key
-2. CMS sends a `postMessage` to your app (opened in an iframe)
-3. The listener finds the element — via `data-cms-key` attribute first, falling
-   back to text-content search
-4. Element is highlighted and scrolled into view
-5. Edits in the CMS input are reflected live in the preview (no reload)
-6. A transparent overlay and capture-phase event listeners block all clicks,
-   link navigation, and form submits for the duration of the preview session
+```ts
+// react-i18next
+const { t } = useTranslation('blog');
+t('blog:post.title');
 
-The listener only activates when `hostname` is `localhost` / `127.0.0.1` or the
-URL contains `?preview=true`. Production is never affected.
+// <Trans> component
+<Trans i18nKey="blog:post.title" />
 
-### Cleanup
+// CMS client (server-side)
+const { t } = await client.getTranslation('blog');
+t('blog:post.title');
 
-```typescript
-import { cleanupPreviewListener } from '@translation-cms/sync/preview';
-cleanupPreviewListener(); // removes overlay, unblocks interactions, clears highlights
+// Standalone string literals
+const key = 'blog:post.title';
 ```
 
----
+All keys must use `namespace:key` format. Bare keys (`t('save')`) produce a
+warning.
 
-## Logging
+### `@preview` annotations
 
-All operations log with a `[CMS]` prefix:
+Associate a key with a specific route for CMS live preview:
 
-```
-[CMS] ✓ Translations fresh (age: 45s < TTL: 300s) — using local files
-[CMS] ⟳ Stale — serving cached, refreshing in background...
-[CMS] ✓ Refresh complete: wrote 4 JSON files, updated .last-pulled
+```ts
+// @preview /blog/[slug] { "slug": "first-post" }
+t('blog:post.title');
+
+// Multiple routes
+// @preview ["/blog/[slug]", "/news/[slug]"] { "slug": "my-post" }
+t('common:share.text');
 ```
 
-Scanner warnings:
+Place the annotation on the line immediately before the call. Parameters must be
+valid JSON matching the dynamic segments in the route.
 
-```
-[WARN] Bare key in src/page.tsx: t('save') — use t('namespace:save') instead
-[WARN] Standalone key in src/data.ts: "post.1.title" — use "namespace:key" format
+### Scan options (`.translationsrc.json`)
+
+```json
+{
+    "excludedDirs": ["e2e", "fixtures"],
+    "sourceExtensions": [".ts", ".tsx", ".js", ".jsx", ".vue"],
+    "reservedCssNamespaces": ["after", "before"]
+}
 ```
 
 ---