@metasyncsite/translations-client-ts 1.0.0

package/README.md

@@ -0,0 +1,322 @@
+# @metasyncsite/translations-client-ts
+
+TypeScript client for pushing and pulling i18n translations to/from the Translation Manager. Works with any Node.js project: Vue, React, Next.js, Nuxt, etc.
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.0 (dev dependency)
+
+---
+
+## Installation
+
+```bash
+npm install @metasyncsite/translations-client-ts
+# or
+pnpm add @metasyncsite/translations-client-ts
+# or
+yarn add @metasyncsite/translations-client-ts
+```
+
+---
+
+## Local Installation (without npm registry)
+
+If the package is not yet published, you have three options:
+
+### Option 1 — file path in package.json (recommended)
+
+Build the package first, then reference it by path in your project's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@metasyncsite/translations-client-ts": "file:../path/to/translations-client-node-ts"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm install
+# or
+pnpm install
+```
+
+> The path must point to the package root (where `package.json` lives). Use a relative or absolute path.
+
+---
+
+### Option 2 — npm pack (portable tarball)
+
+Build and pack the package into a `.tgz` file, then install that file in any project:
+
+```bash
+# Inside the package directory
+cd packages/translations-client-node-ts
+npm run build
+npm pack
+# → creates metasyncsite-translations-client-ts-1.0.0.tgz
+```
+
+Then install the tarball in your project:
+
+```bash
+npm install /path/to/metasyncsite-translations-client-ts-1.0.0.tgz
+# or
+pnpm add /path/to/metasyncsite-translations-client-ts-1.0.0.tgz
+```
+
+> Good when you want to share the package without a registry — just copy the `.tgz` file.
+
+---
+
+### Option 3 — npm link (symlink, for active development)
+
+Use this when you're actively editing the package and want changes to reflect immediately:
+
+```bash
+# 1. Inside the package directory — register a global symlink
+cd packages/translations-client-node-ts
+npm run build
+npm link
+
+# 2. Inside your consuming project — link to it
+cd /path/to/your-project
+npm link @metasyncsite/translations-client-ts
+```
+
+To unlink when done:
+
+```bash
+# Inside your project
+npm unlink @metasyncsite/translations-client-ts
+
+# Inside the package directory
+npm unlink
+```
+
+> With `npm link`, you must re-run `npm run build` (or `npm run dev` for watch mode) after each source change.
+
+---
+
+## Build (if working from source)
+
+```bash
+cd packages/translations-client-node-ts
+npm install
+npm run build   # compiles src/ → dist/
+```
+
+---
+
+## Configuration
+
+The client reads credentials from environment variables or CLI flags.
+
+### Environment variables
+
+Add to your project's `.env`:
+
+```env
+TRANSLATIONS_URL=https://translations.example.com
+TRANSLATIONS_TOKEN=your-api-token
+TRANSLATIONS_LOCALES_PATH=src/locales   # optional, default: src/locales
+```
+
+---
+
+## CLI Usage
+
+After installing the package, two CLI commands are available:
+
+### Push (upload local translations → Translation Manager)
+
+```bash
+npx translations-push
+```
+
+With explicit flags:
+
+```bash
+npx translations-push \
+  --url https://translations.example.com \
+  --token your-api-token \
+  --path src/locales \
+  --locale en \          # push only this locale (optional)
+  --overwrite true \     # overwrite existing keys (default: true)
+  --dry-run \            # preview without sending
+  --exclude i18n.json,test.json  # comma-separated files to skip
+```
+
+### Pull (download translations from Translation Manager → local files)
+
+```bash
+npx translations-pull
+```
+
+With explicit flags:
+
+```bash
+npx translations-pull \
+  --url https://translations.example.com \
+  --token your-api-token \
+  --path src/locales \
+  --locale de \          # pull only this locale (optional)
+  --layout grouped \     # force layout: flat | grouped (optional, auto-detected)
+  --dry-run              # preview without writing files
+```
+
+### Add to package.json scripts
+
+```json
+{
+  "scripts": {
+    "translations:push": "translations-push",
+    "translations:pull": "translations-pull"
+  }
+}
+```
+
+---
+
+## Locale Layouts
+
+The client auto-detects which layout your project uses:
+
+| Layout | Structure | Example |
+|--------|-----------|---------|
+| `flat` | One JSON file per locale | `locales/en.json`, `locales/de.json` |
+| `grouped` | One subdirectory per locale | `locales/en/auth.json`, `locales/de/auth.json` |
+
+---
+
+## Programmatic API
+
+Import and use the client functions directly in TypeScript:
+
+```ts
+import {
+  readLocales,
+  detectLayout,
+  pushLocale,
+  writeGroupedLocale,
+  writeFlatLocale,
+} from '@metasyncsite/translations-client-ts'
+
+import type {
+  LocaleData,
+  LocaleGroups,
+  PushLocaleParams,
+  PushResult,
+} from '@metasyncsite/translations-client-ts'
+
+// Read all locales from disk
+const locales: LocaleData[] = readLocales('./src/locales')
+
+// Push a single locale
+const result: PushResult = await pushLocale({
+  url: 'https://translations.example.com',
+  token: 'your-api-token',
+  locale: 'en',
+  groups: locales[0].groups,
+  overwrite: true,
+})
+
+console.log(`${result.new} new, ${result.updated} updated, ${result.total} total`)
+
+// Detect layout
+const layout = detectLayout('./src/locales')  // 'flat' | 'grouped' | null
+
+// Write pulled translations to disk
+const groups: LocaleGroups = { auth: { 'login': 'Login', 'logout': 'Logout' } }
+writeGroupedLocale('./src/locales', 'en', groups)
+```
+
+---
+
+## API Reference
+
+### `readLocales(localesPath, excludeFiles?)`
+
+Auto-detects layout and reads all locale files.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `localesPath` | `string` | Absolute or relative path to locales directory |
+| `excludeFiles` | `string[]` | Filenames to skip (e.g. `['index.json']`) |
+
+Returns: `LocaleData[]`
+
+---
+
+### `detectLayout(localesPath)`
+
+Returns `'flat'`, `'grouped'`, or `null` if the directory doesn't exist or is empty.
+
+---
+
+### `pushLocale(params)`
+
+Pushes one locale's groups to the Translation Manager API.
+
+| Param | Type | Default |
+|-------|------|---------|
+| `url` | `string` | — |
+| `token` | `string` | — |
+| `locale` | `string` | — |
+| `groups` | `LocaleGroups` | — |
+| `overwrite` | `boolean` | `true` |
+
+Returns: `Promise<PushResult>`
+
+---
+
+### `writeGroupedLocale(localesPath, locale, groups)`
+
+Writes translations in grouped layout (`locales/{locale}/{group}.json`).  
+The special `_json` group is written as `locales/{locale}.json`.
+
+Returns: `string[]` — paths of written files.
+
+---
+
+### `writeFlatLocale(localesPath, locale, groups)`
+
+Merges all groups and writes `locales/{locale}.json`.
+
+Returns: `string[]` — paths of written files.
+
+---
+
+### `unflatten(flat)`
+
+Converts dot-notation keys back to a nested object.
+
+```ts
+unflatten({ 'auth.login': 'Login' })
+// → { auth: { login: 'Login' } }
+```
+
+---
+
+## Types
+
+All exported types are available from the main entry point:
+
+```ts
+import type {
+  FlatKeys,        // Record<string, string>
+  LocaleGroups,    // Record<string, FlatKeys>
+  LocaleLayout,    // 'flat' | 'grouped'
+  LocaleData,      // { locale: string, groups: LocaleGroups }
+  PushLocaleParams,
+  PushResult,      // { new: number, updated: number, total: number }
+  PullOptions,
+  PushOptions,
+} from '@metasyncsite/translations-client-ts'
+```

package/dist/apiClient.d.ts

@@ -0,0 +1,10 @@
+import type { PushLocaleParams, PushResult } from './types.js';
+/**
+ * Push a single locale's translations to the Translation Manager API.
+ */
+export declare function pushLocale({ url, token, locale, groups, overwrite, }: PushLocaleParams): Promise<PushResult>;
+/**
+ * Fetch JSON from a Translation Manager API endpoint.
+ */
+export declare function fetchJson<T = unknown>(url: string, token: string): Promise<T>;
+//# sourceMappingURL=apiClient.d.ts.map

package/dist/apiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../src/apiClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE9D;;GAEG;AACH,wBAAsB,UAAU,CAAC,EAC/B,GAAG,EACH,KAAK,EACL,MAAM,EACN,MAAM,EACN,SAAgB,GACjB,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBxC;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAanF"}

package/dist/apiClient.js

@@ -0,0 +1,36 @@
+/**
+ * Push a single locale's translations to the Translation Manager API.
+ */
+export async function pushLocale({ url, token, locale, groups, overwrite = true, }) {
+    const endpoint = `${url.replace(/\/$/, '')}/api/v1/import`;
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ locale, groups, overwrite }),
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`HTTP ${response.status}: ${body}`);
+    }
+    return response.json();
+}
+/**
+ * Fetch JSON from a Translation Manager API endpoint.
+ */
+export async function fetchJson(url, token) {
+    const res = await fetch(url, {
+        headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+    }
+    return res.json();
+}
+//# sourceMappingURL=apiClient.js.map

package/dist/apiClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiClient.js","sourceRoot":"","sources":["../src/apiClient.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAC/B,GAAG,EACH,KAAK,EACL,MAAM,EACN,MAAM,EACN,SAAS,GAAG,IAAI,GACC;IACjB,MAAM,QAAQ,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAA;IAE1D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;QACrC,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,MAAM,EAAE,kBAAkB;YAC1B,aAAa,EAAE,UAAU,KAAK,EAAE;SACjC;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;KACpD,CAAC,CAAA;IAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;QAClC,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,CAAA;IACrD,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,EAAyB,CAAA;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAc,GAAW,EAAE,KAAa;IACrE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,OAAO,EAAE;YACP,MAAM,EAAE,kBAAkB;YAC1B,aAAa,EAAE,UAAU,KAAK,EAAE;SACjC;KACF,CAAC,CAAA;IAEF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,KAAK,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAC5D,CAAC;IAED,OAAO,GAAG,CAAC,IAAI,EAAgB,CAAA;AACjC,CAAC"}

package/dist/bin/pull.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=pull.d.ts.map

package/dist/bin/pull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../src/bin/pull.ts"],"names":[],"mappings":""}

package/dist/bin/pull.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { detectLayout } from '../langReader.js';
+import { writeGroupedLocale, writeFlatLocale } from '../langWriter.js';
+import { fetchJson } from '../apiClient.js';
+function loadDotEnv(cwd) {
+    const envPath = join(cwd, '.env');
+    if (!existsSync(envPath)) {
+        return;
+    }
+    const lines = readFileSync(envPath, 'utf8').split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1) {
+            continue;
+        }
+        const key = trimmed.slice(0, eqIndex).trim();
+        const rawValue = trimmed.slice(eqIndex + 1).trim();
+        const value = rawValue.replace(/^["']|["']$/g, '');
+        if (!(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+}
+function parseArgs(argv) {
+    const args = { flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const eqIdx = arg.indexOf('=');
+            const rawKey = eqIdx === -1 ? arg.slice(2) : arg.slice(2, eqIdx);
+            const key = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+            if (eqIdx !== -1) {
+                args.flags[key] = arg.slice(eqIdx + 1);
+            }
+            else if (argv[i + 1] && !argv[i + 1].startsWith('--')) {
+                args.flags[key] = argv[i + 1];
+                i++;
+            }
+            else {
+                args.flags[key] = true;
+            }
+        }
+    }
+    return args;
+}
+async function main() {
+    const cwd = process.cwd();
+    loadDotEnv(cwd);
+    const { flags } = parseArgs(process.argv.slice(2));
+    const url = flags['url'] ?? process.env['TRANSLATIONS_URL'];
+    const token = flags['token'] ?? process.env['TRANSLATIONS_TOKEN'];
+    const localesPath = resolve(cwd, flags['path'] ??
+        process.env['TRANSLATIONS_LOCALES_PATH'] ??
+        'src/locales');
+    const onlyLocale = flags['locale'] ?? null;
+    const dryRun = flags['dryRun'] === true || flags['dryRun'] === 'true';
+    const forcedLayout = flags['layout'] ?? null;
+    if (!url || !token) {
+        console.error('Error: TRANSLATIONS_URL and TRANSLATIONS_TOKEN are required.');
+        process.exit(1);
+    }
+    const base = url.replace(/\/$/, '');
+    const langData = await fetchJson(`${base}/api/v1/languages`, token);
+    let locales = langData.data.map((l) => l.code);
+    if (onlyLocale) {
+        locales = locales.filter((c) => c === onlyLocale);
+        if (locales.length === 0) {
+            console.warn(`Locale "${onlyLocale}" not found in Translation Manager.`);
+            process.exit(0);
+        }
+    }
+    const layout = forcedLayout ?? detectLayout(localesPath) ?? 'grouped';
+    const prefix = dryRun ? '[DRY RUN] ' : '';
+    console.log(`${prefix}Pulling ${locales.length} locale(s) [${layout} layout]: ${locales.join(', ')}`);
+    for (const locale of locales) {
+        const data = await fetchJson(`${base}/api/v1/translations/${locale}?format=nested`, token);
+        const groups = data.data ?? {};
+        const keyCount = Object.values(groups).reduce((sum, g) => sum + Object.keys(g).length, 0);
+        if (dryRun) {
+            console.log(`  ${locale}: ${keyCount} keys across ${Object.keys(groups).length} group(s).`);
+            continue;
+        }
+        const written = layout === 'grouped'
+            ? writeGroupedLocale(localesPath, locale, groups)
+            : writeFlatLocale(localesPath, locale, groups);
+        console.log(`  ✓ ${locale}: ${keyCount} keys → ${written.length} file(s) written.`);
+    }
+    if (!dryRun) {
+        console.log('\nDone.');
+    }
+}
+main();
+//# sourceMappingURL=pull.js.map

package/dist/bin/pull.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull.js","sourceRoot":"","sources":["../../src/bin/pull.ts"],"names":[],"mappings":"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"}

package/dist/bin/push.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=push.d.ts.map

package/dist/bin/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../../src/bin/push.ts"],"names":[],"mappings":""}

package/dist/bin/push.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { readLocales } from '../langReader.js';
+import { pushLocale } from '../apiClient.js';
+function loadDotEnv(cwd) {
+    const envPath = join(cwd, '.env');
+    if (!existsSync(envPath)) {
+        return;
+    }
+    const lines = readFileSync(envPath, 'utf8').split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1) {
+            continue;
+        }
+        const key = trimmed.slice(0, eqIndex).trim();
+        const rawValue = trimmed.slice(eqIndex + 1).trim();
+        const value = rawValue.replace(/^["']|["']$/g, '');
+        if (!(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+}
+function parseArgs(argv) {
+    const args = { flags: {}, positional: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const eqIdx = arg.indexOf('=');
+            const rawKey = eqIdx === -1 ? arg.slice(2) : arg.slice(2, eqIdx);
+            const key = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+            if (eqIdx !== -1) {
+                args.flags[key] = arg.slice(eqIdx + 1);
+            }
+            else if (argv[i + 1] && !argv[i + 1].startsWith('--')) {
+                args.flags[key] = argv[i + 1];
+                i++;
+            }
+            else {
+                args.flags[key] = true;
+            }
+        }
+        else {
+            args.positional.push(arg);
+        }
+    }
+    return args;
+}
+async function main() {
+    const cwd = process.cwd();
+    loadDotEnv(cwd);
+    const { flags } = parseArgs(process.argv.slice(2));
+    const url = flags['url'] ?? process.env['TRANSLATIONS_URL'];
+    const token = flags['token'] ?? process.env['TRANSLATIONS_TOKEN'];
+    const localesPath = resolve(cwd, flags['path'] ??
+        process.env['TRANSLATIONS_LOCALES_PATH'] ??
+        'src/locales');
+    const onlyLocale = flags['locale'] ?? null;
+    const overwrite = flags['overwrite'] !== 'false' && flags['overwrite'] !== false;
+    const dryRun = flags['dryRun'] === true || flags['dryRun'] === 'true';
+    const excludeFiles = typeof flags['exclude'] === 'string' ? flags['exclude'].split(',') : [];
+    if (!url || !token) {
+        console.error('Error: TRANSLATIONS_URL and TRANSLATIONS_TOKEN are required.');
+        console.error('Set them in .env or pass --url and --token flags.');
+        process.exit(1);
+    }
+    let locales = readLocales(localesPath, excludeFiles);
+    if (locales.length === 0) {
+        console.warn(`No locale files found in: ${localesPath}`);
+        process.exit(0);
+    }
+    if (onlyLocale) {
+        locales = locales.filter((l) => l.locale === onlyLocale);
+        if (locales.length === 0) {
+            console.warn(`Locale "${onlyLocale}" not found in: ${localesPath}`);
+            process.exit(0);
+        }
+    }
+    const prefix = dryRun ? '[DRY RUN] ' : '';
+    console.log(`${prefix}Pushing ${locales.length} locale(s): ${locales.map((l) => l.locale).join(', ')}`);
+    let totalNew = 0;
+    let totalUpdated = 0;
+    let totalKeys = 0;
+    for (const { locale, groups } of locales) {
+        const keyCount = Object.values(groups).reduce((sum, g) => sum + Object.keys(g).length, 0);
+        if (dryRun) {
+            console.log(`  ${locale}: ${keyCount} keys across ${Object.keys(groups).length} group(s).`);
+            continue;
+        }
+        try {
+            const data = await pushLocale({ url, token, locale, groups, overwrite });
+            totalNew += data.new ?? 0;
+            totalUpdated += data.updated ?? 0;
+            totalKeys += data.total ?? keyCount;
+            console.log(`  ✓ ${locale}: ${data.total ?? keyCount} keys — ${data.new ?? 0} new, ${data.updated ?? 0} updated.`);
+        }
+        catch (err) {
+            console.error(`  ✗ ${locale}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (!dryRun) {
+        console.log(`\nDone. Total: ${totalKeys} keys — ${totalNew} new, ${totalUpdated} updated.`);
+    }
+}
+main();
+//# sourceMappingURL=push.js.map

