localingos 1.0.0 → 1.0.1

package/README.md

@@ -1,16 +1,11 @@
 # Localingos CLI
 
-Sync translations between your codebase and [Localingos](https://localingos.com) with a single command.
-
-## Quick Start
+AI-powered translation for developers. Localize your app into 56 languages with one command.
 
 ```bash
-# Install globally
 npm install -g localingos
-
-# Or use with npx (no install needed)
-npx localingos init
-npx localingos sync
+localingos init
+localingos sync
 ```
 
 ## Setup
@@ -25,12 +20,15 @@ Go to [localingos.com](https://localingos.com) → **Developer Tools** → **API
 localingos init
 ```
 
-This will interactively create a `.localingos.json` config file:
+This creates two config files:
+
+- **`localingos.config.json`** — commit this. Contains project settings (no secrets).
+- **`.localingos.json`** — gitignored. Contains your API key for local development.
 
 ```json
+// localingos.config.json
 {
-  "apiKey": "your-api-key",
-  "familyId": "your-family-id",
+  "projectId": "your-project-id",
   "sourceLocale": "en-US",
   "format": "json-nested",
   "sourceFile": "./src/i18n/en-US.json",
@@ -39,22 +37,18 @@ This will interactively create a `.localingos.json` config file:
 }
 ```
 
-> ⚠️ Add `.localingos.json` to your `.gitignore` — it contains your API key.
-
 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
+- **🤖 Generate an AI prompt** to extract all strings from your codebase
+- **📝 Create a sample file** with hello-world entries
 - **⏭️ 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:
+Detects your project type (React, Next.js, Vue, Angular, etc.) and generates a tailored AI prompt. Paste it into your AI assistant (Cursor, Copilot, Claude, ChatGPT) and it 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
@@ -66,63 +60,96 @@ This detects your project type (React, Next.js, Vue, Angular, etc.) and generate
 localingos sync
 ```
 
-This single command will:
-1. **Extract** all translatable strings from your source file
-2. **Push** them to Localingos (creates new keys, updates changed ones)
-3. **Pull** all available translations
-4. **Write** translation files per locale (e.g., `es-ES.json`, `fr-FR.json`)
+One command to:
+1. **Push** source strings to Localingos
+2. **Pull** all available translations
+3. **Write** locale files (e.g., `es-ES.json`, `fr-FR.json`, `zh-CN.json`)
 
 ## Commands
 
-### `localingos init`
+| Command | Description |
+|---------|-------------|
+| `localingos init` | Interactive setup wizard |
+| `localingos extract` | Generate AI prompt to extract translatable strings |
+| `localingos sync` | Push source strings and pull translations |
+| `localingos push` | Push source strings only |
+| `localingos pull` | Pull translations and write locale files |
+| `localingos mcp-serve` | Start MCP server for AI coding agents |
 
-Interactive setup wizard. Creates `.localingos.json` in the current directory.
+### Options
 
-### `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
-```
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview without making API calls (sync/push) |
+| `--prune` | Remove stale keys from locale files (sync) |
+| `-c, --config <path>` | Path to config file |
+| `-V, --version` | Show version |
+| `-h, --help` | Show help |
 
-### `localingos sync`
+## MCP Server
 
-The main command. Pushes source strings and pulls translations in one call.
+The CLI includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) server. Give your AI coding agent direct access to your translation workflow.
 
 ```bash
-localingos sync              # Full sync
-localingos sync --dry-run    # Preview what would be synced
+localingos mcp-serve
 ```
 
-### `localingos push`
+Configure your AI agent:
 
-Push source strings only (no pull).
-
-```bash
-localingos push              # Push source strings
-localingos push --dry-run    # Preview what would be pushed
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "localingos": { "command": "localingos", "args": ["mcp-serve"] }
+  }
+}
 ```
 
-### `localingos pull`
-
-Pull translations only (no push).
-
-```bash
-localingos pull              # Pull and write translation files
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "localingos": { "command": "localingos", "args": ["mcp-serve"], "cwd": "/path/to/your/project" }
+  }
+}
 ```
 
-### Common Options
-
-| 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 |
+**Remote (no install needed):**
+```json
+{
+  "mcpServers": {
+    "localingos": {
+      "type": "streamable-http",
+      "url": "https://mcp.localingos.com?apiKey=YOUR_KEY&projectId=YOUR_PROJECT_ID"
+    }
+  }
+}
+```
 
-The `--env` flag is for internal development. You can also set the `LOCALINGOS_ENV` environment variable.
+### Available Tools (20)
+
+| Tool | Description |
+|---|---|
+| `localingos_sync` | Push source strings & pull translations |
+| `localingos_push` | Push source strings only |
+| `localingos_pull` | Pull translations and write locale files |
+| `localingos_status` | Show project, locales, key counts |
+| `localingos_search` | Search keys/text across source strings |
+| `localingos_extract` | Run i18n extraction script |
+| `localingos_list_projects` | List all projects you have access to |
+| `localingos_get_translatables` | Get all source strings for a project |
+| `localingos_get_translations` | Get all translations for a project |
+| `localingos_get_translation` | Get translations for a single key |
+| `localingos_get_translations_batch` | Get translations for multiple keys |
+| `localingos_update_translations` | Create or update translations manually |
+| `localingos_delete_translatables` | Delete source strings (prune stale keys) |
+| `localingos_translation_jobs` | List translation jobs, filter by state |
+| `localingos_retry_job` | Retry a single failed translation job |
+| `localingos_retry_all_jobs` | Retry all failed/blocked jobs |
+| `localingos_project_members` | List members of a project |
+| `localingos_add_member` | Add a member to a project |
+| `localingos_remove_member` | Remove a member |
+| `localingos_billing_status` | Show billing status, plan, and usage |
 
 ## Supported Formats
 
@@ -131,143 +158,72 @@ The `--env` flag is for internal development. You can also set the `LOCALINGOS_E
 | `json-nested` | Nested JSON objects | `{ "welcome": { "title": "Hello" } }` |
 | `json-flat` | Flat key-value JSON | `{ "welcome.title": "Hello" }` |
 
