@translation-cms/sync 1.2.3 → 1.2.5

package/README.md

@@ -1,29 +1,51 @@
 # @translation-cms/sync
 
-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.
+Automatisch vertaalsleutels uit je codebase scannen, syncen met de Translations
+CMS, en vertalingen ophalen als lokale JSON-bestanden. Gebouwd voor Next.js +
+i18next.
 
-## How it works
+## Wat is dit?
+
+Een CLI-tool die je workflow vereenvoudigt:
+
+- 🔍 **Scant** je code voor translation keys (React-i18next patroon)
+- 📤 **Synct** nieuwe keys naar de Translations CMS
+- 📥 **Haalt** vertalingen op als JSON-bestanden
+- 🎯 **Preview** functie waarin editors live kunnen zien hoe hun tekst in je app
+  eruit ziet
 
 ```
-1. sync-translations sync   → scans your code, pushes new keys to CMS
-2. sync-translations pull   → fetches translations, writes src/lib/i18n/dictionaries/{locale}.json
-3. i18next loads the files  → static imports in client.ts, dynamic imports in server.ts
+Your Code → scan → CMS → pull → JSON files → i18next → Your App
 ```
 
 ---
 
-## Installation
+# Setup Handleiding — Van Nul Tot Functie
+
+## Stap 1: Vereisten
+
+Controleer wat je nodig hebt:
+
+- ✅ Next.js project (v14+)
+- ✅ pnpm (aanbevolen) of npm
+- ✅ Translations CMS account + project aangemaakt
+- ✅ CMS project credentials (URL, project ID, API key)
+
+## Stap 2: Installatie
 
 ```bash
 pnpm add @translation-cms/sync
 ```
 
----
+Plus de peer dependencies:
+
+```bash
+pnpm add i18next react-i18next i18next-resources-to-backend
+```
 
-## Configuration
+## Stap 3: CMS Credentials Instellen
 
-### `.env.local`
+Maak `.env.local` aan in je project root:
 
 ```bash
 NEXT_PUBLIC_CMS_URL=https://cms.example.com
@@ -31,168 +53,159 @@ NEXT_PUBLIC_CMS_PROJECT_ID=your-project-id
 NEXT_PUBLIC_CMS_ANON_KEY=your-api-key
 ```
 
-### `.translationsrc.json`
+Deze krijg je uit je CMS project settings.
 
-Run `sync-translations init` to generate it interactively, or create it
-manually:
+## Stap 4: Automatische Setup (Aanbevolen)
+
+Run de interactive setup wizard:
+
+```bash
+pnpm sync-translations init
+```
+
+Dit maakt automatisch aan:
+
+```
+src/lib/i18n/
+  ├── settings.ts           # i18next configuratie
+  ├── types.ts              # TypeScript types voor translations
+  ├── client.ts             # 'use client' hook + static imports
+  ├── server.ts             # Server component support
+  ├── provider.tsx          # Provider wrapper
+  └── dictionaries/
+      ├── en.json           # Engels (leeg, wordt gevuld door pull)
+      └── nl.json           # Nederlands (leeg, wordt gevuld door pull)
+```
+
+Ook `.translationsrc.json` wordt gegenereerd:
 
 ```json
 {
     "outputDir": "./src/lib/i18n/dictionaries",
     "pullTtlMs": 300000,
-    "excludedDirs": ["e2e", "fixtures"],
-    "routeParams": {
-        "/[locale]/blog/[slug]": { "slug": "first-post" },
-        "/[locale]/products/[slug]": { "slug": "product-a" }
-    }
+    "excludedDirs": ["e2e", "node_modules", "fixtures"],
+    "routeParams": {}
 }
 ```
 
-**Priority:** CLI args → `.env.local` → `.translationsrc.json`
-
----
+**Let op:** `routeParams` kan leeg blijven! De scanner genereert automatisch
+sensible defaults voor alle dynamic routes.
 
-## Quickstart
+## Stap 5: Eerste Sync — Keys Uploaden
 
-Run the interactive setup — scaffolds all i18n files automatically:
+Scan je code en upload gedetecteerde keys naar de CMS:
 
 ```bash
-sync-translations init
+pnpm sync-translations sync
 ```
 
-It creates `.translationsrc.json` and writes:
+Dit zal:
 
-```
-src/lib/i18n/
-  settings.ts
-  types.ts
-  client.ts          ← 'use client', static imports
-  server.ts          ← RSC, dynamic import()
-  provider.tsx       ← TranslationProvider
-  dictionaries/
-    en.json          ← populated by: sync-translations pull
-    nl.json
-```
+1. Je code scannen op translation keys (`t('namespace:key')` patroon)
+2. Route detecteren waar elke key gebruikt wordt
+3. Nieuwe keys naar CMS uploaden
+4. Rapport tonen (welke keys toegevoegd/gewijzigd)
 