package/dist/bin/push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.js","sourceRoot":"","sources":["../../src/bin/push.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { readLocales, readFlatLayout, readGroupedLayout, detectLayout } from './langReader.js';
+export { pushLocale, fetchJson } from './apiClient.js';
+export { unflatten, writeGroupedLocale, writeFlatLocale } from './langWriter.js';
+export type { FlatKeys, LocaleGroups, LocaleLayout, LocaleData, PushLocaleParams, PushResult, PullOptions, PushOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9F,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAChF,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { readLocales, readFlatLayout, readGroupedLayout, detectLayout } from './langReader.js';
+export { pushLocale, fetchJson } from './apiClient.js';
+export { unflatten, writeGroupedLocale, writeFlatLocale } from './langWriter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9F,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/langReader.d.ts

@@ -0,0 +1,22 @@
+import type { LocaleData, LocaleLayout } from './types.js';
+/**
+ * Detect which locale layout the locales directory uses.
+ *
+ * Layout `flat`    — one file per locale: locales/en.json, locales/de.json
+ * Layout `grouped` — one subdirectory per locale: locales/en/auth.json, locales/de/auth.json
+ */
+export declare function detectLayout(localesPath: string): LocaleLayout | null;
+/**
+ * Read translations in flat layout (one JSON per locale).
+ * All keys are placed in the `_json` group to match Laravel's JSON translation convention.
+ */
+export declare function readFlatLayout(localesPath: string, excludeFiles?: string[]): LocaleData[];
+/**
+ * Read translations in grouped layout (subdirectory per locale, multiple group files).
+ */
+export declare function readGroupedLayout(localesPath: string, excludeFiles?: string[]): LocaleData[];
+/**
+ * Auto-detect layout and read all locales from the given path.
+ */
+export declare function readLocales(localesPath: string, excludeFiles?: string[]): LocaleData[];
+//# sourceMappingURL=langReader.d.ts.map

package/dist/langReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langReader.d.ts","sourceRoot":"","sources":["../src/langReader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAY,UAAU,EAAgB,YAAY,EAAE,MAAM,YAAY,CAAA;AAiClF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAmBrE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO,GAAG,UAAU,EAAE,CAwB7F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO,GAAG,UAAU,EAAE,CAiChG;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO,GAAG,UAAU,EAAE,CAU1F"}

package/dist/langReader.js

@@ -0,0 +1,118 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+/**
+ * Flatten a nested object into dot-notation keys.
+ * { auth: { login: 'Login' } } → { 'auth.login': 'Login' }
+ */
+function flatten(obj, prefix = '') {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            Object.assign(result, flatten(value, fullKey));
+        }
+        else {
+            result[fullKey] = String(value ?? '');
+        }
+    }
+    return result;
+}
+/**
+ * Read and parse a JSON file. Returns an empty object on failure.
+ */
+function readJson(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Detect which locale layout the locales directory uses.
+ *
+ * Layout `flat`    — one file per locale: locales/en.json, locales/de.json
+ * Layout `grouped` — one subdirectory per locale: locales/en/auth.json, locales/de/auth.json
+ */
+export function detectLayout(localesPath) {
+    if (!existsSync(localesPath)) {
+        return null;
+    }
+    const entries = readdirSync(localesPath, { withFileTypes: true });
+    const hasJsonFiles = entries.some((e) => e.isFile() && e.name.endsWith('.json'));
+    const hasDirs = entries.some((e) => e.isDirectory());
+    if (hasDirs) {
+        return 'grouped';
+    }
+    if (hasJsonFiles) {
+        return 'flat';
+    }
+    return null;
+}
+/**
+ * Read translations in flat layout (one JSON per locale).
+ * All keys are placed in the `_json` group to match Laravel's JSON translation convention.
+ */
+export function readFlatLayout(localesPath, excludeFiles = []) {
+    const entries = readdirSync(localesPath, { withFileTypes: true });
+    const result = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) {
+            continue;
+        }
+        if (excludeFiles.includes(entry.name)) {
+            continue;
+        }
+        const locale = basename(entry.name, '.json');
+        const filePath = join(localesPath, entry.name);
+        const parsed = readJson(filePath);
+        result.push({
+            locale,
+            groups: { _json: flatten(parsed) },
+        });
+    }
+    return result;
+}
+/**
+ * Read translations in grouped layout (subdirectory per locale, multiple group files).
+ */
+export function readGroupedLayout(localesPath, excludeFiles = []) {
+    const entries = readdirSync(localesPath, { withFileTypes: true });
+    const result = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const locale = entry.name;
+        const localePath = join(localesPath, locale);
+        const groups = {};
+        for (const file of readdirSync(localePath)) {
+            if (extname(file) !== '.json') {
+                continue;
+            }
+            if (excludeFiles.includes(file)) {
+                continue;
+            }
+            const groupName = basename(file, '.json');
+            const parsed = readJson(join(localePath, file));
+            groups[groupName] = flatten(parsed);
+        }
+        if (Object.keys(groups).length > 0) {
+            result.push({ locale, groups });
+        }
+    }
+    return result;
+}
+/**
+ * Auto-detect layout and read all locales from the given path.
+ */
+export function readLocales(localesPath, excludeFiles = []) {
+    const layout = detectLayout(localesPath);
+    if (!layout) {
+        return [];
+    }
+    return layout === 'grouped'
+        ? readGroupedLayout(localesPath, excludeFiles)
+        : readFlatLayout(localesPath, excludeFiles);
+}
+//# sourceMappingURL=langReader.js.map