-More formats (YAML, properties, XLIFF) coming soon.
-
 ## CI/CD Integration
 
-Add to your build pipeline to keep translations in sync:
+### GitHub Actions — Auto-sync on push
+
+Automatically sync translations when source files change on `main`:
+
+1. Add your API key as a repository secret: `LOCALINGOS_API_KEY`
+2. Commit `localingos.config.json` (project config, no secrets)
+3. Copy [`examples/github-actions-sync.yml`](examples/github-actions-sync.yml) to `.github/workflows/localingos-sync.yml`
 
 ```yaml
-# GitHub Actions example
+# Minimal example
 - name: Sync translations
   run: npx localingos sync
   env:
-    # Store API key as a secret, override config
     LOCALINGOS_API_KEY: ${{ secrets.LOCALINGOS_API_KEY }}
 ```
 
-## How It Works
-
-```
-Your codebase                    Localingos
-┌──────────────┐                ┌──────────────┐
-│ en-US.json   │ ──── push ──→ │  Process &    │
-│ (source)     │                │  Translate    │
-│              │ ←── pull ──── │  (AI-powered) │
-│ es-ES.json   │                │              │
-│ fr-FR.json   │                │              │
-│ de-DE.json   │                │              │
-└──────────────┘                └──────────────┘
-```
-
-The `sync` command combines push + pull into a single API call for efficiency. New/changed strings are registered for translation processing. Already-translated strings are returned immediately.
-
-## Publishing to npm
-
-### First-time setup
-
-```bash
-npm login  # Log in to your npmjs.com account (requires 2FA)
-```
-
-### Publishing a new version
-
-From the `localingos-cli/` directory:
-
-```bash
-# Patch release (0.1.0 → 0.1.1) — bug fixes
-npm version patch && npm publish
-
-# Minor release (0.1.0 → 0.2.0) — new features
-npm version minor && npm publish
-
-# Major release (0.1.0 → 1.0.0) — breaking changes
-npm version major && npm publish
-```
-
-`npm version` automatically:
-- Bumps the version in `package.json`
-- Creates a git commit with message `v0.2.0`
-- Creates a git tag `v0.2.0`
-
-After publishing, push the tag to git:
-
-```bash
-git push && git push --tags
-```
-
-### Quick reference
-
-| Command | When to use | Example |
-|---------|------------|---------|
-| `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 |
-
-## CI/CD Integration
-
-### GitHub Actions — Auto-sync on push
-
-Automatically sync translations when `.messages.ts` files change on `main`:
-
-1. Add your API key as a repository secret: `LOCALINGOS_API_KEY`
-   (Settings → Secrets and variables → Actions → New repository secret)
-
-2. Make sure `localingos.config.json` is committed (project config, no secrets).
-   `.localingos.json` stays in `.gitignore` (contains API key for local dev only).
-
-3. Copy [`examples/github-actions-sync.yml`](examples/github-actions-sync.yml) to `.github/workflows/localingos-sync.yml`
-
-This workflow:
-- Triggers when `.messages.ts` or `src/i18n/` files change on `main`
-- Runs `localingos sync --prune` to push source strings and pull translations
-- Commits updated translation files back to the repo
-
 ### GitHub Actions — PR check
 
-Fail PRs if i18n source files are out of date or orphan messages exist:
+Fail PRs if i18n source files are out of date:
 
 Copy [`examples/github-actions-check.yml`](examples/github-actions-check.yml) to `.github/workflows/localingos-check.yml`
 
-This runs `npm run i18n:check` which verifies:
-- `en-US.json` and `en-US.descriptions.json` match the `.messages.ts` files
-- No orphan messages (defined but never referenced in code)
-
 ### Environment variable
 
-The CLI supports `LOCALINGOS_API_KEY` as an environment variable, which takes precedence over the `apiKey` field in `.localingos.json`. This lets you keep the API key out of your repo:
-
-When you run `localingos init`, it creates two files:
-
-- **`localingos.config.json`** — commit this. Contains project settings (familyId, locale, paths). No secrets.
-- **`.localingos.json`** — gitignored. Contains only your `apiKey` for local development.
+The CLI resolves the API key in this order:
+1. `apiKeyEnv` custom env var (if set in config)
+2. `LOCALINGOS_API_KEY` env var
+3. `apiKey` in `.localingos.json`
 
-```bash
-# Local dev — the CLI reads apiKey from .localingos.json automatically
-localingos sync
-
-# CI — set as a GitHub secret, the CLI reads it from the env var
-LOCALINGOS_API_KEY=your-key localingos sync
-```
+### Monorepo support
 
-### Multiple projects (monorepo)
-
-If you have multiple projects in one repo, each with its own `localingos.config.json` and API key, add an `apiKeyEnv` field to each config pointing to a different env var:
+Each project gets its own `localingos.config.json` with a different `apiKeyEnv`:
 
 ```json
 // apps/web/localingos.config.json
