@translation-cms/sync 1.2.9 → 1.2.12

package/README.md

@@ -1,18 +1,98 @@
 # @translation-cms/sync
 
-Automatisch vertaalsleutels uit je codebase scannen, syncen met de Translations
-CMS, en vertalingen ophalen als lokale JSON-bestanden. Gebouwd voor Next.js +
-i18next.
+Automatically scan translation keys from your codebase, sync with the
+Translations CMS, and fetch translations as local JSON files. Built for
+Next.js + i18next.
 
-## Wat is dit?
+## Integration Methods
 
-Een CLI-tool die je workflow vereenvoudigt:
+Choose the approach that fits your workflow:
 
-- 🔍 **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
+- **Next.js Plugin** (Recommended) — Automatic sync on `next dev` and
+  `next build`
+- **CLI** (Manual) — `pnpm sync-translations` for on-demand control
+- **Programmatic API** — Call sync/pull directly in your code or scripts
+
+### Method 1: Next.js Plugin (Automatic)
+
+Edit `next.config.ts`:
+
+```ts
+import withTranslationsCMS from '@translation-cms/sync/next';
+
+export default withTranslationsCMS(
+    {
+        // your Next.js config
+    },
+    {
+        pullOnBuild: true, // auto pull on build
+        pullOnDev: true, // auto pull on dev startup
+    }
+);
+```
+
+Your translations sync automatically. That's it. No extra commands needed.
+
+### Method 2: CLI (Manual)
+
+```bash
+# Scan code + upload to CMS
+pnpm sync-translations sync
+
+# Download translations
+pnpm sync-translations pull
+
+# Watch mode — auto-sync on file changes
+pnpm sync-translations watch
+
+# Interactive setup
+pnpm sync-translations init
+```
+
+### Method 3: Programmatic API
+
+Use in scripts, build tools, or CI/CD:
+
+```ts
+import { syncTranslations, pullTranslations } from '@translation-cms/sync/api';
+
+// Scan and upload keys
+await syncTranslations({
+    projectRoot: './my-app',
+    verbose: true,
+});
+
+// Download translations
+await pullTranslations({
+    projectRoot: './my-app',
+    environment: 'production',
+});
+
+// Sync and pull in one go
+import { syncAndPull } from '@translation-cms/sync/api';
+await syncAndPull({ projectRoot: './my-app' });
+```
+
+### Choose Your Method
+
+| Method               | When to Use                       | Setup Time |
+| -------------------- | --------------------------------- | ---------- |
+| **Next.js Plugin**   | Team projects, automatic workflow | 5 min      |
+| **CLI**              | Manual control, debugging, CI/CD  | 10 min     |
+| **Programmatic API** | Custom workflows, scripts         | 5 min      |
+
+**Recommended:** Start with the **Next.js Plugin** for automatic updates during
+development, then add CLI or API commands as needed.
+
+## What is this?
+
+Hybrid translation management system with three integration methods:
+
+- **Scans** your code for translation keys (React-i18next pattern)
+- **Syncs** new keys to the Translations CMS
+- **Fetches** translations as JSON files
+- **Automatic or manual** — choose what works for your team
+- **Programmatic API** — bring your own CI/CD or tooling
 
 ```
 Your Code → scan → CMS → pull → JSON files → i18next → Your App
@@ -20,64 +100,125 @@ Your Code → scan → CMS → pull → JSON files → i18next → Your App
 
 ---
 
-# Setup Handleiding — Van Nul Tot Functie
+## Programmatic API Reference
+
+Use these functions when you need fine-grained control or integration with
+custom workflows. Perfect for CI/CD pipelines, build tools, or custom scripts.
+
+### `syncTranslations(options?)`
+
+Scans your codebase for translation keys and uploads them to the CMS.
 
-## Stap 1: Vereisten
+```ts
+import { syncTranslations } from '@translation-cms/sync/api';
+
+const result = await syncTranslations({
+    projectRoot: './apps/web', // auto-detect if omitted
+    dryRun: false, // preview without uploading
+    force: false, // ignore cache
+    reportPath: './sync-report.json', // optional report output
+    verbose: true, // detailed logging
+});
 
