@localheroai/cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LocalHero.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,62 @@
+{
+    "name": "@localheroai/cli",
+    "version": "0.0.1",
+    "description": "CLI tool for managing translations with LocalHero.ai",
+    "type": "module",
+    "main": "src/index.js",
+    "bin": {
+        "localheroai": "./src/cli.js"
+    },
+    "scripts": {
+        "start": "node src/cli.js",
+        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+        "lint": "eslint .",
+        "postinstall": "chmod +x src/cli.js"
+    },
+    "keywords": [
+        "i18n",
+        "translation",
+        "cli",
+        "localization"
+    ],
+    "author": "LocalHero.ai",
+    "license": "MIT",
+    "dependencies": {
+        "chalk": "^5.3.0",
+        "commander": "^12.0.0",
+        "dotenv": "^16.4.5",
+        "glob": "^10.3.10",
+        "inquirer": "^12.0.1",
+        "yaml": "^2.3.4"
+    },
+    "devDependencies": {
+        "@inquirer/testing": "^2.1.36",
+        "@jest/globals": "^29.7.0",
+        "eslint": "^9.14.0",
+        "jest": "^29.7.0",
+        "@babel/preset-env": "^7.24.0"
+    },
+    "engines": {
+        "node": ">=22.11.0"
+    },
+    "files": [
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "jest": {
+        "testEnvironment": "node",
+        "transform": {},
+        "moduleNameMapper": {
+            "^(\\.{1,2}/.*)\\.js$": "$1"
+        },
+        "testMatch": [
+            "**/tests/**/*.test.js"
+        ],
+        "testEnvironmentOptions": {
+            "extensionsToTreatAsEsm": [
+                ".js"
+            ]
+        }
+    }
+}

package/src/api/auth.js

@@ -0,0 +1,15 @@
+import { apiRequest } from './client.js';
+
+export async function verifyApiKey(apiKey) {
+    try {
+        return await apiRequest('/api/v1/auth/verify', {
+            apiKey
+        });
+    } catch (error) {
+        return {
+            error: {
+                message: error.message || 'Failed to verify API key'
+            }
+        };
+    }
+} 

package/src/api/client.js

@@ -0,0 +1,42 @@
+const DEFAULT_API_HOST = 'https://api.localhero.ai';
+
+export function getApiHost() {
+    return process.env.LOCALHERO_API_HOST || DEFAULT_API_HOST;
+}
+
+export async function apiRequest(endpoint, options = {}) {
+    const apiHost = getApiHost();
+    const url = `${apiHost}${endpoint}`;
+    const apiKey = process.env.LOCALHERO_API_KEY || options.apiKey;
+
+    const headers = {
+        'Content-Type': 'application/json',
+        ...options.headers
+    };
+
+    if (apiKey) {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+
+    console.log('API Request:', url);
+    const response = await fetch(url, {
+        ...options,
+        headers,
+    });
+
+    let data;
+    try {
+        data = await response.json();
+    } catch (error) {
+        throw new Error('Failed to parse API response', { cause: error });
+    }
+
+    if (!response.ok) {
+        const errorMessage = Array.isArray(data?.errors)
+            ? data.errors.map(err => typeof err === 'string' ? err : err.message).join(', ')
+            : 'API request failed';
+        throw new Error(errorMessage);
+    }
+
+    return data;
+} 

package/src/api/imports.js

@@ -0,0 +1,20 @@
+import { getApiKey } from '../utils/auth.js';
+import { apiRequest } from './client.js';
+
+export async function createImport({ projectId, translations }) {
+    const apiKey = await getApiKey();
+    const response = await apiRequest(`/api/v1/projects/${projectId}/imports`, {
+        method: 'POST',
+        body: JSON.stringify({ translations }),
+        apiKey
+    });
+    return response.import;
+}
+
+export async function checkImportStatus(projectId, importId) {
+    const apiKey = await getApiKey();
+    const response = await apiRequest(`/api/v1/projects/${projectId}/imports/${importId}`, {
+        apiKey
+    });
+    return response.import;
+} 

package/src/api/projects.js

@@ -0,0 +1,24 @@
+import { getApiKey } from '../utils/auth.js';
+import { apiRequest } from './client.js';
+
+export async function listProjects() {
+    const apiKey = await getApiKey();
+    const response = await apiRequest('/api/v1/projects', { apiKey });
+    return response.projects;
+}
+
+export async function createProject(data) {
+    const apiKey = await getApiKey();
+    const response = await apiRequest('/api/v1/projects', {
+        method: 'POST',
+        body: JSON.stringify({
+            project: {
+                name: data.name,
+                source_language: data.sourceLocale,
+                target_languages: data.targetLocales
+            }
+        }),
+        apiKey
+    });
+    return response.project;
+} 

package/src/api/translations.js

@@ -0,0 +1,37 @@
+import { getApiKey } from '../utils/auth.js';
+import { apiRequest } from './client.js';
+export async function createTranslationJob({ sourceFiles, targetLocales, projectId }) {
+    const apiKey = await getApiKey();
+    const response = await apiRequest(`/api/v1/projects/${projectId}/translation_jobs`, {
+        method: 'POST',
+        body: JSON.stringify({
+            target_languages: targetLocales,
+            files: sourceFiles.map(file => ({
+                path: file.path,
+                content: file.content,
+                format: file.format
+            }))
+        }),
+        apiKey
+    });
+
+    if (!response.jobs || !response.jobs.length) {
+        throw new Error('No translation jobs were created');
+    }
+
+    return {
+        jobs: response.jobs,
+        totalJobs: response.jobs.length
+    };
+}
+
+export async function checkJobStatus(jobId, includeTranslations = false) {
+    const apiKey = await getApiKey();
+    const endpoint = `/api/v1/translation_jobs/${jobId}${includeTranslations ? '?include_translations=true' : ''}`;
+    return apiRequest(endpoint, { apiKey });
+}
+
+export async function getTranslations(jobId) {
+    const apiKey = await getApiKey();
+    return apiRequest(`/api/v1/translation_jobs/${jobId}/translations`, { apiKey });
+} 

package/src/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { login } from './commands/login.js';
+import { init } from './commands/init.js';
+import { defaultDependencies } from './utils/defaults.js';
+import { translate } from './commands/translate.js';
+
+const program = new Command();
+
+function displayBanner() {
+    console.log(chalk.blue(`
+  ===============================================
+    
+                   LocalHero.ai CLI 
+                   
+  ===============================================
+    `));
+}
+
+function getVersion() {
+    const packageJson = JSON.parse(
+        readFileSync(new URL('../package.json', import.meta.url))
+    );
+    return packageJson.version;
+}
+
+function handleApiError(error) {
+    console.error(chalk.red(`❌ ${error.message}`));
+    process.exit(1);
+}
+
+function wrapCommandAction(action) {
+    return function (...args) {
+        return Promise.resolve(action(...args)).catch(handleApiError);
+    };
+}
+
+program
+    .name('localhero')
+    .description('CLI tool for automatic I18n translations with LocalHero.ai')
+    .version(getVersion())
+    .addHelpText('beforeAll', displayBanner)
+    .action(() => {
+        console.log(`Version: ${getVersion()}`);
+        console.log('\nLocalHero.ai is a powerful i18n translation service');
+        console.log('that helps you manage your application translations.');
+        console.log('\n🔗 Visit https://localhero.ai for more information');
+        console.log('💡 Use --help to see available commands');
+    });
+
+program
+    .command('login')
+    .description('Authenticate with LocalHero.ai using an API key')
+    .action(wrapCommandAction(() => login(defaultDependencies)));
+
+program
+    .command('init')
+    .description('Initialize a new LocalHero.ai project')
+    .action(wrapCommandAction(() => init(defaultDependencies)));
+
+program
+    .command('translate')
+    .description('Translate missing keys in your i18n files')
+    .option('-v, --verbose', 'Show detailed progress information')
+    .option('-c, --commit', 'Automatically commit changes (useful for CI/CD)')
+    .action(wrapCommandAction((options) => translate(options)));
+
+program.parse();

package/src/commands/init.js

@@ -0,0 +1,285 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { createPromptService } from '../utils/prompt-service.js';
+import { defaultProjectService } from '../utils/project-service.js';
+import { configService } from '../utils/config.js';
+import { checkAuth } from '../utils/auth.js';
+import { login } from './login.js';
+import { importService } from '../utils/import-service.js';
+import { createGitHubActionFile } from '../utils/github.js';
+
+const PROJECT_TYPES = {
+    rails: {
+        indicators: ['config/application.rb', 'Gemfile'],
+        defaults: {
+            translationPath: 'config/locales/',
+            filePattern: '**/*.{yml,yaml}'
+        }
+    },
+    react: {
+        indicators: ['package.json', 'src/locales', 'public/locales'],
+        defaults: {
+            translationPath: 'src/locales/',
+            filePattern: '**/*.{json,yml}'
+        }
+    },
+    generic: {
+        indicators: [],
+        defaults: {
+            translationPath: 'locales/',
+            filePattern: '**/*.{json,yml,yaml}'
+        }
+    }
+};
+
+async function detectProjectType() {
+    for (const [type, config] of Object.entries(PROJECT_TYPES)) {
+        try {
+            for (const indicator of config.indicators) {
+                await fs.access(indicator);
+                return { type, defaults: config.defaults };
+            }
+        } catch {
+            continue;
+        }
+    }
+    return {
+        type: 'generic',
+        defaults: PROJECT_TYPES.generic.defaults
+    };
+}
+
+async function checkExistingConfig() {
+    try {
+        await fs.access('localhero.json');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function selectProject(projectService, promptService) {
+    const projects = await projectService.listProjects();
+
+    if (!projects || projects.length === 0) {
+        return { choice: 'new' };
+    }
+
+    const choices = [
+        { name: '✨ Create new project', value: 'new' },
+        { name: '─────────────', value: 'separator', disabled: true },
+        ...projects.map(p => ({
+            name: p.name,
+            value: p.id
+        }))
+    ];
+
+    const projectChoice = await promptService.select({
+        message: 'Would you like to use an existing project or create a new one?',
+        choices
+    });
+
+    return {
+        choice: projectChoice,
+        project: projects.find(p => p.id === projectChoice)
+    };
+}
+
+async function promptForConfig(projectDefaults, projectService, promptService) {
+    const { choice: projectChoice, project: existingProject } = await selectProject(projectService, promptService);
+    let projectId = projectChoice;
+    let newProject = false;
+    let config = await promptService.getProjectSetup();
+
+    if (!existingProject) {
+        config = {
+            projectName: await promptService.input({
+                message: 'Project name:',
+                default: path.basename(process.cwd()),
+            }),
+            sourceLocale: await promptService.input({
+                message: 'Source language code:',
+                default: 'en'
+            }),
+            outputLocales: (await promptService.input({
+                message: 'Target languages (comma-separated):',
+            })).split(',').map(lang => lang.trim()).filter(Boolean)
+        };
+
+        newProject = await projectService.createProject({
+            name: config.projectName,
+            sourceLocale: config.sourceLocale,
+            targetLocales: config.outputLocales
+        });
+        projectId = newProject.id;
+    } else {
+        config = {
+            projectName: existingProject.name,
+            sourceLocale: existingProject.source_language,
+            outputLocales: existingProject.target_languages
+        };
+    }
+
+    const translationPath = await promptService.input({
+        message: 'Translation files path:',
+        default: projectDefaults.defaults.translationPath,
+    });
+
+    const ignorePaths = await promptService.input({
+        message: 'Paths to ignore (comma-separated, leave empty for none):',
+    });
+
+    if (newProject) {
+        console.log(chalk.green(`\n✓ Project created, view it at: ${newProject.url}`));
+    }
+
+    return {
+        ...config,
+        projectId,
+        translationPath,
+        ignorePaths: ignorePaths.split(',').map(p => p.trim()).filter(Boolean)
+    };
+}
+
+export async function init(deps = {}) {
+    const {
+        console = global.console,
+        basePath = process.cwd(),
+        promptService = createPromptService({ inquirer: await import('@inquirer/prompts') }),
+        projectService = defaultProjectService,
+        configUtils = configService,
+        authUtils = { checkAuth },
+        importUtils = importService
+    } = deps;
+
+    const existingConfig = await configUtils.getProjectConfig(basePath);
+    if (existingConfig) {
+        console.log(chalk.yellow('localhero.json already exists. Skipping initialization.'));
+        return;
+    }
+
+    const isAuthenticated = await authUtils.checkAuth();
+    if (!isAuthenticated) {
+        console.log(chalk.yellow('\nNo API key found. You need to authenticate first.'));
+        console.log('Please run the login command to continue.\n');
+
+        const { shouldLogin } = await promptService.confirmLogin();
+
+        if (shouldLogin) {
+            await login();
+        } else {
+            console.log('\nYou can run login later with: npx localhero login');
+            return;
+        }
+    }
+
+    console.log(chalk.blue('\nWelcome to LocalHero.ai!'));
+    console.log('Let\'s set up configuration for your project.\n');
+
+    const projectDefaults = await detectProjectType();
+    const answers = await promptForConfig(projectDefaults, projectService, promptService);
+
+    const config = {
+        schemaVersion: '1.0',
+        projectId: answers.projectId,
+        sourceLocale: answers.sourceLocale,
+        outputLocales: answers.outputLocales,
+        translationFiles: {
+            paths: [answers.translationPath],
+            ignore: answers.ignorePaths
+        }
+    };
+
+    await configUtils.saveProjectConfig(config, basePath);
+    console.log(chalk.green('\n✓ Created localhero.json'));
+    console.log('Configuration:');
+    console.log(JSON.stringify(config, null, 2));
+    console.log(' ');
+
+    const shouldSetupGitHubAction = await promptService.confirm({
+        message: 'Would you like to set up GitHub Actions for automatic translations?',
+        default: true
+    });
+
+    if (shouldSetupGitHubAction) {
+        try {
+            const workflowFile = await createGitHubActionFile(basePath, config.translationFiles.paths);
+            console.log(chalk.green(`\n✓ Created GitHub Action workflow at ${workflowFile}`));
+            console.log('\nNext steps:');
+            console.log('1. Add your API key to your repository\'s secrets:');
+            console.log('   - Go to Settings > Secrets > Actions > New repository secret');
+            console.log('   - Name: LOCALHERO_API_KEY');
+            console.log('   - Value: [Your API Key] (find this at https://localhero.ai/api-keys or in your local .localhero_key file)');
+            console.log('\n2. Commit and push the workflow file to enable automatic translations\n');
+        } catch (error) {
+            console.log(chalk.yellow('\nFailed to create GitHub Action workflow:'), error.message);
+        }
+    }
+
+    const shouldImport = await promptService.confirm({
+        message: 'Would you like to import existing translation files? (recommended)',
+        default: true
+    });
+
+    if (shouldImport) {
+        console.log('\nSearching for translation files...');
+        console.log(`Looking in: ${config.translationFiles.paths.join(', ')}`);
+        if (config.translationFiles.ignore.length) {
+            console.log(`Ignoring: ${config.translationFiles.ignore.join(', ')}`);
+        }
+
+        const importResult = await importUtils.importTranslations(config, basePath);
+
+        if (importResult.status === 'no_files') {
+            console.log(chalk.yellow('\nNo translation files found.'));
+            console.log('Make sure your translation files:');
+            console.log('1. Are in the specified path(s)');
+            console.log('2. Have the correct file extensions (.json, .yml, or .yaml)');
+            console.log('3. Follow the naming convention: [language-code].[extension]');
+            console.log(`4. Include source language files (${config.sourceLocale}.[extension])`);
+        } else if (importResult.status === 'failed') {
+            console.log(chalk.red('\n✗ Failed to import translations'));
+            if (importResult.error) {
+                console.log(`Error: ${importResult.error}`);
+            }
+        } else if (importResult.status === 'completed') {
+            console.log(chalk.green('\n✓ Successfully imported translations'));
+
+            if (importResult.files) {
+                console.log('\nImported files:');
+                [...importResult.files.source, ...importResult.files.target]
+                    .sort((a, b) => a.path.localeCompare(b.path))
+                    .forEach(file => {
+                        const isSource = importResult.files.source.includes(file);
+                        console.log(`- ${file.path}${isSource ? ' [source]' : ''}`);
+                    });
+            }
+
+            if (importResult.sourceImport) {
+                console.log(`\nImported ${importResult.sourceImport.statistics.total_keys} source language keys`);
+
+                if (importResult.sourceImport.warnings?.length) {
+                    console.log(chalk.yellow('\nWarnings:'));
+                    importResult.sourceImport.warnings.forEach(warning => {
+                        console.log(`- ${warning.message} (${warning.language})`);
+                    });
+                }
+            }
+
+            console.log('\nTarget Languages:');
+            importResult.statistics.languages.forEach(lang => {
+                console.log(`${lang.code.toUpperCase()}: ${lang.translated}/${importResult.statistics.total_keys} translated`);
+            });
+
+            if (importResult.warnings?.length) {
+                console.log(chalk.yellow('\nWarnings:'));
+                importResult.warnings.forEach(warning => {
+                    console.log(`- ${warning.message} (${warning.language})`);
+                });
+            }
+        }
+    }
+
+    console.log('\n🚀 Done! Start translating with: npx localhero translate');
+}

package/src/commands/login.js

@@ -0,0 +1,69 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { createPromptService } from '../utils/prompt-service.js';
+import { updateGitignore } from '../utils/git.js';
+import { defaultDependencies } from '../utils/defaults.js';
+import { verifyApiKey as defaultVerifyApiKey } from '../api/auth.js';
+import { configService } from '../utils/config.js';
+
+const API_KEY_PATTERN = /^tk_[a-zA-Z0-9]{48}$/;
+
+export async function login(deps = defaultDependencies) {
+    const {
+        console = global.console,
+        basePath = process.cwd(),
+        promptService = createPromptService({ inquirer: await import('@inquirer/prompts') }),
+        verifyApiKey = defaultVerifyApiKey,
+        gitUtils = { updateGitignore },
+        configUtils = configService
+    } = deps;
+
+    const existingConfig = await configUtils.getAuthConfig(basePath);
+
+    if (existingConfig?.api_key) {
+        console.log(chalk.yellow('\n⚠️  Warning: This will replace your existing API key configuration'));
+    }
+
+    const apiKey = process.env.LOCALHERO_API_KEY || (
+        console.log(chalk.blue('\nℹ️  Please enter your API key from https://localhero.ai/api-keys\n')),
+        await promptService.getApiKey()
+    );
+
+    if (!API_KEY_PATTERN.test(apiKey)) {
+        throw new Error('Invalid API key format');
+    }
+
+    const result = await verifyApiKey(apiKey);
+
+    if (result.error) {
+        throw new Error(result.error.message);
+    }
+
+    const config = {
+        api_key: apiKey,
+        last_verified: new Date().toISOString()
+    };
+
+    await configUtils.saveAuthConfig(config, basePath);
+    const gitignoreUpdated = await gitUtils.updateGitignore(basePath);
+
+    console.log(chalk.green('\n✓ API key verified and saved to .localhero_key'));
+    if (gitignoreUpdated) {
+        console.log(chalk.green('✓ Added .localhero_key to .gitignore'));
+    }
+
+    console.log(chalk.blue(`💼️  Organization: ${result.organization.name}`));
+    console.log(chalk.blue(`📚  Projects: ${result.organization.projects.map(p => p.name).join(', ')}`));
+
+    const projectConfig = await configUtils.getProjectConfig(basePath);
+
+    if (!projectConfig) {
+        console.log(chalk.yellow('\n⚠️  Almost there! You need to set up your project configuration.'));
+        console.log(chalk.blue('Run this next:'));
+        console.log(chalk.white('\n  npx localhero init\n'));
+    } else {
+        console.log('\nYou\'re ready to start translating!');
+        console.log('Try running: npx localhero translate');
+    }
+}