-{ "apiKeyEnv": "LOCALINGOS_KEY_WEB", "familyId": "...", ... }
+{ "apiKeyEnv": "LOCALINGOS_KEY_WEB", "projectId": "...", ... }
 
 // apps/docs/localingos.config.json
-{ "apiKeyEnv": "LOCALINGOS_KEY_DOCS", "familyId": "...", ... }
+{ "apiKeyEnv": "LOCALINGOS_KEY_DOCS", "projectId": "...", ... }
 ```
 
-Then in your workflow, pass each secret:
-
 ```yaml
 env:
   LOCALINGOS_KEY_WEB: ${{ secrets.LOCALINGOS_KEY_WEB }}
   LOCALINGOS_KEY_DOCS: ${{ secrets.LOCALINGOS_KEY_DOCS }}
 ```
 
-The CLI checks `apiKeyEnv` first, then falls back to `LOCALINGOS_API_KEY`, then `apiKey` in the config file.
+## How It Works
+
+```
+Your codebase                    Localingos
+┌──────────────┐                ┌──────────────┐
+│ en-US.json   │ ──── push ──→ │  Process &    │
+│ (source)     │                │  Translate    │
+│              │ ←── pull ──── │  (AI-powered) │
+│ es-ES.json   │                │              │
+│ fr-FR.json   │                │              │
+│ zh-CN.json   │                │              │
+└──────────────┘                └──────────────┘
+```
+
+## Links
+
+- [Website](https://localingos.com)
+- [Documentation](https://localingos.com/docs)
+- [MCP Server](https://localingos.com/mcp)
+- [Pricing](https://localingos.com/pricing)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localingos",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "AI-powered translation CLI — localize your app into 56 languages with one command. Supports React, Next.js, Vue, Angular. MCP server included.",
   "main": "src/index.js",
   "type": "module",

package/src/commands/mcp-serve.js

@@ -257,6 +257,108 @@ export async function mcpServeCommand() {
     }
   );
 
+  // ── Project discovery ──────────────────────────────────────────────────
+
+  server.tool('localingos_list_projects', 'List all projects the authenticated user has access to.', {}, async () => {
+    const result = await api('GET', '/project', apiUrl, config.apiKey);
+    const projects = result.projects || [];
+    if (!projects.length) return { content: [{ type: 'text', text: 'No projects found.' }] };
+    const lines = projects.map(p => `${p.id} — ${p.name || '(unnamed)'}${p.locales?.length ? ` [${p.locales.join(', ')}]` : ''}`);
+    return { content: [{ type: 'text', text: `${projects.length} project(s):\n${lines.join('\n')}` }] };
+  });
+
+  // ── Translatable management ────────────────────────────────────────────
+
+  server.tool('localingos_delete_translatables',
+    'Delete source strings from the project by their foreign IDs. Used for pruning stale keys.',
+    { foreignIds: z.array(z.string()).describe('List of foreign IDs (key names) to delete') },
+    async ({ foreignIds }) => {
+      try {
+        await api('DELETE', `/translatable/${config.projectId}`, apiUrl, config.apiKey, { foreignIds });
+        return { content: [{ type: 'text', text: `Deleted ${foreignIds.length} translatable(s)` }] };
+      } catch (e) { return { content: [{ type: 'text', text: `Failed: ${e.message}` }] }; }
+    }
+  );
+
+  // ── Translation tools ──────────────────────────────────────────────────
+
+  server.tool('localingos_get_translation',
+    'Get all translations for a single source string (by foreign ID / key name).',
+    { foreignId: z.string().describe('The key name (foreign ID) of the source string') },
+    async ({ foreignId }) => {
+      const translations = await api('GET', `/translation/${config.projectId}/${encodeURIComponent(foreignId)}`, apiUrl, config.apiKey);
+      if (!translations?.length) return { content: [{ type: 'text', text: `No translations found for "${foreignId}"` }] };
+      const lines = translations.map(t => `${t.locale}: "${t.text}"`);
+      return { content: [{ type: 'text', text: `${translations.length} translation(s) for "${foreignId}":\n${lines.join('\n')}` }] };
+    }
+  );
+
+  server.tool('localingos_get_translations_batch',
+    'Get translations for multiple source strings at once.',
+    { foreignIds: z.array(z.string()).describe('List of key names to fetch translations for') },
+    async ({ foreignIds }) => {
+      const translations = await api('POST', `/translation/${config.projectId}/batch`, apiUrl, config.apiKey, { foreignIds });
+      if (!translations?.length) return { content: [{ type: 'text', text: 'No translations found.' }] };
+      const byKey = {};
+      for (const t of translations) (byKey[t.foreignId] ||= []).push(t);
+      const lines = Object.entries(byKey).map(([k, ts]) => `${k}: ${ts.map(t => t.locale).join(', ')}`);
+      return { content: [{ type: 'text', text: `${translations.length} translation(s) across ${Object.keys(byKey).length} key(s):\n${lines.join('\n')}` }] };
+    }
+  );
+
+  server.tool('localingos_update_translations',
+    'Create or update translations manually. Useful for correcting AI translations or adding human translations.',
+    { translations: z.array(z.object({
+      foreignId: z.string().describe('Key name of the source string'),
+      locale: z.string().describe('Target locale code (e.g. es-ES, fr-FR)'),
+      text: z.string().describe('The translated text'),
+    })).describe('List of translations to create or update') },
+    async ({ translations }) => {
+      try {
+        const translationList = translations.map(t => ({ ...t, projectId: config.projectId }));
+        await api('POST', '/translation', apiUrl, config.apiKey, { projectId: config.projectId, translationList });
+        return { content: [{ type: 'text', text: `Updated ${translations.length} translation(s)` }] };
+      } catch (e) { return { content: [{ type: 'text', text: `Failed: ${e.message}` }] }; }
+    }
+  );
+
+  // ── Translation job tools ──────────────────────────────────────────────
+
+  server.tool('localingos_translation_jobs',
+    'List translation jobs for the project. Optionally filter by state (QUEUED, IN_PROGRESS, DONE, FAILED, BLOCKED).',
+    { state: z.enum(['QUEUED', 'IN_PROGRESS', 'DONE', 'FAILED', 'BLOCKED']).optional().describe('Filter by job state'),
+      pageSize: z.number().min(1).max(100).optional().default(20).describe('Number of results per page'),
+    },
+    async ({ state, pageSize }) => {
+      const urlPath = state ? `/translation-jobs/project/${config.projectId}/state/${state}` : `/translation-jobs/project/${config.projectId}`;
+      const result = await api('POST', urlPath, apiUrl, config.apiKey, { pageSize, nextToken: null });
+      const jobs = result.jobs || [];
+      if (!jobs.length) return { content: [{ type: 'text', text: `No ${state || ''} jobs found.` }] };
+      const lines = jobs.map(j => `${j.id} [${j.jobState}] ${j.sourceLocale}→${(j.targetLocales || []).join(',')} ${j.errorMessage ? '⚠ ' + j.errorMessage : ''}`);
+      const footer = result.hasMore ? `\n... and more (${result.totalCount} total)` : '';
+      return { content: [{ type: 'text', text: `${result.totalCount} job(s)${state ? ` (${state})` : ''}:\n${lines.join('\n')}${footer}` }] };
+    }
+  );
+
+  server.tool('localingos_retry_job',
+    'Retry a single failed translation job.',
+    { jobId: z.string().describe('The job ID to retry'), jobType: z.string().describe('The job type (e.g. TRANSLATE)') },
+    async ({ jobId, jobType }) => {
+      const result = await api('POST', `/translation-jobs/job/${jobId}/${jobType}/retry`, apiUrl, config.apiKey);
+      if (!result.success) return { content: [{ type: 'text', text: `Retry failed: ${result.message}` }] };
+      return { content: [{ type: 'text', text: `Job ${jobId} queued for retry` }] };
+    }
+  );
+
+  server.tool('localingos_retry_all_jobs',
+    'Retry all failed and blocked translation jobs in the project.',
+    {},
+    async () => {
+      const result = await api('POST', `/translation-jobs/project/${config.projectId}/retry-all`, apiUrl, config.apiKey);
+      return { content: [{ type: 'text', text: result.message || `Retried ${result.totalProcessed} jobs` }] };
+    }
+  );
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }