@localheroai/cli 0.0.1

package/src/commands/translate.js

@@ -0,0 +1,282 @@
+import chalk from 'chalk';
+import { configService } from '../utils/config.js';
+import { findTranslationFiles } from '../utils/files.js';
+import { createTranslationJob, checkJobStatus } from '../api/translations.js';
+import { updateTranslationFile } from '../utils/translation-updater.js';
+import path from 'path';
+import { checkAuth } from '../utils/auth.js';
+import { autoCommitChanges } from '../utils/github.js';
+
+const DEFAULT_LOCALE_REGEX = '.*?([a-z]{2}(?:-[A-Z]{2})?)\\.(?:yml|yaml|json)$';
+const MAX_RETRY_ATTEMPTS = 3;
+const BATCH_SIZE = 100;
+
+function validateConfig(config) {
+    const required = ['projectId', 'sourceLocale', 'outputLocales', 'translationFiles'];
+    const missing = required.filter(key => !config[key]);
+
+    if (missing.length) {
+        throw new Error(`Missing required config: ${missing.join(', ')}. Run 'npx localhero init' to set up your project.`);
+    }
+
+    if (!Array.isArray(config.outputLocales) || config.outputLocales.length === 0) {
+        throw new Error('outputLocales must be an array with at least one locale');
+    }
+
+    if (config.outputLocales.length > 10) {
+        throw new Error('Maximum 10 target languages allowed per request');
+    }
+
+    if (!config.translationFiles.paths || !Array.isArray(config.translationFiles.paths)) {
+        throw new Error('translationFiles.paths must be an array of paths');
+    }
+}
+
+function findMissingTranslations(sourceKeys, targetKeys) {
+    const missing = {};
+    for (const [key, value] of Object.entries(sourceKeys)) {
+        if (!targetKeys[key]) {
+            missing[key] = value;
+        }
+    }
+    return missing;
+}
+
+async function retryWithBackoff(operation, attempt = 1) {
+    try {
+        return await operation();
+    } catch (error) {
+        if (attempt >= MAX_RETRY_ATTEMPTS) throw error;
+
+        const backoffTime = Math.min(1000 * Math.pow(2, attempt), 30000);
+        const jitter = Math.random() * 1000;
+        const waitTime = backoffTime + jitter;
+
+        console.log(chalk.yellow(`⚠️  API error, retrying in ${Math.round(waitTime / 1000)}s (attempt ${attempt}/${MAX_RETRY_ATTEMPTS})`));
+        console.log(error);
+        await new Promise(resolve => setTimeout(resolve, waitTime));
+
+        return retryWithBackoff(operation, attempt + 1);
+    }
+}
+
+function batchKeysWithMissing(sourceFiles, missingByLocale, batchSize = BATCH_SIZE) {
+    const batches = [];
+    const sourceFileEntries = new Map();
+
+    for (const [locale, localeData] of Object.entries(missingByLocale)) {
+        const sourceFile = sourceFiles.find(f => f.path === localeData.path);
+        if (!sourceFile) continue;
+
+        if (!sourceFileEntries.has(sourceFile.path)) {
+            sourceFileEntries.set(sourceFile.path, {
+                path: path.relative(process.cwd(), sourceFile.path),
+                keys: {},
+                locales: new Set()
+            });
+        }
+
+        const entry = sourceFileEntries.get(sourceFile.path);
+        entry.keys = { ...entry.keys, ...localeData.keys };
+        entry.locales.add(locale);
+    }
+
+    for (const entry of sourceFileEntries.values()) {
+        const keys = entry.keys;
+        const keyEntries = Object.entries(keys);
+        for (let i = 0; i < keyEntries.length; i += batchSize) {
+            const batchKeys = Object.fromEntries(keyEntries.slice(i, i + batchSize));
+            batches.push([{
+                path: entry.path,
+                content: Buffer.from(JSON.stringify({ keys: batchKeys })).toString('base64')
+            }]);
+        }
+    }
+
+    return batches;
+}
+
+export async function translate(options = {}) {
+    const { verbose = false, commit = false } = options;
+    const log = verbose ? console.log : () => { };
+
+    try {
+        const config = await configService.getValidProjectConfig();
+        const isAuthenticated = await checkAuth();
+
+        if (!isAuthenticated) {
+            throw new Error('No API key found. Run `npx localhero login` or set LOCALHERO_API_KEY');
+        }
+
+        console.log(chalk.blue('ℹ️  Loading configuration from localhero.json'));
+
+        const { translationFiles } = config;
+        const fileLocaleRegex = DEFAULT_LOCALE_REGEX;
+        let allFiles = [];
+
+        for (const translationPath of translationFiles.paths) {
+            const filesInPath = await findTranslationFiles(translationPath, fileLocaleRegex);
+            allFiles = allFiles.concat(filesInPath);
+        }
+
+        if (!allFiles.length) {
+            console.error(chalk.red('❌ No translation files found'));
+            process.exit(1);
+        }
+
+        const sourceFiles = allFiles.filter(f => f.locale === config.sourceLocale);
+        const targetFiles = allFiles.filter(f => config.outputLocales.includes(f.locale));
+
+        if (!sourceFiles.length) {
+            console.error(chalk.red(`❌ No source files found for locale ${config.sourceLocale}`));
+            process.exit(1);
+        }
+
+        log(chalk.blue(`✓ Found ${allFiles.length} translation files`));
+        log(chalk.blue(`ℹ️  Analyzing target translations...`));
+
+        const missingByLocale = {};
+        for (const sourceFile of sourceFiles) {
+            const sourceContent = JSON.parse(Buffer.from(sourceFile.content, 'base64').toString());
+
+            for (const targetLocale of config.outputLocales) {
+                const targetFile = targetFiles.find(f => f.locale === targetLocale);
+                const targetContent = targetFile ?
+                    JSON.parse(Buffer.from(targetFile.content, 'base64').toString()) :
+                    { keys: {} };
+
+                const missing = findMissingTranslations(sourceContent.keys, targetContent.keys);
+                const missingCount = Object.keys(missing).length;
+
+                if (missingCount > 0) {
+                    if (!missingByLocale[targetLocale]) {
+                        missingByLocale[targetLocale] = {
+                            keys: {},
+                            path: sourceFile.path
+                        };
+                    }
+                    missingByLocale[targetLocale].keys = {
+                        ...missingByLocale[targetLocale].keys,
+                        ...missing
+                    };
+                    console.log(chalk.blue(`  ${targetLocale} (${path.basename(sourceFile.path)}): ${missingCount} missing keys`));
+                }
+            }
+        }
+
+        if (Object.keys(missingByLocale).length === 0) {
+            console.log(chalk.green('✓ All translations are up to date!'));
+            return;
+        }
+
+        const updatedFiles = new Set();
+        const batches = batchKeysWithMissing(sourceFiles, missingByLocale);
+        let totalKeysProcessed = 0;
+        let totalErrors = 0;
+        const processedKeys = new Set();
+        let hasShownUpdateMessage = false;
+
+        for (const [batchIndex, batch] of batches.entries()) {
+            log(chalk.blue(`\nProcessing batch ${batchIndex + 1}/${batches.length}...`));
+
+            try {
+                const { jobs } = await retryWithBackoff(() =>
+                    createTranslationJob({
+                        sourceFiles: batch,
+                        targetLocales: config.outputLocales,
+                        projectId: config.projectId
+                    })
+                );
+                const jobStatuses = new Map();
+                let allCompleted = false;
+
+                while (!allCompleted) {
+                    allCompleted = true;
+                    let totalProgress = 0;
+
+                    for (const job of jobs) {
+                        const status = await retryWithBackoff(() => checkJobStatus(job.id, true));
+                        jobStatuses.set(job.id, status);
+
+                        if (status.status === 'processing') {
+                            allCompleted = false;
+                        }
+                        totalProgress += status.progress.percentage;
+                    }
+
+                    const averageProgress = Math.round(totalProgress / jobs.length);
+                    const bar = '='.repeat(averageProgress / 2) + ' '.repeat(50 - averageProgress / 2);
+
+                    process.stdout.write(`\r⧗ Translating... [${bar}] ${averageProgress}%`);
+
+                    await new Promise(resolve => setTimeout(resolve, 2000));
+                }
+
+                for (const job of jobs) {
+                    const status = jobStatuses.get(job.id);
+                    if (status.status === 'completed' && status.translations) {
+                        if (!hasShownUpdateMessage) {
+                            console.log(chalk.blue('\nℹ️  Updating translation files...'));
+                            hasShownUpdateMessage = true;
+                        }
+
+                        const translations = status.translations.translations;
+                        const targetLocale = status.language.code;
+                        const uniqueKey = `${targetLocale}:${Object.keys(translations).sort().join(',')}`;
+
+                        if (processedKeys.has(uniqueKey)) {
+                            continue;
+                        }
+                        processedKeys.add(uniqueKey);
+
+                        const targetFile = targetFiles.find(f => f.locale === targetLocale)?.path ||
+                            path.join(config.translationPath, `${targetLocale}.yml`);
+
+                        try {
+                            const updatedKeys = await updateTranslationFile(
+                                targetFile,
+                                translations,
+                                targetLocale
+                            );
+
+                            updatedFiles.add(targetFile);
+                            totalKeysProcessed += updatedKeys.length;
+
+                            if (verbose) {
+                                console.log(chalk.blue(`  Updated ${targetFile}`));
+                                updatedKeys.forEach(key => console.log(chalk.gray(`  - Added: ${key}`)));
+                            } else {
+                                console.log(chalk.blue(`  Updated ${path.basename(targetFile)}`));
+                            }
+                        } catch (error) {
+                            console.error(chalk.yellow(`⚠️  Failed to update ${targetFile}: ${error.message}`));
+                            totalErrors++;
+                        }
+                    }
+                }
+            } catch (error) {
+                totalErrors++;
+                console.error(chalk.red(`❌ Batch ${batchIndex + 1} failed: ${error.message}`));
+                console.log(error);
+
+            }
+        }
+
+        if (totalErrors > 0) {
+            console.error(chalk.red(`\n❌ Translation completed with ${totalErrors} failed batches`));
+            process.exit(1);
+        }
+
+        console.log(chalk.green('\n✓ Translations complete!') + ` Updated ${totalKeysProcessed} keys in ${config.outputLocales.length} languages`);
+
+        if (commit || process.env.GITHUB_ACTIONS === 'true') {
+            const translationPaths = Array.from(updatedFiles).join(' ');
+            if (translationPaths) {
+                autoCommitChanges(translationPaths);
+            }
+        }
+    } catch (error) {
+        console.error(chalk.red(`❌ ${error.message}`));
+        process.exit(1);
+    }
+} 