-Then install peer deps and pull translations:
+Controleer in de CMS of je keys verschenen zijn ✅
 
-```bash
-pnpm add i18next react-i18next i18next-resources-to-backend
-sync-translations pull
-```
+## Stap 6: Vertalingen Ophalen
 
-Add to your `package.json` so translations are always fresh:
+Download vertalingen van de CMS en schrijf ze naar lokale JSON:
 
-```json
-"scripts": {
-    "dev": "sync-translations pull && next dev",
-    "build": "sync-translations pull && next build"
-}
+```bash
+pnpm sync-translations pull
 ```
 
----
+Dit vult `dictionaries/en.json` en `dictionaries/nl.json` met vertalingen.
 
-## CLI
+## Stap 7: Integratie in je Project
 
-```bash
-# Scan keys + push to CMS
-sync-translations sync
+### A. Root Layout Setup
 
-# Pull translations to local JSON files (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
+Voeg de provider toe aan je `src/app/layout.tsx`:
 
-# Preview changes without touching the CMS
-sync-translations sync --dry-run
+```tsx
+import { TranslationProvider } from '@/lib/i18n/provider';
 
-# Show diff vs last sync (no network)
-sync-translations status
+export default function RootLayout({
+    children,
+}: {
+    children: React.ReactNode;
+}) {
+    return (
+        <html>
+            <body>
+                <TranslationProvider>{children}</TranslationProvider>
+            </body>
+        </html>
+    );
+}
+```
 
-# Watch + auto-sync on file save
-sync-translations watch
+### B. Server Components (Aanbevolen)
 
-# Interactive setup
-sync-translations init
-```
+```tsx
+import { getTranslation } from '@/lib/i18n/server';
 
-**Output:** `dictionaries/{locale}.json` — one file per locale, namespaces as
-top-level keys:
+export default async function Page() {
+    const { t } = await getTranslation('common');
 
-```json
-{
-    "common": { "nav.home": "Home" },
-    "auth": { "signIn": "Sign in" }
+    return (
+        <div>
+            <h1>{t('common:app.title')}</h1>
+            <p>{t('common:app.description')}</p>
+        </div>
+    );
 }
 ```
 
-### Flags
-
-| Flag              | Applies to     | Description                           |
-| ----------------- | -------------- | ------------------------------------- |
-| `--dry-run`       | `sync`         | Print what would change, skip posting |
-| `--force`         | `sync`, `pull` | Skip cache / force re-sync            |
-| `--report <file>` | `sync`         | Write JSON report to file             |
-| `--output <dir>`  | `pull`         | Output directory for JSON files       |
-| `--env <name>`    | `pull`         | Pull from a specific environment      |
-| `--ttl <ms>`      | `pull`         | Override cache TTL                    |
-| `--project-id`    | all            | Override project ID                   |
-| `--api-key`       | all            | Override API key                      |
-| `--cms-url`       | all            | Override CMS URL                      |
+### C. Client Components
 
----
-
-## i18next integration
+```tsx
+'use client';
+import { useTranslation } from '@/lib/i18n/client';
 
-The scaffolded `client.ts` uses static imports so webpack bundles the
-translations at build time — no flash, no loading state:
+export function MyButton() {
+    const { t } = useTranslation('common');
 
-```ts
-// src/lib/i18n/client.ts ('use client')
-import en from './dictionaries/en.json';
-import nl from './dictionaries/nl.json';
+    return <button>{t('common:button.click')}</button>;
+}
+```
 
-const resources = { en, nl } as const;
+### D. Multiple Namespaces (Met Type-Checking)
 
-await i18nInstance.use(initReactI18next).init({
-    ...getOptions(locale),
-    resources,
-});
-```
+```tsx
+const { t } = useTranslation(['common', 'auth']);
 
-The scaffolded `server.ts` uses `i18next-resources-to-backend` with dynamic
-`import()` — no HTTP, reads directly from the filesystem:
+// ✅ Dit werkt
+t('common:nav.home');
+t('auth:login.email');
 
-```ts
-// src/lib/i18n/server.ts (RSC)
-.use(resourcesToBackend((lng, ns) =>
-    import(`./dictionaries/${lng}.json`).then(m => m.default[ns] ?? {})
-))
+// ❌ Dit geeft een type error
+t('payments:amount'); // namespace niet toegevoegd
 ```
 
-### Usage
+## Stap 8: Automatische Sync in je Workflow
 
-```tsx
-// Client component
-import { useTranslation } from '@/lib/i18n/client';
-const { t } = useTranslation('common');
-t('common:nav.home');
+Voeg dit toe aan `package.json`:
 