-Controleer wat je nodig hebt:
+console.log(`Added ${result.keysAdded} keys`);
+```
 
-- ✅ Next.js project (v14+)
-- ✅ pnpm (aanbevolen) of npm
-- ✅ Translations CMS account + project aangemaakt
-- ✅ CMS project credentials (URL, project ID, API key)
+### `pullTranslations(options?)`
 
-## Stap 2: Installatie
+Fetches translations from the CMS and writes them as JSON files.
+
+```ts
+import { pullTranslations } from '@translation-cms/sync/api';
+
+const result = await pullTranslations({
+    projectRoot: './apps/web', // auto-detect if omitted
+    outputDir: './src/i18n/locales', // custom output location
+    force: false, // ignore cache
+    ttl: 300000, // cache duration in ms
+    environment: 'production', // pull from specific env
+    verbose: true, // detailed logging
+});
+```
+
+### `syncAndPull(options?)`
+
+Convenience function: sync keys then pull translations in one call.
+
+```ts
+import { syncAndPull } from '@translation-cms/sync/api';
+
+const { synced, pulled } = await syncAndPull({
+    projectRoot: './apps/web',
+    verbose: true,
+});
+```
+
+---
+
+# Setup Guide — From Zero to Working
+
+## Step 1: Prerequisites
+
+Check what you need:
+
+- Next.js project (v14+)
+- pnpm (recommended) or npm
+- Translations CMS account + project created
+- CMS project credentials (URL, project ID, API key)
+
+## Step 2: Installation
 
 ```bash
 pnpm add @translation-cms/sync
 ```
 
-Plus de peer dependencies:
+Plus the peer dependencies:
 
 ```bash
 pnpm add i18next react-i18next i18next-resources-to-backend
 ```
 
-## Stap 3: CMS Credentials Instellen
+## Step 3: Set Up CMS Credentials
 
-Maak `.env.local` aan in je project root:
+Create `.env.local` in your project root:
 
 ```bash
 NEXT_PUBLIC_CMS_URL=https://cms.example.com
 NEXT_PUBLIC_CMS_PROJECT_ID=your-project-id
-NEXT_PUBLIC_CMS_ANON_KEY=your-api-key
+CMS_SYNC_API_KEY=your-jwt-api-key
 ```
 
-Deze krijg je uit je CMS project settings.
+The `CMS_SYNC_API_KEY` is a **JWT token**. You can find it in the CMS under
+**Project Settings → Environments → your environment → API Key**. If the key
+there still looks like a UUID, use "Regenerate" to generate a JWT.
+
+> **Note:** use `CMS_SYNC_API_KEY` (without `NEXT_PUBLIC_`). This prevents the
+> JWT from accidentally ending up in the browser. The old name
+> `NEXT_PUBLIC_CMS_ANON_KEY` still works as a fallback, but is discouraged.
 
-## Stap 4: Automatische Setup (Aanbevolen)
+## Step 4: Automatic Setup (Recommended)
 
-Run de interactive setup wizard:
+Run the interactive setup wizard:
 
 ```bash
 pnpm sync-translations init
 ```
 
-Dit maakt automatisch aan:
+This automatically creates:
 
 ```
 src/lib/i18n/