package/src/utils/auth.js

@@ -0,0 +1,23 @@
+import { configService } from './config.js';
+
+export async function getApiKey() {
+    const envKey = process.env.LOCALHERO_API_KEY;
+    if (envKey) {
+        return envKey;
+    }
+
+    const config = await configService.getAuthConfig();
+    return config?.api_key;
+}
+
+export async function checkAuth() {
+    try {
+        const apiKey = await getApiKey();
+        const isValidFormat = typeof apiKey === 'string' &&
+            /^tk_[a-f0-9]+$/.test(apiKey);
+
+        return isValidFormat;
+    } catch (error) {
+        return false;
+    }
+} 

package/src/utils/config.js

@@ -0,0 +1,96 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+const AUTH_CONFIG_FILE = '.localhero_key';
+const PROJECT_CONFIG_FILE = 'localhero.json';
+
+const DEFAULT_PROJECT_CONFIG = {
+    schemaVersion: '1.0',
+    projectId: '',
+    sourceLocale: 'en',
+    outputLocales: [],
+    translationFiles: {
+        paths: [],
+        ignore: []
+    }
+};
+
+export const configService = {
+    async getAuthConfig(basePath = process.cwd()) {
+        try {
+            const configPath = path.join(basePath, AUTH_CONFIG_FILE);
+            const content = await fs.readFile(configPath, 'utf8');
+            return JSON.parse(content);
+        } catch {
+            return null;
+        }
+    },
+
+    async saveAuthConfig(config, basePath = process.cwd()) {
+        const configPath = path.join(basePath, AUTH_CONFIG_FILE);
+        await fs.writeFile(configPath, JSON.stringify(config, null, 2), {
+            mode: 0o600 // User-only readable
+        });
+    },
+
+    async getProjectConfig(basePath = process.cwd()) {
+        try {
+            const configPath = path.join(basePath, PROJECT_CONFIG_FILE);
+            const content = await fs.readFile(configPath, 'utf8');
+            const config = JSON.parse(content);
+
+            if (config.schemaVersion !== DEFAULT_PROJECT_CONFIG.schemaVersion) {
+                throw new Error(`Unsupported config schema version: ${config.schemaVersion}`);
+            }
+
+            return config;
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    },
+
+    async saveProjectConfig(config, basePath = process.cwd()) {
+        const configPath = path.join(basePath, PROJECT_CONFIG_FILE);
+        const configWithSchema = {
+            ...DEFAULT_PROJECT_CONFIG,
+            ...config,
+            schemaVersion: DEFAULT_PROJECT_CONFIG.schemaVersion
+        };
+        await fs.writeFile(configPath, JSON.stringify(configWithSchema, null, 2));
+    },
+
+    async validateProjectConfig(config) {
+        const required = ['projectId', 'sourceLocale', 'outputLocales', 'translationFiles'];
+        const missing = required.filter(key => !config[key]);
+
+        if (missing.length) {
+            throw new Error(`Missing required config: ${missing.join(', ')}. Run 'npx localhero init' to set up your project.`);
+        }
+
+        if (!Array.isArray(config.outputLocales) || config.outputLocales.length === 0) {
+            throw new Error('outputLocales must be an array with at least one locale');
+        }
+
+        if (config.outputLocales.length > 10) {
+            throw new Error('Maximum 10 target languages allowed per request');
+        }
+
+        if (!config.translationFiles.paths || !Array.isArray(config.translationFiles.paths)) {
+            throw new Error('translationFiles.paths must be an array of paths');
+        }
+
+        return true;
+    },
+
+    async getValidProjectConfig(basePath = process.cwd()) {
+        const config = await this.getProjectConfig(basePath);
+        if (!config) {
+            throw new Error('No localhero.json found. Run `npx localhero init` first');
+        }
+        await this.validateProjectConfig(config);
+        return config;
+    }
+}; 

package/src/utils/defaults.js

@@ -0,0 +1,7 @@
+import inquirer from 'inquirer';
+
+export const defaultDependencies = {
+    inquirer,
+    console: global.console,
+    basePath: process.cwd(),
+}; 

package/src/utils/files.js

@@ -0,0 +1,139 @@
+import { glob } from 'glob';
+import { readFile } from 'fs/promises';
+import path from 'path';
+import yaml from 'yaml';
+
+function parseFile(content, format) {
+    try {
+        if (format === 'json') {
+            return JSON.parse(content);
+        }
+        return yaml.parse(content);
+    } catch (error) {
+        throw new Error(`Failed to parse ${format} file: ${error.message}`);
+    }
+}
+
+function extractKeysWithContext(obj, parentKeys = [], result = {}) {
+    for (const [key, value] of Object.entries(obj)) {
+        const currentPath = [...parentKeys, key];
+        const fullKey = currentPath.join('.');
+
+        if (typeof value === 'object' && value !== null) {
+            extractKeysWithContext(value, currentPath, result);
+        } else {
+            const siblings = {};
+            const parentObj = parentKeys.length ?
+                parentKeys.reduce((acc, key) => acc[key], obj) :
+                obj;
+
+            Object.entries(parentObj)
+                .filter(([k, v]) => k !== key && typeof v !== 'object')
+                .forEach(([k, v]) => {
+                    siblings[`${parentKeys.join('.')}.${k}`] = v;
+                });
+
+            result[fullKey] = {
+                value: value,
+                context: {
+                    parent_keys: parentKeys,
+                    sibling_keys: siblings
+                }
+            };
+        }
+    }
+    return result;
+}
+
+function extractLocaleFromPath(filePath, localeRegex) {
+    const match = path.basename(filePath).match(new RegExp(localeRegex));
+    if (!match || !match[1]) {
+        throw new Error(`Could not extract locale from filename: ${filePath}`);
+    }
+    return match[1].toLowerCase();
+}
+
+function flattenTranslations(obj, parentKey = '') {
+    const result = {};
+
+    for (const [key, value] of Object.entries(obj)) {
+        const newKey = parentKey ? `${parentKey}.${key}` : key;
+
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            Object.assign(result, flattenTranslations(value, newKey));
+        } else {
+            result[newKey] = value;
+        }
+    }
+
+    return result;
+}
+
+export async function findTranslationFiles(translationPath, localeRegex) {
+    const pattern = path.join(translationPath, '**/*.{yml,yaml,json}');
+    const files = await glob(pattern, { absolute: true });
+
+    return Promise.all(files.map(async (filePath) => {
+        try {
+            const locale = extractLocaleFromPath(filePath, localeRegex);
+            const content = await readFile(filePath, 'utf8');
+            const format = path.extname(filePath).slice(1);
+            const parsedContent = parseFile(content, format);
+
+            // Extract translations, handling both nested and flat structures
+            let translations;
+            if (parsedContent[locale]) {
+                // Nested under locale key (common in Rails/YAML)
+                translations = flattenTranslations(parsedContent[locale]);
+            } else {
+                // Flat structure (common in JSON)
+                translations = flattenTranslations(parsedContent);
+            }
+
+            // Extract keys with context
+            const keys = {};
+            for (const [key, value] of Object.entries(translations)) {
+                const parts = key.split('.');
+                const parentKeys = parts.slice(0, -1);
+
+                // Get sibling translations
+                const siblings = {};
+                Object.entries(translations)
+                    .filter(([k, v]) => {
+                        const kParts = k.split('.');
+                        return k !== key &&
+                            kParts.length === parts.length &&
+                            kParts.slice(0, -1).join('.') === parentKeys.join('.');
+                    })
+                    .forEach(([k, v]) => {
+                        siblings[k] = v;
+                    });
+
+                keys[key] = {
+                    value,
+                    context: {
+                        parent_keys: parentKeys,
+                        sibling_keys: siblings
+                    }
+                };
+            }
+
+            const formattedContent = {
+                keys,
+                metadata: {
+                    source_language: locale
+                }
+            };
+
+            return {
+                path: filePath,
+                locale,
+                format,
+                content: Buffer.from(JSON.stringify(formattedContent)).toString('base64')
+            };
+        } catch (error) {
+            console.error(chalk.yellow(`⚠️  Skipping ${filePath}: ${error.message}`));
+            return null;
+        }
+    })).then(results => results.filter(Boolean));
+} 

