@translation-cms/sync

v1.2.132

Published

a month ago

Scan translation keys in your codebase and sync them to the Translations CMS

0High
0Medium
0Low

rickveerman

translations i18n cms sync

@translation-cms/sync

Scan translation keys in je codebase en sync ze naar de Translations CMS. Haul vertalingen automatisch op in dev-mode via Next.js plugin. Gebouwd voor Next.js

i18next met full TypeScript support.

Hoe werkt het?

| Wat | Waar | Hoe | | -------------------- | --------------------------------- | -------------------------------- | | Pull vertalingen | Build pipeline (next build) | Plugin (automatisch) | | Scan + sync keys | CI/CD pipeline (na merge develop) | CLI (sync-translations sync) | | Status check | Lokale dev | CLI (sync-translations status) |

Setup

Stap 1: Installeren

pnpm add @translation-cms/sync
pnpm add i18next react-i18next i18next-resources-to-backend

Stap 2: Configuratie

Creëer .translationsrc.json in je project root:

{
    "cmsUrl": "https://cms.example.nl",
    "outputDir": "src/lib/i18n/dictionaries"
}

Voeg je API key toe aan .env.local:

CMS_SYNC_API_KEY=eyJ...

Zoek je API key? In de CMS: Project Settings → Environments → jouw environment → API Key

Opmerking: projectId wordt automatisch uit de API key geëxtraheerd. Je hoeft het niet handmatig in te voeren of op te slaan.

Stap 3: Plugin in next.config.ts

import withTranslationsCMS from '@translation-cms/sync/next';
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {};

export default withTranslationsCMS(nextConfig);

Automatische workflow per omgeving:

| Omgeving | Commando | Wat de plugin doet | | ---------------- | ----------------------------------- | ------------------------------ | | Development | pnpm dev | ❌ Niks (geen pull/sync) | | Staging build | ENVIRONMENT=staging pnpm build | ✅ Sync keys (upload naar CMS) | | Production build | ENVIRONMENT=production pnpm build | ✅ Pull vertalingen |

De plugin detecteert automatisch of je aan het bouwen bent en welke omgeving (staging vs production) je target. Pull vertalingen moet handmatig gebeuren met pnpm sync-translations pull.

Stap 4: i18n Setup

Voeg de provider toe aan src/app/layout.tsx:

import { TranslationProvider } from '@/lib/i18n/provider';

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <html>
            <body>
                <TranslationProvider>{children}</TranslationProvider>
            </body>
        </html>
    );
}

Vertalingen gebruiken in je app

Server Component

import { getTranslation } from '@/lib/i18n/server';

export default async function Page() {
    const { t } = await getTranslation('common');
    return <h1>{t('common:app.title')}</h1>;
}

Client Component

'use client';
import { useTranslation } from '@/lib/i18n/client';

export function MyButton() {
    const { t } = useTranslation('common');
    return <button>{t('common:button.click')}</button>;
}

Meerdere namespaces

const { t } = useTranslation(['common', 'auth']);

t('common:nav.home'); // ✓
t('auth:login.email'); // ✓
t('payments:amount'); // TypeScript-fout — namespace niet geladen

CLI Commands

Voor project scanning, syncing, en CI/CD pipelines:

# Scan keys en upload naar CMS
sync-translations sync

# Download gepubliceerde vertalingen
sync-translations pull

# Zie wat veranderd is (lokaal, geen netwerk)
sync-translations status

# Eenmalige setup (manueel config-generator)
sync-translations init

# Bypass cache, altijd opnieuw laden
sync-translations pull --force

# Toon wat zou veranderen zonder uit te voeren
sync-translations sync --dry-run

# Aangepaste output-map
sync-translations pull --output ./translations

# Specifieke omgeving (staging/production)
sync-translations pull --env staging

Handige flags:

| Flag | Beschrijving | | ---------------- | ---------------------------------------------------------- | | --force | TTL cache negeren, altijd opnieuw ophalen | | --dry-run | Toon wijzigingen, voer niet uit (sync) | | --output <dir> | Aangepaste output-map voor JSON | | --env <naam> | Pull van specifieke omgeving | | --ttl <ms> | Cache TTL in milliseconden | | --project-id | Projectnummer (optioneel — wordt uit API key geëxtraheerd) |

Programmatic API

Voor custom scripts en CI/CD workflows:

import {
    syncTranslations,
    pullTranslations,
    watchTranslations,
} from '@translation-cms/sync/api';

// Keys scannen en uploaden naar CMS
await syncTranslations({
    projectRoot: '.',
    verbose: true,
});

// Vertalingen ophalen en naar disk schrijven
await pullTranslations({
    cmsUrl: process.env.CMS_URL,
    projectId: process.env.CMS_PROJECT_ID,
    apiKey: process.env.CMS_SYNC_API_KEY,
    outputDir: 'src/lib/i18n/dictionaries',
    force: false, // skip cache als true
});

// Optioneel: polling voor CMS-updates
watchTranslations({
    checkInterval: 300_000, // elke 5 minuten
});

Troubleshooting

| Probleem | Oplossing | | -------------------------------- | --------------------------------------------------------------- | | Geen keys gevonden | Zorg dat je t('namespace:key') gebruikt — namespace verplicht | | Plugin haalt niet op | Check .translationsrc.json: cmsUrl, projectId ingesteld | | CMS_SYNC_API_KEY niet herkend | Herstart dev server na wijzigen van .env.local | | Pull mislukt (credentials error) | Controleer API key in CMS Project Settings | | Cache stale (oude vertalingen) | Gebruik sync-translations pull --force om te flushen | | Wil preview van wijzigingen | sync-translations sync --dry-run toont wat zou veranderen |

Best practices

✅ Commit .translationsrc.json — dit is shared config (bevat geen projectId meer)
❌ Commit .env.local NIET — bevat API keys

Voeg toe aan .gitignore:

.env.local
.cms-sync-cache.json
.cms-sync-cache-meta.json

Gebruik server components waar mogelijk — beter voor performance
Keys scannen gebeurt automatisch in CI/CD — developers hoeven niks handmatig
Lokale development: sync-translations pull handmatig draaien of pullOnDev: true in next.config.ts

Workflow voor je team

Developers (Lokaal):

Voeg t('namespace:key') toe in code
Run pnpm dev (plugin doet NIKS)
Handmatig vertalingen ophalen: pnpm sync-translations pull
Push naar develop

CI/CD Pipeline (Staging build):

ENVIRONMENT=staging pnpm build
Plugin draait: sync keys (upload naar CMS)
Vervolgens: pnpm sync-translations pull --env staging (fetch vertalingen)
Build artifact klaar voor testing

CI/CD Pipeline (Production build):

ENVIRONMENT=production pnpm build
Plugin draait: pull vertalingen (van gepubliceerde CMS release)
Build artifact klaar voor live

Editors (CMS):

Vul/edit vertalingen in CMS
Publiceer naar staging → production
Production build getriggerd automatisch

MIT License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@translation-cms/sync

Hoe werkt het?

Setup

Stap 1: Installeren

Stap 2: Configuratie

Stap 3: Plugin in next.config.ts

Stap 4: i18n Setup

Vertalingen gebruiken in je app

Server Component

Client Component

Meerdere namespaces

CLI Commands

Programmatic API

Troubleshooting

Best practices

Workflow voor je team