-  ├── settings.ts           # i18next configuratie
-  ├── types.ts              # TypeScript types voor translations
+  ├── settings.ts           # i18next configuration
+  ├── types.ts              # TypeScript types for 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)
+      ├── en.json           # English (empty, filled by pull)
+      └── nl.json           # Dutch (empty, filled by pull)
 ```
 
-Ook `.translationsrc.json` wordt gegenereerd:
+Also `.translationsrc.json` is generated:
 
 ```json
 {
@@ -88,57 +229,56 @@ Ook `.translationsrc.json` wordt gegenereerd:
 }
 ```
 
-**Let op:** `routeParams` kan leeg blijven! De scanner genereert automatisch
-sensible defaults voor alle dynamic routes.
+**Note:** `routeParams` can stay empty! The scanner automatically generates
+sensible defaults for all dynamic routes.
 
-## Stap 5: Eerste Sync — Keys Uploaden
+## Step 5: First Sync — Upload Keys
 
-Scan je code en upload gedetecteerde keys naar de CMS:
+Scan your code and upload detected keys to the CMS:
 
 ```bash
 pnpm sync-translations sync
 ```
 
-Dit zal:
+This will:
 
-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)
+1. Scan your code for translation keys (`t('namespace:key')` pattern)
+2. Detect routes where each key is used
+3. Upload new keys to CMS
+4. Show report (which keys added/changed)
 
-Controleer in de CMS of je keys verschenen zijn ✅
+Check in the CMS if your keys appeared.
 
-**Bij eerste sync:** je krijgt mogelijk een error dat geen vertalingen kunnen
-worden gedownload — dit is normaal! De keys zijn net geupload maar hebben nog
-geen vertalingen. Ga naar je CMS, vul vertalingen in, dan draai je `pull`
-opnieuw.
+**On first sync:** you might get an error that no translations can be downloaded
+— this is normal! The keys were just uploaded but don't have translations yet.
+Go to your CMS, fill in translations, then run `pull` again.
 
-## Stap 5b: Vertalingen Toevoegen in CMS
+## Step 5b: Add Translations in CMS
 
-1. Open je Translations CMS project
-2. Je keys staan nu gelistd (zonder vertalingen)
-3. Vul vertalingen in per locale (English, Nederlands, etc.)
-4. Klik Save
+1. Open your Translations CMS project
+2. Your keys are now listed (without translations)
+3. Fill in translations per locale (English, Dutch, etc.)
+4. Click Save
 
-## Stap 6: Vertalingen Ophalen
+## Step 6: Fetch Translations
 
-Als je de eerste sync hebt gedaan EN vertalingen in de CMS hebt ingevuld:
+If you've done the first sync AND filled in translations in the CMS:
 
 ```bash
 pnpm sync-translations pull
 ```
 
-Dit haalt vertalingen op van de CMS en schrijft ze naar lokale JSON:
+This fetches translations from the CMS and writes them to local JSON:
 
-- `dictionaries/en.json` → English vertalingen
-- `dictionaries/nl.json` → Nederlandse vertalingen
-- etc. (één per locale)
+- `dictionaries/en.json` → English translations
+- `dictionaries/nl.json` → Dutch translations
+- etc. (one per locale)
 
-## Stap 7: Integratie in je Project
+## Step 7: Integration in Your Project
 
 ### A. Root Layout Setup
 
-Voeg de provider toe aan je `src/app/layout.tsx`:
+Add the provider to your `src/app/layout.tsx`:
 
 ```tsx
 import { TranslationProvider } from '@/lib/i18n/provider';
