localingos 0.1.2 → 0.1.4

package/README.md

@@ -29,7 +29,6 @@ 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",
@@ -42,7 +41,26 @@ This will interactively create a `.localingos.json` config file:
 
 > ⚠️ Add `.localingos.json` to your `.gitignore` — it contains your API key.
 
-### 3. Sync translations
+If the source file doesn't exist yet, `init` will offer you three options:
+- **🤖 Generate an AI prompt** to automatically extract all strings from your codebase
+- **📝 Create a sample file** with hello-world entries to try the flow
+- **⏭️ Skip** and create it yourself
+
+### 3. Extract translatable strings (new projects)
+
+If you're internationalizing an existing codebase, use:
+
+```bash
+localingos extract
+```
+
+This detects your project type (React, Next.js, Vue, Angular, etc.) and generates a tailored AI prompt that you paste into your AI assistant (Cline, Cursor, Copilot, ChatGPT). The AI will:
+1. Scan your codebase for all user-facing strings
+2. Create the source locale file (e.g., `en-US.json`)
+3. Replace hardcoded strings with `t('key')` calls
+4. Set up an i18n library if needed
+
+### 4. Sync translations
 
 ```bash
 localingos sync
@@ -60,6 +78,14 @@ This single command will:
 
 Interactive setup wizard. Creates `.localingos.json` in the current directory.
 
+### `localingos extract`
+
+Generates an AI prompt to extract all translatable strings from your codebase.
+
+```bash
+localingos extract    # Detects project type, generates prompt, copies to clipboard
+```
+
 ### `localingos sync`
 
 The main command. Pushes source strings and pulls translations in one call.
@@ -91,10 +117,13 @@ localingos pull              # Pull and write translation files
 | Option | Description |
 |--------|-------------|
 | `-c, --config <path>` | Path to config file (default: `.localingos.json`) |
+| `--env <environment>` | API environment: `prod`, `gamma`, `local` (default: `prod`) |
 | `--dry-run` | Preview without making API calls (sync/push) |
 | `-V, --version` | Show version |
 | `-h, --help` | Show help |
 
+The `--env` flag is for internal development. You can also set the `LOCALINGOS_ENV` environment variable.
+
 ## Supported Formats
 
 | Format | Description | Example |
@@ -173,4 +202,4 @@ git push && git push --tags
 |---------|------------|---------|
 | `npm version patch` | Bug fix, typo, minor tweak | 0.1.0 → 0.1.1 |
 | `npm version minor` | New feature, new format support | 0.1.0 → 0.2.0 |
-| `npm version major` | Breaking config/API change | 0.1.0 → 1.0.0 |
+| `npm version major` | Breaking config/API change | 0.1.0 → 1.0.0 |

package/bin/localingos.js

@@ -5,6 +5,7 @@ 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';
+import { extractCommand } from '../src/commands/extract.js';
 
 program
     .name('localingos')
@@ -20,6 +21,7 @@ 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('--env <environment>', 'API environment: prod, gamma, local (default: prod)')
     .option('--dry-run', 'Show what would be synced without making API calls')
     .action(syncCommand);
 
@@ -27,13 +29,21 @@ program
     .command('pull')
     .description('Pull all available translations from Localingos and write locale files')
     .option('-c, --config <path>', 'Path to config file', '.localingos.json')
+    .option('--env <environment>', 'API environment: prod, gamma, local (default: prod)')
     .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('--env <environment>', 'API environment: prod, gamma, local (default: prod)')
     .option('--dry-run', 'Show what would be pushed without making API calls')
     .action(pushCommand);
 
+program
+    .command('extract')
+    .description('Generate an AI prompt to extract all translatable strings from your codebase')
+    .option('-c, --config <path>', 'Path to config file', '.localingos.json')
+    .action(extractCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localingos",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI tool to sync translations with Localingos",
   "main": "src/index.js",
   "type": "module",

package/src/commands/extract.js

@@ -0,0 +1,205 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Detect project type by scanning for common files.
+ */
+function detectProjectType() {
+    const indicators = {
+        react: ['package.json'],
+        nextjs: ['next.config.js', 'next.config.mjs', 'next.config.ts'],
+        vue: ['vue.config.js', 'nuxt.config.js', 'nuxt.config.ts'],
+        angular: ['angular.json'],
+        svelte: ['svelte.config.js'],
+        flutter: ['pubspec.yaml'],
+        ios: ['Package.swift', 'Podfile'],
+        android: ['build.gradle', 'build.gradle.kts'],
+    };
+
+    const detected = [];
+    for (const [type, files] of Object.entries(indicators)) {
+        for (const file of files) {
+            if (fs.existsSync(path.resolve(file))) {
+                detected.push(type);
+                break;
+            }
+        }
+    }
+
+    // Check package.json dependencies for more specificity
+    const pkgPath = path.resolve('package.json');
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (allDeps['next']) detected.push('nextjs');
+            if (allDeps['react']) detected.push('react');
+            if (allDeps['vue']) detected.push('vue');
+            if (allDeps['@angular/core']) detected.push('angular');
+            if (allDeps['svelte']) detected.push('svelte');
+            if (allDeps['react-i18next']) detected.push('react-i18next');
+            if (allDeps['next-intl']) detected.push('next-intl');
+            if (allDeps['vue-i18n']) detected.push('vue-i18n');
+        } catch (e) {
+            // Ignore parse errors
+        }
+    }
+
+    return [...new Set(detected)];
+}
+
+function getI18nLibrarySuggestion(projectTypes) {
+    if (projectTypes.includes('react-i18next') || projectTypes.includes('next-intl') || projectTypes.includes('vue-i18n')) {
+        return null; // Already has one
+    }
+    if (projectTypes.includes('nextjs')) return 'next-intl';
+    if (projectTypes.includes('react')) return 'react-i18next';
+    if (projectTypes.includes('vue')) return 'vue-i18n';
+    if (projectTypes.includes('angular')) return '@ngx-translate/core';
+    if (projectTypes.includes('svelte')) return 'svelte-i18n';
+    return 'i18next'; // Generic fallback
+}
+
+function getFileExtensions(projectTypes) {
+    const exts = ['.js', '.jsx', '.ts', '.tsx'];
+    if (projectTypes.includes('vue')) exts.push('.vue');
+    if (projectTypes.includes('svelte')) exts.push('.svelte');
+    if (projectTypes.includes('angular')) exts.push('.html');
+    return exts;
+}
+
+/**
+ * Generate the extraction prompt. Exported so init.js can call it too.
+ */
+export function generateExtractPrompt(config) {
+    const projectTypes = detectProjectType();
+    const i18nLib = getI18nLibrarySuggestion(projectTypes);
+    const fileExts = getFileExtensions(projectTypes);
+    const format = config.format || 'json-nested';
+    const sourceFile = config.sourceFile || './src/i18n/en-US.json';
+    const outputDir = config.outputDir || './src/i18n';
+
+    const formatExample = format === 'json-flat' 
+        ? `{
+  "page_name.section.element": "English text here"
+}`
+        : `{
+  "page_name": {
+    "section": {
+      "element": "English text here"
+    }
+  }
+}`;
+
+    const prompt = `## Task: Extract all translatable strings from this project and set up i18n
+
+Scan this codebase and extract every user-facing string into an i18n source file.
+
+### What to extract:
+- All visible text content in UI components (${fileExts.join(', ')} files)
+- Button labels, link text, menu items
+- Form labels, input placeholders, helper text
+- Headings, titles, page descriptions
+- Error messages, validation messages, toast/notification messages
+- Modal titles and content
+- Alt text for images
+- Aria labels and accessibility text
+- Static list items and table headers
+- Tooltip text
+
+### What NOT to extract:
+- Code comments, console.log messages
+- CSS class names, HTML attributes that aren't text
+- Technical identifiers (URLs, API paths, query params)
+- Constants that aren't user-visible
+- Enum values used only programmatically
+- Package names, library identifiers
+
+### Output file:
+Create \`${sourceFile}\` in this format:
+
+\`\`\`json
+${formatExample}
+\`\`\`
+
+### Key naming convention:
+- Use dot-separated paths: \`{page}.{section}.{element}\`
+- Use lowercase snake_case for key segments
+- Be descriptive: \`login.form.email_placeholder\` not \`text_1\`
+- Group by page/feature first, then by section, then by element
+- Use common prefixes for shared strings: \`common.buttons.save\`, \`common.buttons.cancel\`
+
+### Source code changes:
+${i18nLib ? `1. Install \`${i18nLib}\` as a dependency
+2. Set it up to load translations from \`${outputDir}/{locale}.json\`
+3. Replace` : `1. Using the existing i18n library in this project, replace`} every hardcoded string in the source code with the appropriate translation function call (e.g., \`t('key')\` or equivalent)
+${i18nLib ? '4' : '2'}. Make sure imports are added to every file that uses translation calls
+${i18nLib ? '5' : '3'}. Preserve any dynamic values using interpolation: \`t('greeting.welcome', { name: userName })\`
+
+### Important:
+- Extract ALL user-facing strings — do not leave any hardcoded text
+- If a string contains dynamic values like \`\${name}\`, use interpolation: \`"Hello, {name}"\`
+- Maintain the original string exactly as-is in the source file (English)
+- After extraction, \`localingos sync\` will handle translating to other languages`;
+
+    // Print the prompt
+    console.log(chalk.blue('🤖 AI Extraction Prompt'));
+    console.log(chalk.blue('─'.repeat(60)));
+    console.log(chalk.gray('Copy the prompt below and paste it into your AI assistant'));
+    console.log(chalk.gray('(Cline, Cursor, Copilot, ChatGPT, etc.)'));
+    console.log(chalk.blue('─'.repeat(60)));
+    console.log('');
+    console.log(prompt);
+    console.log('');
+    console.log(chalk.blue('─'.repeat(60)));
+
+    // Detect project info
+    if (projectTypes.length > 0) {
+        console.log(chalk.gray(`\n📋 Detected project: ${projectTypes.join(', ')}`));
+    }
+    if (i18nLib) {
+        console.log(chalk.gray(`📦 Suggested i18n library: ${i18nLib}`));
+    }
+
+    // Try to copy to clipboard (macOS)
+    try {
+        execSync('command -v pbcopy', { stdio: 'ignore' });
+        execSync('echo ' + JSON.stringify(prompt) + ' | pbcopy', { stdio: 'ignore' });
+        console.log(chalk.green('\n✅ Prompt copied to clipboard!'));
+    } catch (e) {
+        console.log(chalk.yellow('\n💡 Copy the prompt above and paste it into your AI assistant.'));
+    }
+
+    console.log(chalk.blue(`\nAfter the AI extracts your strings, run "localingos sync" to push and translate.\n`));
+}
+
+/**
+ * CLI command handler
+ */
+export async function extractCommand(options) {
+    let config;
+    const configPath = path.resolve(options.config || '.localingos.json');
+    
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        } catch (e) {
+            config = {};
+        }
+    } else {
+        // No config file — use sensible defaults
+        config = {};
+    }
+
+    // Fill in defaults for anything missing
+    config = {
+        format: config.format || 'json-nested',
+        sourceFile: config.sourceFile || './src/i18n/en-US.json',
+        outputDir: config.outputDir || './src/i18n',
+        ...config
+    };
+    
+    generateExtractPrompt(config);
+}

package/src/commands/init.js

@@ -1,12 +1,33 @@
-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);
+const SAMPLE_SOURCE_FILES = {
+    'json-nested': {
+        greeting: {
+            hello: 'Hello',
+            welcome: 'Welcome to our app'
+        },
+        buttons: {
+            submit: 'Submit',
+            cancel: 'Cancel'
+        },
+        errors: {
+            required: 'This field is required',
+            invalid_email: 'Please enter a valid email address'
+        }
+    },
+    'json-flat': {
+        'greeting.hello': 'Hello',
+        'greeting.welcome': 'Welcome to our app',
+        'buttons.submit': 'Submit',
+        'buttons.cancel': 'Cancel',
+        'errors.required': 'This field is required',
+        'errors.invalid_email': 'Please enter a valid email address'
+    }
+};
 
 export async function initCommand() {
     const inquirer = (await import('inquirer')).default;
@@ -28,12 +49,6 @@ export async function initCommand() {
     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',
@@ -43,7 +58,7 @@ export async function initCommand() {
         {
             type: 'input',
             name: 'familyId',
-            message: 'Family ID (your project/family in Localingos):',
+            message: 'Family ID (copy from Families page → Family ID column):',
             validate: (input) => input.trim().length > 0 || 'Family ID is required'
         },
         {
@@ -79,7 +94,6 @@ export async function initCommand() {
     ]);
 
     const config = {
-        apiUrl: answers.apiUrl.trim(),
         apiKey: answers.apiKey.trim(),
         familyId: answers.familyId.trim(),
         sourceLocale: answers.sourceLocale.trim(),
@@ -110,5 +124,38 @@ export async function initCommand() {
         }
     }
 
-    console.log(chalk.blue('\nRun "localingos sync" to push source strings and pull translations.\n'));
+    // Check if source file exists — offer to create sample or generate extraction prompt
+    const sourceFilePath = path.resolve(config.sourceFile);
+    if (!fs.existsSync(sourceFilePath)) {
+        console.log(chalk.yellow(`\n⚠️  Source file doesn't exist yet: ${config.sourceFile}`));
+        
+        const { action } = await inquirer.prompt([{
+            type: 'list',
+            name: 'action',
+            message: 'How would you like to set up your source strings?',
+            choices: [
+                { name: '🤖 Generate an AI prompt to extract strings from my codebase (recommended)', value: 'extract' },
+                { name: '📝 Create a sample file with hello-world entries', value: 'sample' },
+                { name: '⏭️  Skip — I\'ll create it myself', value: 'skip' }
+            ]
+        }]);
+
+        if (action === 'sample') {
+            const sampleContent = SAMPLE_SOURCE_FILES[config.format] || SAMPLE_SOURCE_FILES['json-nested'];
+            fs.mkdirSync(path.dirname(sourceFilePath), { recursive: true });
+            fs.writeFileSync(sourceFilePath, JSON.stringify(sampleContent, null, 2) + '\n', 'utf-8');
+            console.log(chalk.green(`✅ Created sample source file: ${config.sourceFile}`));
+            console.log(chalk.gray('   Edit this file to add your real translatable strings.'));
+            console.log(chalk.blue('\nRun "localingos sync" to push these source strings and get translations!\n'));
+        } else if (action === 'extract') {
+            console.log('');
+            // Dynamically import and run the extract prompt generator
+            const { generateExtractPrompt } = await import('./extract.js');
+            generateExtractPrompt(config);
+        } else {
+            console.log(chalk.blue(`\nCreate your source file at ${config.sourceFile}, then run "localingos sync".\n`));
+        }
+    } else {
+        console.log(chalk.blue('\nRun "localingos sync" to push source strings and pull translations.\n'));
+    }
 }

package/src/commands/pull.js

@@ -1,15 +1,16 @@
 import chalk from 'chalk';
 import path from 'path';
-import { loadConfig } from '../config.js';
+import { loadConfig, resolveApiUrl } 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 apiUrl = resolveApiUrl(options.env);
     const formatter = getFormatter(config.format);
 
     console.log(chalk.blue(`⬇️  Pulling translations for family ${config.familyId}...`));
-    const api = new LocalingosApi(config.apiUrl, config.apiKey);
+    const api = new LocalingosApi(apiUrl, config.apiKey);
 
     let translations;
     try {

package/src/commands/push.js

@@ -1,17 +1,27 @@
 import chalk from 'chalk';
+import fs from 'fs';
 import path from 'path';
-import { loadConfig } from '../config.js';
+import { loadConfig, resolveApiUrl } 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 apiUrl = resolveApiUrl(options.env);
     const formatter = getFormatter(config.format);
 
     // 1. Extract source strings
     const sourceFilePath = path.resolve(config.sourceFile);
     console.log(chalk.blue(`📖 Extracting source strings from ${sourceFilePath}`));
 
+    if (!fs.existsSync(sourceFilePath)) {
+        console.error(chalk.red(`\n❌ Source file not found: ${config.sourceFile}`));
+        console.error(chalk.yellow('   To create it, you have two options:'));
+        console.error(chalk.yellow('   1. Run "localingos extract" to generate an AI prompt that will create it for you'));
+        console.error(chalk.yellow('   2. Run "localingos init" again and choose "Create a sample file"'));
+        process.exit(1);
+    }
+
     let entries;
     try {
         entries = formatter.extract(sourceFilePath);
@@ -20,6 +30,12 @@ export async function pushCommand(options) {
         process.exit(1);
     }
 
+    if (entries.length === 0) {
+        console.error(chalk.red(`\n❌ Source file is empty: ${config.sourceFile}`));
+        console.error(chalk.yellow('   Add your translatable strings as key-value pairs, or run "localingos extract" for help.'));
+        process.exit(1);
+    }
+
     console.log(chalk.gray(`   Found ${entries.length} translatable strings`));
 
     const translatables = entries.map(entry => ({
@@ -41,7 +57,7 @@ export async function pushCommand(options) {
 
     // 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);
+    const api = new LocalingosApi(apiUrl, config.apiKey);
 
     try {
         await api.postTranslatables(config.familyId, translatables);

package/src/commands/sync.js

@@ -1,17 +1,27 @@
 import chalk from 'chalk';
+import fs from 'fs';
 import path from 'path';
-import { loadConfig } from '../config.js';
+import { loadConfig, resolveApiUrl } 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 apiUrl = resolveApiUrl(options.env);
     const formatter = getFormatter(config.format);
 
     // 1. Extract source strings
     const sourceFilePath = path.resolve(config.sourceFile);
     console.log(chalk.blue(`📖 Extracting source strings from ${sourceFilePath}`));
 
+    if (!fs.existsSync(sourceFilePath)) {
+        console.error(chalk.red(`\n❌ Source file not found: ${config.sourceFile}`));
+        console.error(chalk.yellow('   To create it, you have two options:'));
+        console.error(chalk.yellow('   1. Run "localingos extract" to generate an AI prompt that will create it for you'));
+        console.error(chalk.yellow('   2. Run "localingos init" again and choose "Create a sample file"'));
+        process.exit(1);
+    }
+
     let entries;
     try {
         entries = formatter.extract(sourceFilePath);
@@ -20,6 +30,12 @@ export async function syncCommand(options) {
         process.exit(1);
     }
 
+    if (entries.length === 0) {
+        console.error(chalk.red(`\n❌ Source file is empty: ${config.sourceFile}`));
+        console.error(chalk.yellow('   Add your translatable strings as key-value pairs, or run "localingos extract" for help.'));
+        process.exit(1);
+    }
+
     console.log(chalk.gray(`   Found ${entries.length} translatable strings`));
 
     // Build translatables payload
@@ -42,7 +58,7 @@ export async function syncCommand(options) {
 
     // 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);
+    const api = new LocalingosApi(apiUrl, config.apiKey);
 
     let result;
     try {

package/src/config.js

@@ -4,6 +4,27 @@ import chalk from 'chalk';
 
 const DEFAULT_CONFIG_FILE = '.localingos.json';
 
+const ENVIRONMENTS = {
+    prod: 'https://api.localingos.com',
+    gamma: 'https://gamma-api.localingos.com',
+    local: 'https://desktop.localingos.com:8080'
+};
+
+/**
+ * Resolve the API URL based on --env flag or LOCALINGOS_ENV env variable.
+ * Defaults to production.
+ */
+export function resolveApiUrl(envFlag) {
+    const env = envFlag || process.env.LOCALINGOS_ENV || 'prod';
+    const url = ENVIRONMENTS[env];
+    if (!url) {
+        const valid = Object.keys(ENVIRONMENTS).join(', ');
+        console.error(chalk.red(`Unknown environment "${env}". Valid: ${valid}`));
+        process.exit(1);
+    }
+    return url;
+}
+
 export function loadConfig(configPath) {
     const resolvedPath = path.resolve(configPath || DEFAULT_CONFIG_FILE);
 
@@ -18,7 +39,7 @@ export function loadConfig(configPath) {
         const config = JSON.parse(raw);
 
         // Validate required fields
-        const required = ['apiKey', 'familyId', 'apiUrl', 'sourceLocale', 'format', 'sourceFile', 'outputDir'];
+        const required = ['apiKey', 'familyId', '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(', ')}`));