package/dist/langReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langReader.js","sourceRoot":"","sources":["../src/langReader.ts"],"names":[],"mappings":"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"}

package/dist/langWriter.d.ts

@@ -0,0 +1,20 @@
+import type { FlatKeys, LocaleGroups } from './types.js';
+/**
+ * Restore dot-notation flat keys back to a nested object.
+ * { 'auth.login': 'Login' } → { auth: { login: 'Login' } }
+ */
+export declare function unflatten(flat: FlatKeys): Record<string, unknown>;
+/**
+ * Write translations for a single locale in grouped layout.
+ *
+ * Each group becomes its own file: locales/{locale}/{group}.json
+ * The special `_json` group is written as locales/{locale}.json (root-level).
+ */
+export declare function writeGroupedLocale(localesPath: string, locale: string, groups: LocaleGroups): string[];
+/**
+ * Write translations for a single locale in flat layout.
+ *
+ * All groups are merged into a single locales/{locale}.json file.
+ */
+export declare function writeFlatLocale(localesPath: string, locale: string, groups: LocaleGroups): string[];
+//# sourceMappingURL=langWriter.d.ts.map

package/dist/langWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langWriter.d.ts","sourceRoot":"","sources":["../src/langWriter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAExD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBjE;AAeD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,MAAM,EAAE,CAkBV;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,MAAM,EAAE,CAYV"}