package/src/utils/git.js

@@ -0,0 +1,16 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+export async function updateGitignore(basePath) {
+    const gitignorePath = path.join(basePath, '.gitignore');
+    try {
+        const content = await fs.readFile(gitignorePath, 'utf8').catch(() => '');
+        if (!content.includes('.localhero_key')) {
+            await fs.appendFile(gitignorePath, '\n.localhero_key\n');
+            return true;
+        }
+        return false;
+    } catch (error) {
+        return false;
+    }
+} 

package/src/utils/github.js

@@ -0,0 +1,65 @@
+import { execSync } from 'child_process';
+import { promises as fs } from 'fs';
+import path from 'path';
+
+export function isGitHubAction() {
+    return process.env.GITHUB_ACTIONS === 'true';
+}
+
+export async function createGitHubActionFile(basePath, translationPaths) {
+    const workflowDir = path.join(basePath, '.github', 'workflows');
+    const workflowFile = path.join(workflowDir, 'localhero-translate.yml');
+
+    // Create directories if they don't exist
+    await fs.mkdir(workflowDir, { recursive: true });
+
+    const actionContent = `name: Localhero.ai - I18n translation
+
+on:
+  pull_request:
+    paths:
+      ${translationPaths.map(p => `- "${p}"`).join('\n      ')}
+
+jobs:
+  translate:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18
+
+    - name: Run LocalHero CLI
+      env:
+        LOCALHERO_API_KEY: \${{ secrets.LOCALHERO_API_KEY }}
+      run: npx @localheroai/cli translate`;
+
+    await fs.writeFile(workflowFile, actionContent);
+    return workflowFile;
+}
+
+export function autoCommitChanges(filesPath) {
+    if (!isGitHubAction()) return;
+
+    console.log("Running in GitHub Actions. Committing changes...");
+    try {
+        execSync(`git config --global user.name "LocalHero Bot"`, { stdio: "inherit" });
+        execSync(`git config --global user.email "bot@localhero.ai"`, { stdio: "inherit" });
+        execSync(`git add ${filesPath}`, { stdio: "inherit" });
+        execSync(`git commit -m "Update translations"`, { stdio: "inherit" });
+        const branchName = process.env.GITHUB_HEAD_REF;
+        execSync(`git push origin ${branchName}`, { stdio: "inherit" });
+        console.log("Changes committed and pushed.");
+    } catch (error) {
+        if (error.message.includes("nothing to commit")) {
+            console.log("No changes to commit.");
+            return;
+        }
+        console.error("Auto-commit failed:", error.message);
+        throw error;
+    }
+} 

package/src/utils/helpers.js

@@ -0,0 +1,3 @@
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}