-// Server component
-import { getTranslation } from '@/lib/i18n/server';
-const { t } = await getTranslation('common');
-t('common:nav.home');
+```json
+{
+    "scripts": {
+        "dev": "sync-translations pull && next dev",
+        "build": "sync-translations pull && next build"
+    }
+}
 ```
 
----
+Nu pull je automatisch de latest vertalingen bij startup ⚡
+
+## Stap 9 (Optioneel): Preview Mode Instellen
 
-## Preview Listener
+Enable live in-context preview — editors kunnen live zien hoe hun tekst in je
+app eruit ziet.
 
-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.
+Voeg dit toe aan je root layout:
 
 ```tsx
 'use client';
@@ -202,198 +215,293 @@ import { initPreviewListener } from '@translation-cms/sync';
 export function CMSPreview() {
     useEffect(() => {
         if (process.env.NODE_ENV === 'development') {
-            initPreviewListener();
+            initPreviewListener({
+                onLocaleSwitch: locale => {
+                    // wijzig taal als CMS een ander locale selecteert
+                    window.location.href = `/${locale}`;
+                },
+            });
         }
     }, []);
     return null;
 }
 ```
 
-Add `<CMSPreview />` to your root layout.
+En voeg toe in layout:
 
-### `data-cms-key`
+```tsx
+<TranslationProvider>
+    <CMSPreview />
+    {children}
+</TranslationProvider>
+```
 
-For precise element targeting — useful with interpolated values:
+Voeg `data-cms-key` toe op elementen voor nauwkeurige highlighting:
 
 ```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="common:page.title">{t('common:page.title')}</h1>
 ```
 
-### Locale switching
+---
 
-```ts
-initPreviewListener({
-    onLocaleSwitch: locale => i18n.changeLanguage(locale),
-});
+# CLI Commands Reference
+
+## Basiscommands
+
+```bash
+# Scan code + upload naar CMS
+pnpm sync-translations sync
+
+# Download vertalingen naar lokale JSON
+pnpm sync-translations pull
+
+# Bekijk wat er zou veranderen (zonder upload)
+pnpm sync-translations sync --dry-run
+
+# Bekijk verschil met vorige sync
+pnpm sync-translations status
+
+# Watch mode — auto-sync bij bestand wijzigingen
+pnpm sync-translations watch
+
+# Interactieve setup
+pnpm sync-translations init
 ```
 
-### Custom highlight styles
+## Advanced Flags
 
-```ts
-initPreviewListener({
-    highlightStyles: {
-        outline: '3px solid #3b82f6',
-        outlineOffset: '4px',
-        backgroundColor: 'rgba(59, 130, 246, 0.1)',
-    },
-});
+| Flag              | Beschrijving                         |
+| ----------------- | ------------------------------------ |
+| `--dry-run`       | Toon wijzigingen, voer niet uit      |
+| `--force`         | Negeer cache, force hernieuwen       |
+| `--output <dir>`  | Custom output map voor JSON          |
+| `--env <name>`    | Pull uit staging/production omgeving |
+| `--ttl <ms>`      | Overschrijf cache TTL (ms)           |
+| `--project-id`    | Overschrijf project ID               |
+| `--api-key`       | Overschrijf API key                  |
+| `--cms-url`       | Overschrijf CMS URL                  |
+| `--report <file>` | Schrijf sync rapport naar JSON file  |
+
+## Voorbeelden
+
+```bash
+# Force refresh, negeer cache
+pnpm sync-translations pull --force
+
+# Custom output directory
+pnpm sync-translations pull --output ./locales
+
+# Pull uit staging environment
+pnpm sync-translations pull --env staging
+
+# Schrijf rapport van wijzigingen
+pnpm sync-translations sync --report ./sync-report.json
 ```
 
-### Cleanup
+---
+
+# Key Scanner — Hoe Werkt Het
+
+De tool herkent deze patronen in je code:
 
 ```ts
-import { cleanupPreviewListener } from '@translation-cms/sync';
-cleanupPreviewListener();
-```
+// ✅ React-i18next hook
+const { t } = useTranslation('blog');
+t('blog:post.title');
 
-### Triggering actions (dialogs, menus, etc.)
+// ✅ Trans component
+<Trans i18nKey="blog:post.title" />
 