package/dist/langWriter.js

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+/**
+ * Restore dot-notation flat keys back to a nested object.
+ * { 'auth.login': 'Login' } → { auth: { login: 'Login' } }
+ */
+export function unflatten(flat) {
+    const result = {};
+    for (const [dotKey, value] of Object.entries(flat)) {
+        const parts = dotKey.split('.');
+        let cursor = result;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i];
+            if (typeof cursor[part] !== 'object' || cursor[part] === null) {
+                cursor[part] = {};
+            }
+            cursor = cursor[part];
+        }
+        cursor[parts[parts.length - 1]] = value;
+    }
+    return result;
+}
+/**
+ * Write a JSON file, creating parent directories as needed.
+ */
+function writeJson(filePath, data) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+/**
+ * Write translations for a single locale in grouped layout.
+ *
+ * Each group becomes its own file: locales/{locale}/{group}.json
+ * The special `_json` group is written as locales/{locale}.json (root-level).
+ */
+export function writeGroupedLocale(localesPath, locale, groups) {
+    const written = [];
+    for (const [groupName, flatKeys] of Object.entries(groups)) {
+        const nested = unflatten(flatKeys);
+        if (groupName === '_json') {
+            const filePath = join(localesPath, `${locale}.json`);
+            writeJson(filePath, nested);
+            written.push(filePath);
+        }
+        else {
+            const filePath = join(localesPath, locale, `${groupName}.json`);
+            writeJson(filePath, nested);
+            written.push(filePath);
+        }
+    }
+    return written;
+}
+/**
+ * Write translations for a single locale in flat layout.
+ *
+ * All groups are merged into a single locales/{locale}.json file.
+ */
+export function writeFlatLocale(localesPath, locale, groups) {
+    const merged = {};
+    for (const flatKeys of Object.values(groups)) {
+        Object.assign(merged, flatKeys);
+    }
+    const nested = unflatten(merged);
+    const filePath = join(localesPath, `${locale}.json`);
+    writeJson(filePath, nested);
+    return [filePath];
+}
+//# sourceMappingURL=langWriter.js.map