@@ -158,7 +298,7 @@ export default function RootLayout({
 }
 ```
 
-### B. Server Components (Aanbevolen)
+### B. Server Components (Recommended)
 
 ```tsx
 import { getTranslation } from '@/lib/i18n/server';
@@ -188,22 +328,22 @@ export function MyButton() {
 }
 ```
 
-### D. Multiple Namespaces (Met Type-Checking)
+### D. Multiple Namespaces (With Type-Checking)
 
 ```tsx
 const { t } = useTranslation(['common', 'auth']);
 
-// ✅ Dit werkt
+// This works
 t('common:nav.home');
 t('auth:login.email');
 
-// ❌ Dit geeft een type error
-t('payments:amount'); // namespace niet toegevoegd
+// This gives a type error
+t('payments:amount'); // namespace not added
 ```
 
-## Stap 8: Automatische Sync in je Workflow
+## Step 8: Automatic Sync in Your Workflow
 
-Voeg dit toe aan `package.json`:
+Add this to `package.json`:
 
 ```json
 {
@@ -214,14 +354,14 @@ Voeg dit toe aan `package.json`:
 }
 ```
 
-Nu pull je automatisch de latest vertalingen bij startup ⚡
+Now you automatically pull the latest translations on startup.
 
-## Stap 9 (Optioneel): Preview Mode Instellen
+## Step 9 (Optional): Set Up Preview Mode
 
-Enable live in-context preview — editors kunnen live zien hoe hun tekst in je
-app eruit ziet.
+Enable live in-context preview — editors can live see how their text looks in
+your app.
 
-Voeg dit toe aan je root layout:
+Add this to your root layout:
 
 ```tsx
 'use client';
@@ -233,7 +373,7 @@ export function CMSPreview() {
         if (process.env.NODE_ENV === 'development') {
             initPreviewListener({
                 onLocaleSwitch: locale => {
-                    // wijzig taal als CMS een ander locale selecteert
+                    // change language if CMS selects a different locale
                     window.location.href = `/${locale}`;
                 },
             });
@@ -243,7 +383,7 @@ export function CMSPreview() {
 }
 ```
 
-En voeg toe in layout:
+And add to layout:
 
 ```tsx
 <TranslationProvider>
@@ -252,7 +392,7 @@ En voeg toe in layout:
 </TranslationProvider>
 ```
 
-Voeg `data-cms-key` toe op elementen voor nauwkeurige highlighting:
+Add `data-cms-key` to elements for precise highlighting:
 
 ```tsx
 <h1 data-cms-key="common:page.title">{t('common:page.title')}</h1>
@@ -262,110 +402,122 @@ Voeg `data-cms-key` toe op elementen voor nauwkeurige highlighting:
 
 # CLI Commands Reference
 
-## Basiscommands
+## Basic Commands
 
 ```bash
-# Scan code + upload naar CMS
+# Scan code + upload to CMS
 pnpm sync-translations sync
 
-# Download vertalingen naar lokale JSON
+# Download translations to local JSON
 pnpm sync-translations pull
 
-# Bekijk wat er zou veranderen (zonder upload)
+# See what would change (without upload)
 pnpm sync-translations sync --dry-run
 
-# Bekijk verschil met vorige sync
+# See difference from previous sync
 pnpm sync-translations status
 
-# Watch mode — auto-sync bij bestand wijzigingen
+# Watch mode — auto-sync on file changes
 pnpm sync-translations watch
 
-# Interactieve setup
+# Interactive setup
 pnpm sync-translations init
 ```
 
 ## Advanced Flags
 
-| 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  |
+| Flag              | Description                              |
+| ----------------- | ---------------------------------------- |
+| `--dry-run`       | Show changes, don't execute              |
+| `--force`         | Ignore cache, force refresh              |
+| `--output <dir>`  | Custom output directory for JSON         |
+| `--env <name>`    | Pull from staging/production environment |
+| `--ttl <ms>`      | Override cache TTL (ms)                  |
+| `--project-id`    | Override project ID                      |
+| `--api-key`       | Override API key                         |
+| `--cms-url`       | Override CMS URL                         |
+| `--report <file>` | Write sync report to JSON file           |
 
-## Voorbeelden
+## Examples
 
 ```bash
-# Force refresh, negeer cache
+# Force refresh, ignore cache
 pnpm sync-translations pull --force
 
 # Custom output directory
 pnpm sync-translations pull --output ./locales
 
-# Pull uit staging environment
+# Pull from staging environment
 pnpm sync-translations pull --env staging
 
-# Schrijf rapport van wijzigingen
+# Write report of changes
 pnpm sync-translations sync --report ./sync-report.json
 ```
 
 ---
 
-# Key Scanner — Hoe Werkt Het
+# Key Scanner — How It Works
 
-De tool herkent deze patronen in je code:
+The tool recognizes these patterns in your code:
 
 ```ts
-// ✅ React-i18next hook
+// React-i18next hook
 const { t } = useTranslation('blog');
 t('blog:post.title');
 
-// ✅ Trans component
+// Server-side helper
+const { t } = await getTranslation('blog');
+t('blog:post.title');
+
+// CMS client helper
+const t = await client.getTranslations(locale, 'blog');
+t('blog:post.title');
+
+// Trans component
 <Trans i18nKey="blog:post.title" />
 
-// ✅ String literal
-const key = 'blog:post.title';
+// I18nKey-typed config (only if the file imports `I18nKey`)
+import type { I18nKey } from '@/lib/i18n/types';
+const label: I18nKey = 'sidebar:settings';
+
+// Object properties ending in "Key"
+const config = { titleKey: 'blog:post.title' };
 ```
 
 ### Format: `namespace:key`
 
-Alle keys moeten dit format volgen. Anders krijg je een warning:
+All keys must follow this format. Otherwise you'll get a warning:
 
 ```ts
-// ✅ Goed
+// Good
 t('common:button.save');
 
-// ❌ Fout — namespace mist
+// Wrong — namespace missing
 t('save');
 ```
 
-### Dynamische Routes — Auto-Generated routeParams
+### Dynamic Routes — Auto-Generated routeParams
 
-**Hoe het werkt:**
+**How it works:**
 
-Bij elke `pnpm sync-translations sync`:
+At each `pnpm sync-translations sync`:
 
-1. Scanner detecteert automatisch alle routes met dynamic parameters (bijv.
+1. Scanner automatically detects all routes with dynamic parameters (e.g.
    `/[locale]/blog/[slug]`)
-2. Voor elke `[param]` wordt automatisch een sensible default gegenereerd:
+2. For each `[param]` a sensible default is automatically generated:
     - `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
+3. This is saved in `.cms-sync-cache-meta.json` (you can ignore it)
+4. The CMS uses this to generate working preview URLs
 
-**Je hoeft niks te doen!** — alles werkt out-of-the-box.
+**You don't have to do anything!** — everything works out-of-the-box.
 
-**Handmatig overschrijven (optioneel):**
+**Manual override (optional):**
 
-Als je andere test-waarden wil gebruiken, vul je `.translationsrc.json` in:
+If you want to use different test values, fill in `.translationsrc.json`:
 
 ```json
 {
@@ -376,21 +528,21 @@ Als je andere test-waarden wil gebruiken, vul je `.translationsrc.json` in:
 }
 ```
 
-Dit overschrijft de auto-generated waarden. Alles wat je hier toevoegt krijgt
-prioriteit.
+This overrides the auto-generated values. Everything you add here takes
+priority.
 
-### Cache bestanden
+### Cache Files
 
-Bij elke sync worden twee cache bestanden aangemaakt:
+At each sync two cache files are created:
 
-- `.cms-sync-cache.json` — Geüploade keys en hun routes (voor diff bij volgende
+- `.cms-sync-cache.json` — Uploaded keys and their routes (for diff on next
   sync)
-- `.cms-sync-cache-meta.json` — Auto-generated route params (mag je .gitignore
-  toevoegen)
+- `.cms-sync-cache-meta.json` — Auto-generated route params (you can add to
+  .gitignore)
 
-### Scanner Opties
+### Scanner Options
 
-Customize scan gedrag in `.translationsrc.json`:
+Customize scan behavior in `.translationsrc.json`:
 
 ```json
 {
@@ -406,8 +558,8 @@ Customize scan gedrag in `.translationsrc.json`:
 
 ## Preview Mode — Live Highlighting
 
-Editors kunnen in de CMS klikken op "Show in app" en je app opent in een iframe
-met live highlighting van het element.
+Editors can click "Show in app" in the CMS and your app opens in an iframe with
+live highlighting of the element.
 
 ### Setup
 
@@ -428,7 +580,7 @@ useEffect(() => {
 
 ### Element Targeting
 
-Gebruik `data-cms-key` voor nauwkeurige targeting:
+Use `data-cms-key` for precise targeting:
 
 ```tsx
 <h1 data-cms-key="blog:title">{t('blog:title')}</h1>
@@ -439,82 +591,83 @@ Gebruik `data-cms-key` voor nauwkeurige targeting:
 
 # JSON Output Format
 
-Na `sync-translations pull` worden dit soort bestanden gegenereerd:
+After `sync-translations pull` these kinds of files are generated:
 
 ```json
 {
     "common": {
-        "app.title": "Mijn App",
-        "button.save": "Opslaan",
+        "app.title": "My App",
+        "button.save": "Save",
         "nav.home": "Home"
     },
     "auth": {
         "login.email": "Email",
-        "login.password": "Wachtwoord"
+        "login.password": "Password"
     }
 }
 ```
 
-**Structuur:**
+**Structure:**
 
 - Top-level keys = namespaces
 - Nested keys = translation strings
-- 1 bestand per taal (`en.json`, `nl.json`, etc.)
+- 1 file per language (`en.json`, `nl.json`, etc.)
 
 ---
 
 # Troubleshooting
 
-### Geen keys gevonden
+### No keys found
 
 ```bash
-# Check scanner configuratie
+# Check scanner configuration
 pnpm sync-translations sync --dry-run
 ```
 
-Zorg dat je keys `namespace:key` format gebruiken.
+Make sure your keys use `namespace:key` format.
 
-### Environment variables niet gevonden
+### Environment variables not found
 
-Controleer `.env.local`:
+Check `.env.local`:
 
 ```bash
-cat .env.local | grep NEXT_PUBLIC_CMS
+grep -E 'CMS_URL|CMS_PROJECT_ID|CMS_SYNC_API_KEY' .env.local
 ```
 
-Moet `NEXT_PUBLIC_CMS_URL`, `NEXT_PUBLIC_CMS_PROJECT_ID`,
-`NEXT_PUBLIC_CMS_ANON_KEY` bevatten.
+Must contain `NEXT_PUBLIC_CMS_URL`, `NEXT_PUBLIC_CMS_PROJECT_ID` and
+`CMS_SYNC_API_KEY`. The value of `CMS_SYNC_API_KEY` is a JWT token — get it from
+the CMS Project Settings.
 
-### Pull werkt niet
+### Pull doesn't work
 
 ```bash
-# Force refresh, negeer cache
+# Force refresh, ignore cache
 pnpm sync-translations pull --force
 
-# Check configuratie
+# Check configuration
 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.
+Make sure `src/lib/i18n/types.ts` is generated correctly and that your
+namespaces are in `.translationsrc.json`.
 
 ---
 
 # 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`:
+1. **Use server components** where possible — better for performance
+2. **Add `data-cms-key`** on visually important elements
+3. **Commit `.translationsrc.json`** to git — not `.env.local`
+4. **Ignore cache files:** add to `.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
+5. **Run `sync` in CI/CD** on main branch — catch missing translations
+6. **Add `pull` to build script** — always fresh translations
 
 ---