localingos 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# Localingos CLI
+
+Sync translations between your codebase and [Localingos](https://localingos.com) with a single command.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g localingos
+
+# Or use with npx (no install needed)
+npx localingos init
+npx localingos sync
+```
+
+## Setup
+
+### 1. Create an API Key
+
+Go to [localingos.com](https://localingos.com) → **Settings** → **API Keys** → **Create API Key**.
+
+### 2. Initialize your project
+
+```bash
+localingos init
+```
+
+This will interactively create a `.localingos.json` config file:
+
+```json
+{
+  "apiUrl": "https://api.localingos.com",
+  "apiKey": "your-api-key",
+  "familyId": "your-family-id",
+  "sourceLocale": "en-US",
+  "format": "json-nested",
+  "sourceFile": "./src/i18n/en-US.json",
+  "outputDir": "./src/i18n",
+  "outputPattern": "{locale}.json"
+}
+```
+
+> ⚠️ Add `.localingos.json` to your `.gitignore` — it contains your API key.
+
+### 3. Sync translations
+
+```bash
+localingos sync
+```
+
+This single command will:
+1. **Extract** all translatable strings from your source file
+2. **Push** them to Localingos (creates new keys, updates changed ones)
+3. **Pull** all available translations
+4. **Write** translation files per locale (e.g., `es-ES.json`, `fr-FR.json`)
+
+## Commands
+
+### `localingos init`
+
+Interactive setup wizard. Creates `.localingos.json` in the current directory.
+
+### `localingos sync`
+
+The main command. Pushes source strings and pulls translations in one call.
+
+```bash
+localingos sync              # Full sync
+localingos sync --dry-run    # Preview what would be synced
+```
+
+### `localingos push`
+
+Push source strings only (no pull).
+
+```bash
+localingos push              # Push source strings
+localingos push --dry-run    # Preview what would be pushed
+```
+
+### `localingos pull`
+
+Pull translations only (no push).
+
+```bash
+localingos pull              # Pull and write translation files
+```
+
+### Common Options
+
+| Option | Description |
+|--------|-------------|
+| `-c, --config <path>` | Path to config file (default: `.localingos.json`) |
+| `--dry-run` | Preview without making API calls (sync/push) |
+| `-V, --version` | Show version |
+| `-h, --help` | Show help |
+
+## Supported Formats
+
+| Format | Description | Example |
+|--------|-------------|---------|
+| `json-nested` | Nested JSON objects | `{ "welcome": { "title": "Hello" } }` |
+| `json-flat` | Flat key-value JSON | `{ "welcome.title": "Hello" }` |
+
+More formats (YAML, properties, XLIFF) coming soon.
+
+## CI/CD Integration
+
+Add to your build pipeline to keep translations in sync:
+
+```yaml
+# GitHub Actions example
+- name: Sync translations
+  run: npx localingos sync
+  env:
+    # Store API key as a secret, override config
+    LOCALINGOS_API_KEY: ${{ secrets.LOCALINGOS_API_KEY }}
+```
+
+## How It Works
+
+```
+Your codebase                    Localingos
+┌──────────────┐                ┌──────────────┐
+│ en-US.json   │ ──── push ──→ │  Process &    │
+│ (source)     │                │  Translate    │
+│              │ ←── pull ──── │  (AI-powered) │
+│ es-ES.json   │                │              │
+│ fr-FR.json   │                │              │
+│ de-DE.json   │                │              │
+└──────────────┘                └──────────────┘
+```
+
+The `sync` command combines push + pull into a single API call for efficiency. New/changed strings are registered for translation processing. Already-translated strings are returned immediately.

package/bin/localingos.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { initCommand } from '../src/commands/init.js';
+import { syncCommand } from '../src/commands/sync.js';
+import { pullCommand } from '../src/commands/pull.js';
+import { pushCommand } from '../src/commands/push.js';
+
+program
+    .name('localingos')
+    .description('CLI tool to sync translations with Localingos')
+    .version('0.1.0');
+
+program
+    .command('init')
+    .description('Initialize a new .localingos.json config file interactively')
+    .action(initCommand);
+
+program
+    .command('sync')
+    .description('Extract source strings, push to Localingos, and pull all available translations')
+    .option('-c, --config <path>', 'Path to config file', '.localingos.json')
+    .option('--dry-run', 'Show what would be synced without making API calls')
+    .action(syncCommand);
+
+program
+    .command('pull')
+    .description('Pull all available translations from Localingos and write locale files')
+    .option('-c, --config <path>', 'Path to config file', '.localingos.json')
+    .action(pullCommand);
+
+program
+    .command('push')
+    .description('Extract and push source strings to Localingos without pulling translations')
+    .option('-c, --config <path>', 'Path to config file', '.localingos.json')
+    .option('--dry-run', 'Show what would be pushed without making API calls')
+    .action(pushCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "localingos",
+  "version": "0.1.0",
+  "description": "CLI tool to sync translations with Localingos",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "localingos": "./bin/localingos.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "i18n",
+    "translation",
+    "localization",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "inquirer": "^9.2.0",
+    "yaml": "^2.4.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,71 @@
+import chalk from 'chalk';
+
+export class LocalingosApi {
+    constructor(apiUrl, apiKey) {
+        this.apiUrl = apiUrl.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+    }
+
+    async sync(familyId, translatables) {
+        return this._post('/sync', {
+            familyId,
+            translatables
+        });
+    }
+
+    async getTranslatables(familyId) {
+        return this._get(`/translatable/${familyId}`);
+    }
+
+    async getTranslations(familyId) {
+        return this._get(`/translation/${familyId}`);
+    }
+
+    async postTranslatables(familyId, translatableList) {
+        return this._post('/translatable', {
+            familyId,
+            translatableList
+        });
+    }
+
+    async _get(path) {
+        const url = `${this.apiUrl}${path}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'X-API-Key': this.apiKey,
+                'Accept': 'application/json'
+            }
+        });
+
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`API GET ${path} failed (${response.status}): ${body}`);
+        }
+
+        return response.json();
+    }
+
+    async _post(path, body) {
+        const url = `${this.apiUrl}${path}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'X-API-Key': this.apiKey,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json'
+            },
+            body: JSON.stringify(body)
+        });
+
+        if (!response.ok) {
+            const responseBody = await response.text().catch(() => '');
+            throw new Error(`API POST ${path} failed (${response.status}): ${responseBody}`);
+        }
+
+        // Some endpoints return 200 with no body
+        const text = await response.text();
+        if (!text) return {};
+        return JSON.parse(text);
+    }
+}

package/src/commands/init.js

@@ -0,0 +1,114 @@
+import { createRequire } from 'module';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { saveConfig } from '../config.js';
+import { getSupportedFormats } from '../formats/index.js';
+
+// Use createRequire for inquirer since it needs CJS-style dynamic import
+const require = createRequire(import.meta.url);
+
+export async function initCommand() {
+    const inquirer = (await import('inquirer')).default;
+    const configPath = path.resolve('.localingos.json');
+
+    if (fs.existsSync(configPath)) {
+        const { overwrite } = await inquirer.prompt([{
+            type: 'confirm',
+            name: 'overwrite',
+            message: '.localingos.json already exists. Overwrite?',
+            default: false
+        }]);
+        if (!overwrite) {
+            console.log(chalk.yellow('Aborted.'));
+            return;
+        }
+    }
+
+    console.log(chalk.blue('\n🌍 Localingos CLI Setup\n'));
+
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'apiUrl',
+            message: 'API URL:',
+            default: 'https://api.localingos.com'
+        },
+        {
+            type: 'input',
+            name: 'apiKey',
+            message: 'API Key (from localingos.com → Settings → API Keys):',
+            validate: (input) => input.trim().length > 0 || 'API key is required'
+        },
+        {
+            type: 'input',
+            name: 'familyId',
+            message: 'Family ID (your project/family in Localingos):',
+            validate: (input) => input.trim().length > 0 || 'Family ID is required'
+        },
+        {
+            type: 'input',
+            name: 'sourceLocale',
+            message: 'Source locale code (e.g. en-US, en-GB):',
+            default: 'en-US'
+        },
+        {
+            type: 'list',
+            name: 'format',
+            message: 'Source file format:',
+            choices: getSupportedFormats()
+        },
+        {
+            type: 'input',
+            name: 'sourceFile',
+            message: 'Path to source locale file:',
+            default: './src/i18n/en-US.json'
+        },
+        {
+            type: 'input',
+            name: 'outputDir',
+            message: 'Output directory for translated files:',
+            default: './src/i18n'
+        },
+        {
+            type: 'input',
+            name: 'outputPattern',
+            message: 'Output file pattern ({locale} will be replaced):',
+            default: '{locale}.json'
+        }
+    ]);
+
+    const config = {
+        apiUrl: answers.apiUrl.trim(),
+        apiKey: answers.apiKey.trim(),
+        familyId: answers.familyId.trim(),
+        sourceLocale: answers.sourceLocale.trim(),
+        format: answers.format,
+        sourceFile: answers.sourceFile.trim(),
+        outputDir: answers.outputDir.trim(),
+        outputPattern: answers.outputPattern.trim()
+    };
+
+    const savedPath = saveConfig(config);
+    console.log(chalk.green(`\n✅ Config saved to ${savedPath}`));
+
+    // Check if .gitignore exists and suggest adding .localingos.json
+    const gitignorePath = path.resolve('.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+        const gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
+        if (!gitignoreContent.includes('.localingos.json')) {
+            const { addGitignore } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'addGitignore',
+                message: 'Add .localingos.json to .gitignore? (recommended — contains your API key)',
+                default: true
+            }]);
+            if (addGitignore) {
+                fs.appendFileSync(gitignorePath, '\n# Localingos CLI config (contains API key)\n.localingos.json\n');
+                console.log(chalk.green('✅ Added .localingos.json to .gitignore'));
+            }
+        }
+    }
+
+    console.log(chalk.blue('\nRun "localingos sync" to push source strings and pull translations.\n'));
+}

package/src/commands/pull.js

@@ -0,0 +1,37 @@
+import chalk from 'chalk';
+import path from 'path';
+import { loadConfig } from '../config.js';
+import { LocalingosApi } from '../api.js';
+import { getFormatter } from '../formats/index.js';
+
+export async function pullCommand(options) {
+    const config = loadConfig(options.config);
+    const formatter = getFormatter(config.format);
+
+    console.log(chalk.blue(`⬇️  Pulling translations for family ${config.familyId}...`));
+    const api = new LocalingosApi(config.apiUrl, config.apiKey);
+
+    let translations;
+    try {
+        translations = await api.getTranslations(config.familyId);
+    } catch (e) {
+        console.error(chalk.red(`\nPull failed: ${e.message}`));
+        process.exit(1);
+    }
+
+    console.log(chalk.green(`   ✅ ${translations.length} translations received`));
+
+    if (translations.length > 0) {
+        const outputDir = path.resolve(config.outputDir);
+        console.log(chalk.blue(`\n📝 Writing translation files to ${outputDir}`));
+
+        const writtenFiles = formatter.write(translations, outputDir, config.outputPattern);
+        for (const file of writtenFiles) {
+            console.log(chalk.green(`   ✅ ${file}`));
+        }
+    } else {
+        console.log(chalk.yellow('\n   No translations available yet.'));
+    }
+
+    console.log(chalk.blue('\n✨ Pull complete!\n'));
+}

package/src/commands/push.js

@@ -0,0 +1,55 @@
+import chalk from 'chalk';
+import path from 'path';
+import { loadConfig } from '../config.js';
+import { LocalingosApi } from '../api.js';
+import { getFormatter } from '../formats/index.js';
+
+export async function pushCommand(options) {
+    const config = loadConfig(options.config);
+    const formatter = getFormatter(config.format);
+
+    // 1. Extract source strings
+    const sourceFilePath = path.resolve(config.sourceFile);
+    console.log(chalk.blue(`📖 Extracting source strings from ${sourceFilePath}`));
+
+    let entries;
+    try {
+        entries = formatter.extract(sourceFilePath);
+    } catch (e) {
+        console.error(chalk.red(`Failed to read source file: ${e.message}`));
+        process.exit(1);
+    }
+
+    console.log(chalk.gray(`   Found ${entries.length} translatable strings`));
+
+    const translatables = entries.map(entry => ({
+        id: entry.id,
+        locale: config.sourceLocale,
+        text: entry.text,
+        description: entry.description || null,
+        forceReTranslate: false
+    }));
+
+    if (options.dryRun) {
+        console.log(chalk.yellow('\n🔍 Dry run — would push these keys:'));
+        for (const t of translatables) {
+            console.log(chalk.gray(`   ${t.id}: "${t.text.substring(0, 60)}${t.text.length > 60 ? '...' : ''}"`));
+        }
+        console.log(chalk.yellow(`\nTotal: ${translatables.length} keys. No API calls made.`));
+        return;
+    }
+
+    // 2. Push to API
+    console.log(chalk.blue(`\n⬆️  Pushing ${translatables.length} translatables to family ${config.familyId}...`));
+    const api = new LocalingosApi(config.apiUrl, config.apiKey);
+
+    try {
+        await api.postTranslatables(config.familyId, translatables);
+    } catch (e) {
+        console.error(chalk.red(`\nPush failed: ${e.message}`));
+        process.exit(1);
+    }
+
+    console.log(chalk.green(`   ✅ ${translatables.length} source strings pushed`));
+    console.log(chalk.blue('\n✨ Push complete! Translations will be processed shortly.\n'));
+}

package/src/commands/sync.js

@@ -0,0 +1,75 @@
+import chalk from 'chalk';
+import path from 'path';
+import { loadConfig } from '../config.js';
+import { LocalingosApi } from '../api.js';
+import { getFormatter } from '../formats/index.js';
+
+export async function syncCommand(options) {
+    const config = loadConfig(options.config);
+    const formatter = getFormatter(config.format);
+
+    // 1. Extract source strings
+    const sourceFilePath = path.resolve(config.sourceFile);
+    console.log(chalk.blue(`📖 Extracting source strings from ${sourceFilePath}`));
+
+    let entries;
+    try {
+        entries = formatter.extract(sourceFilePath);
+    } catch (e) {
+        console.error(chalk.red(`Failed to read source file: ${e.message}`));
+        process.exit(1);
+    }
+
+    console.log(chalk.gray(`   Found ${entries.length} translatable strings`));
+
+    // Build translatables payload
+    const translatables = entries.map(entry => ({
+        id: entry.id,
+        locale: config.sourceLocale,
+        text: entry.text,
+        description: entry.description || null,
+        forceReTranslate: false
+    }));
+
+    if (options.dryRun) {
+        console.log(chalk.yellow('\n🔍 Dry run — would sync these keys:'));
+        for (const t of translatables) {
+            console.log(chalk.gray(`   ${t.id}: "${t.text.substring(0, 60)}${t.text.length > 60 ? '...' : ''}"`));
+        }
+        console.log(chalk.yellow(`\nTotal: ${translatables.length} keys. No API calls made.`));
+        return;
+    }
+
+    // 2. Call /sync endpoint (push + pull in one call)
+    console.log(chalk.blue(`\n🔄 Syncing with Localingos (family: ${config.familyId})...`));
+    const api = new LocalingosApi(config.apiUrl, config.apiKey);
+
+    let result;
+    try {
+        result = await api.sync(config.familyId, translatables);
+    } catch (e) {
+        console.error(chalk.red(`\nSync failed: ${e.message}`));
+        process.exit(1);
+    }
+
+    const { translations, pending } = result;
+    console.log(chalk.green(`   ✅ ${translations.length} translations available`));
+    if (pending.length > 0) {
+        console.log(chalk.yellow(`   ⏳ ${pending.length} keys pending translation: ${pending.slice(0, 5).join(', ')}${pending.length > 5 ? '...' : ''}`));
+    }
+
+    // 3. Write translation files
+    if (translations.length > 0) {
+        const outputDir = path.resolve(config.outputDir);
+        console.log(chalk.blue(`\n📝 Writing translation files to ${outputDir}`));
+
+        const writtenFiles = formatter.write(translations, outputDir, config.outputPattern);
+        for (const file of writtenFiles) {
+            console.log(chalk.green(`   ✅ ${file}`));
+        }
+    } else {
+        console.log(chalk.yellow('\n   No translations available yet. Run "localingos sync" again later.'));
+    }
+
+    console.log(chalk.blue('\n✨ Sync complete!\n'));
+}

package/src/config.js

@@ -0,0 +1,39 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+
+const DEFAULT_CONFIG_FILE = '.localingos.json';
+
+export function loadConfig(configPath) {
+    const resolvedPath = path.resolve(configPath || DEFAULT_CONFIG_FILE);
+
+    if (!fs.existsSync(resolvedPath)) {
+        console.error(chalk.red(`Config file not found: ${resolvedPath}`));
+        console.error(chalk.yellow('Run "localingos init" to create one.'));
+        process.exit(1);
+    }
+
+    try {
+        const raw = fs.readFileSync(resolvedPath, 'utf-8');
+        const config = JSON.parse(raw);
+
+        // Validate required fields
+        const required = ['apiKey', 'familyId', 'apiUrl', 'sourceLocale', 'format', 'sourceFile', 'outputDir'];
+        const missing = required.filter(field => !config[field]);
+        if (missing.length > 0) {
+            console.error(chalk.red(`Missing required config fields: ${missing.join(', ')}`));
+            process.exit(1);
+        }
+
+        return config;
+    } catch (e) {
+        console.error(chalk.red(`Failed to parse config file: ${e.message}`));
+        process.exit(1);
+    }
+}
+
+export function saveConfig(config, configPath) {
+    const resolvedPath = path.resolve(configPath || DEFAULT_CONFIG_FILE);
+    fs.writeFileSync(resolvedPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    return resolvedPath;
+}

package/src/formats/index.js

@@ -0,0 +1,20 @@
+import * as jsonNested from './json-nested.js';
+import * as jsonFlat from './json-flat.js';
+
+const formatters = {
+    'json-nested': jsonNested,
+    'json-flat': jsonFlat
+};
+
+export function getFormatter(format) {
+    const formatter = formatters[format];
+    if (!formatter) {
+        const supported = Object.keys(formatters).join(', ');
+        throw new Error(`Unsupported format "${format}". Supported: ${supported}`);
+    }
+    return formatter;
+}
+
+export function getSupportedFormats() {
+    return Object.keys(formatters);
+}

package/src/formats/json-flat.js

@@ -0,0 +1,33 @@
+import fs from 'fs';
+import path from 'path';
+
+export function extract(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const json = JSON.parse(raw);
+    return Object.entries(json).map(([key, value]) => ({
+        id: key,
+        text: String(value)
+    }));
+}
+
+export function write(translations, outputDir, outputPattern) {
+    const byLocale = {};
+    for (const t of translations) {
+        if (!byLocale[t.locale]) {
+            byLocale[t.locale] = {};
+        }
+        byLocale[t.locale][t.foreignId] = t.text;
+    }
+
+    const writtenFiles = [];
+    for (const [locale, entries] of Object.entries(byLocale)) {
+        const fileName = (outputPattern || '{locale}.json').replace('{locale}', locale);
+        const filePath = path.join(outputDir, fileName);
+
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(entries, null, 2) + '\n', 'utf-8');
+        writtenFiles.push(filePath);
+    }
+
+    return writtenFiles;
+}

package/src/formats/json-nested.js

@@ -0,0 +1,69 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Flatten a nested JSON object into dot-separated keys.
+ * { "welcome": { "title": "Hello" } } → [{ id: "welcome.title", text: "Hello" }]
+ */
+function flatten(obj, prefix = '') {
+    const entries = [];
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            entries.push(...flatten(value, fullKey));
+        } else {
+            entries.push({ id: fullKey, text: String(value) });
+        }
+    }
+    return entries;
+}
+
+/**
+ * Unflatten dot-separated keys back into nested object.
+ * [{ foreignId: "welcome.title", text: "Hello" }] → { "welcome": { "title": "Hello" } }
+ */
+function unflatten(translations) {
+    const result = {};
+    for (const { foreignId, text } of translations) {
+        const keys = foreignId.split('.');
+        let current = result;
+        for (let i = 0; i < keys.length - 1; i++) {
+            if (!current[keys[i]] || typeof current[keys[i]] !== 'object') {
+                current[keys[i]] = {};
+            }
+            current = current[keys[i]];
+        }
+        current[keys[keys.length - 1]] = text;
+    }
+    return result;
+}
+
+export function extract(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const json = JSON.parse(raw);
+    return flatten(json);
+}
+
+export function write(translations, outputDir, outputPattern) {
+    // Group translations by locale
+    const byLocale = {};
+    for (const t of translations) {
+        if (!byLocale[t.locale]) {
+            byLocale[t.locale] = [];
+        }
+        byLocale[t.locale].push(t);
+    }
+
+    const writtenFiles = [];
+    for (const [locale, localeTranslations] of Object.entries(byLocale)) {
+        const nested = unflatten(localeTranslations);
+        const fileName = (outputPattern || '{locale}.json').replace('{locale}', locale);
+        const filePath = path.join(outputDir, fileName);
+
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(nested, null, 2) + '\n', 'utf-8');
+        writtenFiles.push(filePath);
+    }
+
+    return writtenFiles;
+}