package/dist/langWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langWriter.js","sourceRoot":"","sources":["../src/langWriter.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+/** Flat map of dot-notation keys to string values. */
+export type FlatKeys = Record<string, string>;
+/** A locale's translations grouped by file/group name. */
+export type LocaleGroups = Record<string, FlatKeys>;
+/** Detected directory layout of the locales folder. */
+export type LocaleLayout = 'flat' | 'grouped';
+/** A single locale's data as returned by readLocales(). */
+export interface LocaleData {
+    locale: string;
+    groups: LocaleGroups;
+}
+/** Parameters for pushLocale(). */
+export interface PushLocaleParams {
+    /** Base URL of the Translation Manager (e.g. https://translations.example.com). */
+    url: string;
+    /** API bearer token. */
+    token: string;
+    /** Locale code, e.g. 'en', 'de'. */
+    locale: string;
+    /** Translation groups to push. */
+    groups: LocaleGroups;
+    /** When true, existing keys will be overwritten. Defaults to true. */
+    overwrite?: boolean;
+}
+/** Response from the Translation Manager import endpoint. */
+export interface PushResult {
+    new: number;
+    updated: number;
+    total: number;
+}
+/** Parameters for pullLocale() / the pull CLI. */
+export interface PullOptions {
+    /** Base URL of the Translation Manager. */
+    url: string;
+    /** API bearer token. */
+    token: string;
+    /** Absolute path to the locales directory. */
+    localesPath: string;
+    /** Restrict pull to a single locale code. */
+    locale?: string | null;
+    /** Force layout instead of auto-detecting. */
+    layout?: LocaleLayout | null;
+    /** Dry-run: report what would be written without writing. */
+    dryRun?: boolean;
+}
+/** Parameters for pushAll() / the push CLI. */
+export interface PushOptions {
+    /** Base URL of the Translation Manager. */
+    url: string;
+    /** API bearer token. */
+    token: string;
+    /** Absolute path to the locales directory. */
+    localesPath: string;
+    /** Restrict push to a single locale code. */
+    locale?: string | null;
+    /** When true, existing keys will be overwritten. Defaults to true. */
+    overwrite?: boolean;
+    /** Dry-run: report what would be sent without sending. */
+    dryRun?: boolean;
+    /** JSON filenames to exclude from reading. */
+    excludeFiles?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE7C,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;AAEnD,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,CAAA;AAE7C,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,YAAY,CAAA;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAA;IACX,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,kCAAkC;IAClC,MAAM,EAAE,YAAY,CAAA;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAA;IACX,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAC5B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAA;IACX,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@metasyncsite/translations-client-ts",
+  "version": "1.0.0",
+  "description": "Push/pull i18n translations (Vue, React, Next.js, etc.) to the MetaSyncSite Translation Manager — TypeScript edition",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "translations-push": "./dist/bin/push.js",
+    "translations-pull": "./dist/bin/pull.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "i18n",
+    "vue-i18n",
+    "translations",
+    "localization",
+    "typescript"
+  ]
+}