@shipi18n/cli 1.0.0

package/README.md

@@ -0,0 +1,385 @@
+# @shipi18n/cli
+
+Command-line tool for translating locale files with [Shipi18n](https://shipi18n.com).
+
+> **🚀 Translate JSON files in seconds** - One command, multiple languages!
+
+## Features
+
+- ✅ **Translate JSON files** to 100+ languages with one command
+- ✅ **Preserve JSON structure** - Nested objects, arrays, everything
+- ✅ **Placeholder preservation** - Keep `{name}`, `{{value}}`, `%s`, etc. intact
+- ✅ **Key-based pricing** - 100 free translation keys (unlimited characters!)
+- ✅ **Language limits enforced** - FREE: 3 languages, STARTER: 10, PRO: unlimited
+- ✅ **Config file support** - Save settings in `~/.shipi18n/config.yml`
+- ✅ **Translation Memory** - Manage keys with `shipi18n keys` commands
+- ✅ **Beautiful output** - Colored, formatted terminal output
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g @shipi18n/cli
+```
+
+### 2. Get Your Free API Key
+
+Sign up at [shipi18n.com](https://shipi18n.com) - it takes 30 seconds!
+
+**Free tier includes:**
+- 100 translation keys
+- 3 languages
+- 10 requests/minute
+- Unlimited characters
+
+### 3. Configure
+
+```bash
+shipi18n config set apiKey YOUR_API_KEY
+```
+
+### 4. Translate!
+
+```bash
+shipi18n translate en.json --target es,fr,de
+```
+
+Done! You now have `es.json`, `fr.json`, and `de.json` in your `./locales` folder.
+
+## Installation
+
+### Global (recommended)
+
+```bash
+npm install -g @shipi18n/cli
+```
+
+### Local project
+
+```bash
+npm install --save-dev @shipi18n/cli
+```
+
+Then use via npx:
+```bash
+npx shipi18n translate en.json --target es,fr
+```
+
+## Usage
+
+### Translate Command
+
+Translate a JSON locale file to multiple languages:
+
+```bash
+shipi18n translate <input> [options]
+```
+
+**Options:**
+- `-t, --target <languages>` - Target languages (comma-separated, default: `es,fr`)
+- `-s, --source <language>` - Source language (default: `en`)
+- `-o, --output <dir>` - Output directory (default: `./locales`)
+- `--api-key <key>` - API key (overrides config)
+- `--preserve-placeholders` - Preserve placeholders (default: `true`)
+
+**Examples:**
+
+```bash
+# Basic usage
+shipi18n translate en.json --target es,fr
+
+# Custom output directory
+shipi18n translate en.json --target es,fr,de --output ./translations
+
+# Specify source language
+shipi18n translate ja.json --source ja --target en,es
+
+# Use inline API key
+shipi18n translate en.json --target es --api-key sk_live_...
+```
+
+### Keys Management
+
+Manage your translation keys in Translation Memory:
+
+```bash
+# List all saved keys
+shipi18n keys list
+
+# Export keys to JSON
+shipi18n keys export --format json --output keys.json
+
+# Delete a specific key
+shipi18n keys delete <keyId>
+```
+
+### Configuration
+
+Manage CLI settings:
+
+```bash
+# Show current configuration
+shipi18n config get
+
+# Set API key
+shipi18n config set apiKey YOUR_KEY
+
+# Set default target languages
+shipi18n config set targetLanguages es,fr,de
+
+# Initialize config file with defaults
+shipi18n config init
+```
+
+### Help
+
+```bash
+# General help
+shipi18n --help
+
+# Command-specific help
+shipi18n translate --help
+shipi18n keys --help
+shipi18n config --help
+```
+
+## Configuration File
+
+The CLI stores settings in `~/.shipi18n/config.yml`:
+
+```yaml
+apiKey: sk_live_your_api_key_here
+sourceLanguage: en
+targetLanguages:
+  - es
+  - fr
+  - de
+outputDir: ./locales
+saveKeys: true
+```
+
+**Priority:** Environment variables > Config file > Command-line options
+
+## Environment Variables
+
+You can also configure via environment variables:
+
+```bash
+export SHIPI18N_API_KEY=sk_live_your_api_key_here
+export SHIPI18N_SOURCE_LANG=en
+export SHIPI18N_TARGET_LANGS=es,fr,de
+export SHIPI18N_OUTPUT_DIR=./locales
+```
+
+## Supported Languages
+
+Shipi18n supports **100+ languages** including:
+
+**Popular:**
+- 🇪🇸 Spanish (es)
+- 🇫🇷 French (fr)
+- 🇩🇪 German (de)
+- 🇯🇵 Japanese (ja)
+- 🇨🇳 Chinese Simplified (zh)
+- 🇨🇳 Chinese Traditional (zh-TW)
+- 🇵🇹 Portuguese (pt)
+- 🇷🇺 Russian (ru)
+- 🇰🇷 Korean (ko)
+- 🇮🇹 Italian (it)
+
+[See full list of 100+ supported languages](https://shipi18n.com/docs/languages)
+
+## Pricing
+
+| Tier | Price | Keys | Languages | Rate Limit |
+|------|-------|------|-----------|------------|
+| **FREE** | $0/mo | 100 | 3 | 10 req/min |
+| **STARTER** | $9/mo | 500 | 10 | 60 req/min |
+| **PRO** | $29/mo | 10K | 100+ | 300 req/min |
+| **ENTERPRISE** | Custom | Unlimited | Custom | 1000+ req/min |
+
+**What's a "key"?** Each unique translation path (e.g., `app.welcome`) counts as one key. Translating to multiple languages doesn't multiply the count!
+
+## Examples
+
+### Real-World Workflow
+
+```bash
+# Your project structure
+my-app/
+├── locales/
+│   └── en.json        # ✅ You have this
+└── src/
+
+# Translate to multiple languages
+$ shipi18n translate locales/en.json --target es,fr,de,ja
+
+# Result
+my-app/
+├── locales/
+│   ├── en.json        # ✅ Original
+│   ├── es.json        # ✅ Spanish
+│   ├── fr.json        # ✅ French
+│   ├── de.json        # ✅ German
+│   └── ja.json        # ✅ Japanese
+└── src/
+```
+
+### Input File (`en.json`)
+
+```json
+{
+  "app": {
+    "title": "My Application",
+    "welcome": "Welcome, {username}!",
+    "description": "This is a demo"
+  },
+  "auth": {
+    "login": "Log In",
+    "logout": "Log Out"
+  }
+}
+```
+
+### Output (`es.json`)
+
+```json
+{
+  "app": {
+    "title": "Mi Aplicación",
+    "welcome": "¡Bienvenido, {username}!",
+    "description": "Esta es una demostración"
+  },
+  "auth": {
+    "login": "Iniciar Sesión",
+    "logout": "Cerrar Sesión"
+  }
+}
+```
+
+Notice how:
+- ✅ JSON structure is preserved
+- ✅ Placeholders like `{username}` are kept intact
+- ✅ Only values are translated, keys stay in English
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Translate Locales
+on: [push]
+
+jobs:
+  translate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Install Shipi18n CLI
+        run: npm install -g @shipi18n/cli
+
+      - name: Translate
+        env:
+          SHIPI18N_API_KEY: ${{ secrets.SHIPI18N_API_KEY }}
+        run: shipi18n translate locales/en.json --target es,fr,de
+
+      - name: Commit translations
+        run: |
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+          git add locales/
+          git commit -m "Update translations" || echo "No changes"
+          git push
+```
+
+### NPM Scripts
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "translate": "shipi18n translate locales/en.json --target es,fr,de",
+    "translate:dev": "shipi18n translate locales/en.json --target es",
+    "translate:all": "shipi18n translate locales/en.json --target es,fr,de,ja,zh,pt,ru,ko"
+  }
+}
+```
+
+Then run:
+```bash
+npm run translate
+```
+
+## Troubleshooting
+
+### "API key not found"
+
+```bash
+# Set your API key
+shipi18n config set apiKey YOUR_KEY
+
+# Or use environment variable
+export SHIPI18N_API_KEY=YOUR_KEY
+
+# Get your key at https://shipi18n.com
+```
+
+### "Language limit exceeded"
+
+The FREE tier allows 3 languages. Upgrade your plan:
+- **STARTER** ($9/mo) - 10 languages
+- **PRO** ($29/mo) - 100+ languages
+
+### "Rate limit exceeded"
+
+Wait a minute or upgrade your plan for higher rate limits.
+
+### "Invalid JSON"
+
+Make sure your input file is valid JSON:
+```bash
+# Validate JSON
+cat en.json | jq .
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/Shipi18n/shipi18n-cli.git
+cd shipi18n-cli
+
+# Install dependencies
+npm install
+
+# Test locally
+node bin/shipi18n.js translate test.json --target es,fr
+
+# Link globally for testing
+npm link
+shipi18n --help
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Shipi18n Website](https://shipi18n.com)
+- [Documentation](https://shipi18n.com/docs)
+- [API Reference](https://shipi18n.com/docs/api)
+- [GitHub](https://github.com/Shipi18n/shipi18n-cli)
+- [Support](https://github.com/Shipi18n/shipi18n-cli/issues)
+
+---
+
+Built with ❤️ by [Shipi18n](https://shipi18n.com) - Smart translation API for developers

package/bin/shipi18n.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { translateCommand } from '../src/commands/translate.js';
+import { keysCommand } from '../src/commands/keys.js';
+import { configCommand } from '../src/commands/config.js';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read package.json for version
+const packageJson = JSON.parse(
+  readFileSync(join(__dirname, '../package.json'), 'utf8')
+);
+
+const program = new Command();
+
+program
+  .name('shipi18n')
+  .description('🌍 Translate your locale files with Shipi18n')
+  .version(packageJson.version, '-v, --version', 'Output the current version')
+  .addHelpText('after', `
+${chalk.cyan('Examples:')}
+  $ shipi18n translate en.json --target es,fr,de
+  $ shipi18n keys list
+  $ shipi18n config set apiKey sk_live_...
+
+${chalk.cyan('Get started:')}
+  1. Sign up at ${chalk.underline('https://shipi18n.com')}
+  2. Get your API key (free tier: 100 keys, 3 languages)
+  3. Run: ${chalk.yellow('shipi18n config set apiKey YOUR_KEY')}
+  4. Translate: ${chalk.yellow('shipi18n translate en.json --target es,fr')}
+
+${chalk.gray('Documentation: https://shipi18n.com/docs/cli')}
+  `);
+
+// Add commands
+translateCommand(program);
+keysCommand(program);
+configCommand(program);
+
+// Parse arguments
+program.parse(process.argv);
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@shipi18n/cli",
+  "version": "1.0.0",
+  "description": "Command-line tool for translating locale files with Shipi18n",
+  "main": "src/index.js",
+  "type": "module",
+  "files": [
+    "bin",
+    "src/commands",
+    "src/lib",
+    "src/utils",
+    "src/index.js",
+    "README.md"
+  ],
+  "bin": {
+    "shipi18n": "./bin/shipi18n.js"
+  },
+  "scripts": {
+    "dev": "node bin/shipi18n.js",
+    "build": "echo 'No build step needed for now'",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --watch"
+  },
+  "keywords": [
+    "translation",
+    "i18n",
+    "internationalization",
+    "localization",
+    "cli",
+    "shipi18n"
+  ],
+  "author": "Shipi18n",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^11.1.0",
+    "chalk": "^5.3.0",
+    "dotenv": "^16.3.1",
+    "yaml": "^2.3.4",
+    "ora": "^7.0.1",
+    "inquirer": "^9.2.12"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shipi18n/shipi18n-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Shipi18n/shipi18n-cli/issues"
+  },
+  "homepage": "https://shipi18n.com"
+}

package/src/commands/config.js

@@ -0,0 +1,94 @@
+import chalk from 'chalk';
+import { getConfig, setConfigValue, saveConfig } from '../lib/config.js';
+import { logger } from '../utils/logger.js';
+
+export function configCommand(program) {
+  const config = program.command('config')
+    .description('Manage CLI configuration');
+
+  // Get config
+  config
+    .command('get [key]')
+    .description('Get configuration value(s)')
+    .action((key) => {
+      const currentConfig = getConfig();
+
+      if (key) {
+        const value = currentConfig[key];
+        if (value !== undefined && value !== null) {
+          logger.log(`${chalk.cyan(key)}: ${value}`);
+        } else {
+          logger.warn(`Config key "${key}" not found`);
+        }
+      } else {
+        logger.log(chalk.cyan('Current configuration:'));
+        logger.log('');
+        Object.entries(currentConfig).forEach(([k, v]) => {
+          if (v !== undefined && v !== null) {
+            // Mask API key for security
+            if (k === 'apiKey' && v) {
+              logger.log(`  ${chalk.yellow(k)}: ${v.substring(0, 12)}...`);
+            } else {
+              logger.log(`  ${chalk.yellow(k)}: ${v}`);
+            }
+          }
+        });
+        logger.log('');
+        logger.log(chalk.gray('Config file: ~/.shipi18n/config.yml'));
+      }
+    });
+
+  // Set config
+  config
+    .command('set <key> <value>')
+    .description('Set configuration value')
+    .action((key, value) => {
+      try {
+        // Parse value if it's a boolean or array
+        let parsedValue = value;
+        if (value === 'true') parsedValue = true;
+        if (value === 'false') parsedValue = false;
+        if (value.includes(',')) parsedValue = value.split(',').map(v => v.trim());
+
+        setConfigValue(key, parsedValue);
+        logger.success(`Set ${chalk.cyan(key)} = ${parsedValue}`);
+
+        // Show next steps for API key
+        if (key === 'apiKey') {
+          logger.log('');
+          logger.info('API key saved! Try translating a file:');
+          logger.log(`  ${chalk.yellow('shipi18n translate en.json --target es,fr')}`);
+        }
+      } catch (error) {
+        logger.error(`Failed to set config: ${error.message}`);
+        process.exit(1);
+      }
+    });
+
+  // Init config
+  config
+    .command('init')
+    .description('Initialize configuration file with defaults')
+    .action(() => {
+      try {
+        const defaultConfig = {
+          apiKey: '',
+          sourceLanguage: 'en',
+          targetLanguages: ['es', 'fr', 'de'],
+          outputDir: './locales',
+          saveKeys: true,
+        };
+
+        saveConfig(defaultConfig);
+        logger.success('Created config file: ~/.shipi18n/config.yml');
+        logger.log('');
+        logger.info('Next steps:');
+        logger.log(`  1. Get your API key at ${chalk.cyan('https://shipi18n.com')}`);
+        logger.log(`  2. Set your API key: ${chalk.yellow('shipi18n config set apiKey YOUR_KEY')}`);
+        logger.log(`  3. Translate: ${chalk.yellow('shipi18n translate en.json --target es,fr')}`);
+      } catch (error) {
+        logger.error(`Failed to initialize config: ${error.message}`);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/keys.js

@@ -0,0 +1,128 @@
+import chalk from 'chalk';
+import { Shipi18nAPI } from '../lib/api.js';
+import { getConfig } from '../lib/config.js';
+import { logger, formatError } from '../utils/logger.js';
+import { writeFileSync } from 'fs';
+
+export function keysCommand(program) {
+  const keys = program.command('keys')
+    .description('Manage translation keys');
+
+  // List keys
+  keys
+    .command('list')
+    .description('List all translation keys')
+    .option('--api-key <key>', 'API key (overrides config)')
+    .action(async (options) => {
+      const spinner = logger.spinner('Fetching keys...');
+
+      try {
+        const config = getConfig();
+        const apiKey = options.apiKey || config.apiKey;
+
+        if (!apiKey) {
+          spinner.fail();
+          logger.error('API key not found. Run: shipi18n config set apiKey YOUR_KEY');
+          process.exit(1);
+        }
+
+        const api = new Shipi18nAPI(apiKey);
+        const result = await api.listKeys();
+
+        spinner.succeed(chalk.green(`Found ${result.keys?.length || 0} keys`));
+
+        if (!result.keys || result.keys.length === 0) {
+          logger.info('No translation keys found');
+          logger.log(chalk.gray('  Create keys by translating JSON files with --save-keys flag'));
+          return;
+        }
+
+        // Display keys in a table
+        logger.log('');
+        result.keys.forEach((key, index) => {
+          logger.log(chalk.cyan(`${index + 1}. ${key.keyName}`));
+          logger.log(chalk.gray(`   Source: ${key.sourceValue}`));
+          logger.log(chalk.gray(`   Languages: ${Object.keys(key.translations || {}).join(', ')}`));
+          logger.log('');
+        });
+
+        logger.log(chalk.gray(`Total: ${result.keys.length} keys | Limit: ${result.limit || 'unlimited'}`));
+
+      } catch (error) {
+        spinner.fail();
+        logger.log(formatError(error));
+        process.exit(1);
+      }
+    });
+
+  // Delete key
+  keys
+    .command('delete <keyId>')
+    .description('Delete a translation key')
+    .option('--api-key <key>', 'API key (overrides config)')
+    .action(async (keyId, options) => {
+      const spinner = logger.spinner(`Deleting key ${keyId}...`);
+
+      try {
+        const config = getConfig();
+        const apiKey = options.apiKey || config.apiKey;
+
+        if (!apiKey) {
+          spinner.fail();
+          logger.error('API key not found. Run: shipi18n config set apiKey YOUR_KEY');
+          process.exit(1);
+        }
+
+        const api = new Shipi18nAPI(apiKey);
+        await api.deleteKey(keyId);
+
+        spinner.succeed(chalk.green(`Deleted key: ${keyId}`));
+
+      } catch (error) {
+        spinner.fail();
+        logger.log(formatError(error));
+        process.exit(1);
+      }
+    });
+
+  // Export keys
+  keys
+    .command('export')
+    .description('Export all translation keys')
+    .option('-f, --format <format>', 'Export format (json, csv)', 'json')
+    .option('-o, --output <file>', 'Output file')
+    .option('--api-key <key>', 'API key (overrides config)')
+    .action(async (options) => {
+      const spinner = logger.spinner(`Exporting keys as ${options.format}...`);
+
+      try {
+        const config = getConfig();
+        const apiKey = options.apiKey || config.apiKey;
+
+        if (!apiKey) {
+          spinner.fail();
+          logger.error('API key not found. Run: shipi18n config set apiKey YOUR_KEY');
+          process.exit(1);
+        }
+
+        const api = new Shipi18nAPI(apiKey);
+        const result = await api.exportKeys(options.format);
+
+        if (options.output) {
+          const content = options.format === 'json'
+            ? JSON.stringify(result, null, 2)
+            : result;
+          writeFileSync(options.output, content, 'utf8');
+          spinner.succeed(chalk.green(`Exported to: ${options.output}`));
+        } else {
+          spinner.succeed(chalk.green('Export complete'));
+          console.log(JSON.stringify(result, null, 2));
+        }
+
+      } catch (error) {
+        spinner.fail();
+        logger.log(formatError(error));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/translate.js

@@ -0,0 +1,103 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, parse, dirname } from 'path';
+import chalk from 'chalk';
+import { Shipi18nAPI } from '../lib/api.js';
+import { getConfig } from '../lib/config.js';
+import { logger, formatError } from '../utils/logger.js';
+
+export function translateCommand(program) {
+  program
+    .command('translate <input>')
+    .description('Translate a JSON locale file to multiple languages')
+    .option('-t, --target <languages>', 'Target languages (comma-separated)', 'es,fr')
+    .option('-s, --source <language>', 'Source language', 'en')
+    .option('-o, --output <dir>', 'Output directory', './locales')
+    .option('--api-key <key>', 'API key (overrides config)')
+    .option('--preserve-placeholders', 'Preserve placeholders like {name}, {{value}}, etc.', true)
+    .action(async (input, options) => {
+      const spinner = logger.spinner('Translating...');
+
+      try {
+        // Get config
+        const config = getConfig();
+        const apiKey = options.apiKey || config.apiKey;
+
+        if (!apiKey) {
+          spinner.fail();
+          logger.error('API key not found');
+          logger.info('Set your API key:');
+          logger.log(`  ${chalk.yellow('shipi18n config set apiKey YOUR_KEY')}`);
+          logger.log(`  ${chalk.gray('Get your free key at https://shipi18n.com')}`);
+          process.exit(1);
+        }
+
+        // Read input file
+        if (!existsSync(input)) {
+          spinner.fail();
+          logger.error(`Input file not found: ${input}`);
+          process.exit(1);
+        }
+
+        const fileContent = readFileSync(input, 'utf8');
+        let json;
+        try {
+          json = JSON.parse(fileContent);
+        } catch (error) {
+          spinner.fail();
+          logger.error(`Invalid JSON in ${input}: ${error.message}`);
+          process.exit(1);
+        }
+
+        // Parse target languages
+        const targetLanguages = options.target.split(',').map(lang => lang.trim());
+        const sourceLanguage = options.source;
+
+        spinner.text = `Translating to ${targetLanguages.length} language${targetLanguages.length > 1 ? 's' : ''}...`;
+
+        // Translate
+        const api = new Shipi18nAPI(apiKey);
+        const translations = await api.translateJSON({
+          json,
+          sourceLanguage,
+          targetLanguages,
+          preservePlaceholders: options.preservePlaceholders,
+        });
+
+        spinner.succeed(chalk.green(`Translated to ${targetLanguages.length} language${targetLanguages.length > 1 ? 's' : ''}!`));
+
+        // Save translated files
+        const outputDir = options.output;
+        if (!existsSync(outputDir)) {
+          mkdirSync(outputDir, { recursive: true });
+        }
+
+        let savedCount = 0;
+        for (const [langCode, content] of Object.entries(translations)) {
+          if (langCode === 'warnings') continue;
+
+          const outputFile = join(outputDir, `${langCode}.json`);
+          writeFileSync(outputFile, JSON.stringify(content, null, 2), 'utf8');
+          logger.success(`Saved: ${chalk.cyan(outputFile)}`);
+          savedCount++;
+        }
+
+        // Show warnings if any
+        if (translations.warnings && translations.warnings.length > 0) {
+          logger.warn('Warnings:');
+          translations.warnings.forEach(warning => {
+            logger.log(`  ${chalk.yellow('•')} ${warning.message}`);
+          });
+        }
+
+        logger.log('');
+        logger.log(chalk.green(`✨ Successfully translated ${savedCount} file${savedCount > 1 ? 's' : ''}!`));
+        logger.log(chalk.gray(`   Output: ${outputDir}`));
+
+      } catch (error) {
+        spinner.fail();
+        logger.log('');
+        logger.log(formatError(error));
+        process.exit(1);
+      }
+    });
+}

package/src/lib/api.js

@@ -0,0 +1,135 @@
+import dotenv from 'dotenv';
+dotenv.config();
+
+const API_BASE_URL = process.env.SHIPI18N_API_URL || 'https://x9527l3blg.execute-api.us-east-1.amazonaws.com';
+
+/**
+ * Shipi18n API Client
+ */
+export class Shipi18nAPI {
+  constructor(apiKey) {
+    this.apiKey = apiKey || process.env.SHIPI18N_API_KEY;
+    this.baseUrl = API_BASE_URL;
+  }
+
+  /**
+   * Translate JSON file
+   */
+  async translateJSON({ json, sourceLanguage = 'en', targetLanguages, preservePlaceholders = true }) {
+    if (!this.apiKey) {
+      throw new Error('API key is required. Set SHIPI18N_API_KEY or run: shipi18n config set apiKey YOUR_KEY');
+    }
+
+    const jsonString = typeof json === 'string' ? json : JSON.stringify(json);
+
+    const response = await fetch(`${this.baseUrl}/api/translate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': this.apiKey,
+      },
+      body: JSON.stringify({
+        inputMethod: 'text',
+        text: jsonString,
+        sourceLanguage,
+        targetLanguages: JSON.stringify(targetLanguages),
+        preservePlaceholders: String(preservePlaceholders),
+      }),
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({ error: { message: response.statusText } }));
+      const error = new Error(errorData.error?.message || errorData.message || `Translation failed: ${response.statusText}`);
+      error.code = errorData.error?.code;
+      error.status = response.status;
+      throw error;
+    }
+
+    const result = await response.json();
+
+    // Parse JSON strings back to objects
+    const parsed = {};
+    for (const [lang, jsonStr] of Object.entries(result)) {
+      if (lang === 'warnings') {
+        parsed.warnings = jsonStr;
+        continue;
+      }
+      try {
+        parsed[lang] = typeof jsonStr === 'string' ? JSON.parse(jsonStr) : jsonStr;
+      } catch (e) {
+        parsed[lang] = jsonStr;
+      }
+    }
+
+    return parsed;
+  }
+
+  /**
+   * List translation keys
+   */
+  async listKeys() {
+    if (!this.apiKey) {
+      throw new Error('API key is required');
+    }
+
+    const response = await fetch(`${this.baseUrl}/api/keys`, {
+      method: 'GET',
+      headers: {
+        'X-API-Key': this.apiKey,
+      },
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({ error: { message: response.statusText } }));
+      throw new Error(errorData.error?.message || errorData.message || 'Failed to list keys');
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Delete a translation key
+   */
+  async deleteKey(keyId) {
+    if (!this.apiKey) {
+      throw new Error('API key is required');
+    }
+
+    const response = await fetch(`${this.baseUrl}/api/keys/${keyId}`, {
+      method: 'DELETE',
+      headers: {
+        'X-API-Key': this.apiKey,
+      },
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({ error: { message: response.statusText } }));
+      throw new Error(errorData.error?.message || errorData.message || 'Failed to delete key');
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Export translation keys
+   */
+  async exportKeys(format = 'json') {
+    if (!this.apiKey) {
+      throw new Error('API key is required');
+    }
+
+    const response = await fetch(`${this.baseUrl}/api/keys/export/${format}`, {
+      method: 'GET',
+      headers: {
+        'X-API-Key': this.apiKey,
+      },
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({ error: { message: response.statusText } }));
+      throw new Error(errorData.error?.message || errorData.message || 'Failed to export keys');
+    }
+
+    return response.json();
+  }
+}

package/src/lib/config.js

@@ -0,0 +1,74 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import YAML from 'yaml';
+
+const CONFIG_DIR = join(homedir(), '.shipi18n');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.yml');
+
+/**
+ * Get configuration from file or environment variables
+ */
+export function getConfig() {
+  const config = {
+    apiKey: process.env.SHIPI18N_API_KEY,
+    sourceLanguage: process.env.SHIPI18N_SOURCE_LANG || 'en',
+    targetLanguages: process.env.SHIPI18N_TARGET_LANGS?.split(','),
+    outputDir: process.env.SHIPI18N_OUTPUT_DIR || './locales',
+    saveKeys: process.env.SHIPI18N_SAVE_KEYS === 'true',
+  };
+
+  // Try to read from config file
+  if (existsSync(CONFIG_FILE)) {
+    try {
+      const fileContent = readFileSync(CONFIG_FILE, 'utf8');
+      const fileConfig = YAML.parse(fileContent);
+
+      // Merge with priority: env vars > config file
+      Object.keys(fileConfig).forEach((key) => {
+        if (config[key] === undefined || config[key] === null) {
+          config[key] = fileConfig[key];
+        }
+      });
+    } catch (error) {
+      console.warn(`Warning: Could not read config file: ${error.message}`);
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Save configuration to file
+ */
+export function saveConfig(config) {
+  try {
+    // Create directory if it doesn't exist
+    if (!existsSync(CONFIG_DIR)) {
+      mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+
+    const yamlContent = YAML.stringify(config);
+    writeFileSync(CONFIG_FILE, yamlContent, 'utf8');
+    return true;
+  } catch (error) {
+    throw new Error(`Failed to save config: ${error.message}`);
+  }
+}
+
+/**
+ * Get a specific config value
+ */
+export function getConfigValue(key) {
+  const config = getConfig();
+  return config[key];
+}
+
+/**
+ * Set a specific config value
+ */
+export function setConfigValue(key, value) {
+  const config = getConfig();
+  config[key] = value;
+  saveConfig(config);
+}

package/src/utils/logger.js

@@ -0,0 +1,46 @@
+import chalk from 'chalk';
+import ora from 'ora';
+
+export const logger = {
+  success: (message) => {
+    console.log(chalk.green('✓'), message);
+  },
+
+  error: (message) => {
+    console.log(chalk.red('✗'), message);
+  },
+
+  warn: (message) => {
+    console.log(chalk.yellow('⚠'), message);
+  },
+
+  info: (message) => {
+    console.log(chalk.blue('ℹ'), message);
+  },
+
+  log: (message) => {
+    console.log(message);
+  },
+
+  spinner: (text) => {
+    return ora(text).start();
+  },
+};
+
+export function formatError(error) {
+  if (error.code === 'ENOTFOUND') {
+    return chalk.red('Network error: Could not connect to Shipi18n API');
+  }
+
+  if (error.message.includes('Language limit exceeded')) {
+    return chalk.red(error.message) + '\n' +
+      chalk.yellow('💡 Upgrade your plan at https://shipi18n.com to translate to more languages');
+  }
+
+  if (error.message.includes('API key')) {
+    return chalk.red(error.message) + '\n' +
+      chalk.yellow('💡 Get your free API key at https://shipi18n.com or run: shipi18n config set apiKey YOUR_KEY');
+  }
+
+  return chalk.red(error.message);
+}