-For translations inside dialogs or collapsed menus, register an action callback
-that opens the UI when the CMS sends a trigger:
+// ✅ String literal
+const key = 'blog:post.title';
+```
 
-```tsx
-'use client';
-import { useState, useEffect } from 'react';
-import {
-    initPreviewListener,
-    registerPreviewAction,
-} from '@translation-cms/sync';
+### Format: `namespace:key`
 
-export function NavMenu() {
-    const [open, setOpen] = useState(false);
+Alle keys moeten dit format volgen. Anders krijg je een warning:
 
-    useEffect(() => {
-        if (process.env.NODE_ENV === 'development') {
-            // Register so the CMS can open the menu during preview
-            registerPreviewAction('nav.menu', () => {
-                setOpen(true);
-            });
-        }
-    }, []);
+```ts
+// ✅ Goed
+t('common:button.save');
 
-    return (
-        <nav>
-            <button onClick={() => setOpen(!open)}>Menu</button>
-            {open && (
-                <div>
-                    <a href="/">
-                        <span data-cms-key="nav:home">{t('nav:home')}</span>
-                    </a>
-                    <a href="/about">
-                        <span data-cms-key="nav:about">{t('nav:about')}</span>
-                    </a>
-                </div>
-            )}
-        </nav>
-    );
-}
+// ❌ Fout — namespace mist
+t('save');
 ```
 
-#### Setting up action_id in the CMS
+### Dynamische Routes — Auto-Generated routeParams
 
-In the Translations CMS, each translation key can have an `action_id`:
+**Hoe het werkt:**
 
-1. Click the **Edit** button (pencil icon) on a translation key
-2. Fill in **Preview action** field with your action ID (e.g., `nav.menu`,
-   `modal.signup`)
-3. Click **Update**
+Bij elke `pnpm sync-translations sync`:
 
-When an editor clicks "Show in app" for that key, the CMS will:
+1. Scanner detecteert automatisch alle routes met dynamic parameters (bijv.
+   `/[locale]/blog/[slug]`)
+2. Voor elke `[param]` wordt automatisch een sensible default gegenereerd:
+    - `locale` / `lang` → `"en"`
+    - `id`, `postId`, `productId` → `"123"`
+    - `slug` → `"demo"`
+    - `username` → `"demo-user"`
+    - `email` → `"demo@example.com"`
+3. Dit wordt opgeslagen in `.cms-sync-cache-meta.json` (mag je negeren)
+4. De CMS gebruikt deze om werkende preview URLs te genereren
 
-1. Load your app in an iframe
-2. Auto-open the menu/dialog/modal by sending a `CMS_TRIGGER_ACTION` message
-3. Highlight the matching `data-cms-key` element
+**Je hoeft niks te doen!** — alles werkt out-of-the-box.
 
-**Action IDs** are namespaced identifiers you define — they should match action
-names registered during initialization. Common patterns:
+**Handmatig overschrijven (optioneel):**
 
-```
-nav.menu              → Opens main navigation menu
-nav.mobile-menu       → Opens mobile hamburger menu
-modal.signup          → Opens signup modal
-modal.login           → Opens login modal
-dropdown.language     → Opens language selector
-sidebar.filter        → Opens filter sidebar
-accordion.faq         → Opens FAQ accordion
-tabs.pricing          → Switches to pricing tab
+Als je andere test-waarden wil gebruiken, vul je `.translationsrc.json` in:
+
+```json
+{
+    "routeParams": {
+        "/[locale]/products/[id]": { "id": "prod-999" },
+        "/[locale]/blog/[slug]": { "slug": "my-custom-post" }
+    }
+}
 ```
 
-**Complete workflow example:**
+Dit overschrijft de auto-generated waarden. Alles wat je hier toevoegt krijgt
+prioriteit.
 
-1. **Client app registers action:**
+### Cache bestanden
 
-    ```ts
-    registerPreviewAction('nav.mobile-menu', () => setMobileMenuOpen(true));
-    ```
+Bij elke sync worden twee cache bestanden aangemaakt:
 
-2. **CMS Editor:**
-    - Selects key `common:nav.home`
-    - Clicks Edit
-    - Sets **Preview action** to `nav.mobile-menu`
-    - Clicks Update
+- `.cms-sync-cache.json` — Geüploade keys en hun routes (voor diff bij volgende
+  sync)
+- `.cms-sync-cache-meta.json` — Auto-generated route params (mag je .gitignore
+  toevoegen)
 
-3. **CMS Preview:**
-    - Editor clicks "Show in app"
-    - Mobile menu auto-opens
-    - `<span data-cms-key="common:nav.home">` element is highlighted in yellow
-    - Editor sees the translation in context
+### Scanner Opties
 
----
+Customize scan gedrag in `.translationsrc.json`:
 
-### How it works
+```json
+{
+    "excludedDirs": ["e2e", "node_modules", "fixtures"],
+    "sourceExtensions": [".ts", ".tsx", ".js", ".jsx"],
+    "reservedCssNamespaces": ["after", "before"]
+}
+```
 
 ---
 
-## Scanner
+# Advanced Features
 
-The CLI scans your source files for translation keys. Recognised patterns:
+## Preview Mode — Live Highlighting
 
-```ts
-// react-i18next
-const { t } = useTranslation('blog');
-t('blog:post.title');
+Editors kunnen in de CMS klikken op "Show in app" en je app opent in een iframe
+met live highlighting van het element.
 
-// <Trans> component
-<Trans i18nKey="blog:post.title" />
+### Setup
 
-// Standalone string literals
-const key = 'blog:post.title';
+```tsx
+'use client';
+import { initPreviewListener } from '@translation-cms/sync';
+
+useEffect(() => {
+    initPreviewListener({
+        highlightStyles: {
+            outline: '3px solid #3b82f6',
+            outlineOffset: '2px',
+            backgroundColor: 'rgba(59, 130, 246, 0.1)',
+        },
+    });
+}, []);
+```
+
+### Element Targeting
+
+Gebruik `data-cms-key` voor nauwkeurige targeting:
+
+```tsx
+<h1 data-cms-key="blog:title">{t('blog:title')}</h1>
+<p data-cms-key="blog:excerpt">{t('blog:excerpt')}</p>
 ```
 
-All keys must use `namespace:key` format. Bare keys (`t('save')`) produce a
-warning.
+---
 
-### `routeParams` — mock params for dynamic routes
+# JSON Output Format
 
-The scanner detects which route each key is used on automatically. For dynamic
-routes (e.g. `/[locale]/blog/[slug]`), add mock params in `.translationsrc.json`
-so the CMS can generate a working preview URL:
+Na `sync-translations pull` worden dit soort bestanden gegenereerd:
 
 ```json
 {
-    "routeParams": {
-        "/[locale]/blog/[slug]": { "slug": "first-post" },
-        "/[locale]/products/[slug]": { "slug": "product-a" }
+    "common": {
+        "app.title": "Mijn App",
+        "button.save": "Opslaan",
+        "nav.home": "Home"
+    },
+    "auth": {
+        "login.email": "Email",
+        "login.password": "Wachtwoord"
     }
 }
 ```
 
-The scanner applies these automatically to every key it detects on that route —
-no need to repeat params per key.
+**Structuur:**
 
-### Scan options (`.translationsrc.json`)
+- Top-level keys = namespaces
+- Nested keys = translation strings
+- 1 bestand per taal (`en.json`, `nl.json`, etc.)
 
-```json
-{
-    "excludedDirs": ["e2e", "fixtures"],
-    "sourceExtensions": [".ts", ".tsx", ".js", ".jsx", ".vue"],
-    "reservedCssNamespaces": ["after", "before"]
-}
+---
+
+# Troubleshooting
+
+### Geen keys gevonden
+
+```bash
+# Check scanner configuratie
+pnpm sync-translations sync --dry-run
 ```
 
+Zorg dat je keys `namespace:key` format gebruiken.
+
+### Environment variables niet gevonden
+
+Controleer `.env.local`:
+
+```bash
+cat .env.local | grep NEXT_PUBLIC_CMS
+```
+
+Moet `NEXT_PUBLIC_CMS_URL`, `NEXT_PUBLIC_CMS_PROJECT_ID`,
+`NEXT_PUBLIC_CMS_ANON_KEY` bevatten.
+
+### Pull werkt niet
+
+```bash
+# Force refresh, negeer cache
+pnpm sync-translations pull --force
+
+# Check configuratie
+cat .translationsrc.json
+```
+
+### Type errors in TypeScript
+
+Zorg dat `src/lib/i18n/types.ts` correct gegenereerd is en dat je namespaces in
+`.translationsrc.json` staan.
+
+---
+
+# Best Practices
+
+1. **Gebruik server components** waar mogelijk — beter voor performance
+2. **Voeg `data-cms-key` toe** op visueel belangrijke elementen
+3. **Commit `.translationsrc.json`** naar git — niet `.env.local`
+4. **Negeer cache bestanden:** voeg toe aan `.gitignore`:
+    ```
+    .cms-sync-cache.json
+    .cms-sync-cache-meta.json
+    .last-pulled
+    ```
+5. **Run `sync` in CI/CD** op main branch — catch missing translations
+6. **Voeg `pull` toe aan build script** — altijd fresh translations
+
 ---
 
-## License
+# License
 
 MIT