@vocoder/cli 0.1.2 → 0.1.3

package/README.md

@@ -1,305 +1,127 @@
 # @vocoder/cli
 
-CLI tool for the Vocoder translation workflow. Extract translatable strings from your React code and get them translated automatically.
+CLI for Vocoder translation workflows.
 
-## Installation
+Commands:
+
+- `vocoder init`
+- `vocoder sync`
+- `vocoder wrap`
+
+## Install
 
 ```bash
-npm install -D @vocoder/cli
-# or
 pnpm add -D @vocoder/cli
-# or
-yarn add -D @vocoder/cli
 ```
 
-## Quick Start
+## `vocoder sync`
+
+Extracts translatable strings, sends them to Vocoder, then generates runtime artifacts for `@vocoder/react`.
+
+Generated output:
+
+`node_modules/@vocoder/generated`
 
-1. **Set up environment variables** (create `.env` in your project root):
+Includes:
+
+- `manifest.mjs`
+- `manifest.cjs`
+- `<locale>.js` files
+- `package.json` exports map
+
+### Typical usage
 
 ```bash
-VOCODER_API_KEY=your-api-key-here
+pnpm exec vocoder sync
 ```
 
-2. **Add to your build script**:
+Add to build pipeline:
 
 ```json
 {
   "scripts": {
-    "prebuild": "vocoder sync",
+    "prebuild": "pnpm exec vocoder sync",
     "build": "next build"
   }
 }
 ```
 
-3. **Use `<T>` components in your code**:
+### Options
 
-```tsx
-import { T } from '@vocoder/react';
+- `--include <pattern>` (repeatable)
+- `--exclude <pattern>` (repeatable)
+- `--branch <name>`
+- `--force`
+- `--dry-run`
+- `--verbose`
 
-function MyComponent() {
-  return (
-    <div>
-      <T>Welcome to our app!</T>
-      <T name={userName}>Hello, {name}!</T>
-    </div>
-  );
-}
-```
+## `vocoder wrap`
 
-4. **Run the CLI**:
+Scans source files and wraps likely user-facing strings with `<T>` / `t()` patterns.
 
 ```bash
-npx vocoder sync
+pnpm exec vocoder wrap
 ```
 
-This will:
-- Extract all `<T>` components from your code
-- Submit them to Vocoder for translation
-- Download translations to `.vocoder/locales/*.json`
-- Only translate NEW strings (incremental updates are fast!)
-
-## Configuration
-
-The CLI uses environment variables for configuration:
-
-### Required
-
-- **`VOCODER_API_KEY`**: Your Vocoder API key (get from https://vocoder.dev)
-
-### Optional (Development Only)
-
-- **`VOCODER_API_URL`**: Override API endpoint (defaults to `https://api.vocoder.dev`)
-
-### Defaults (Not Configurable)
-
-- **Target locales**: `es`, `fr`, `de`
-- **Extraction pattern**: `src/**/*.{tsx,jsx,ts,js}`
-- **Output directory**: `.vocoder/locales`
-- **Target branches**: `main`, `master`, `production`, `staging`
-
-To customize these defaults, configure them in your Vocoder dashboard.
-
-## Commands
+Options:
 
-### `vocoder sync`
+- `--include <pattern>` (repeatable)
+- `--exclude <pattern>` (repeatable)
+- `--dry-run`
+- `--interactive`
+- `--confidence <high|medium|low>`
+- `--verbose`
 
-Extract and translate strings.
-
-```bash
-npx vocoder sync [options]
-```
+## Configuration
 
-**Options:**
+Config priority:
 
-- `--branch <name>` - Specify branch name (auto-detected from git)
-- `--force` - Translate even if not on a target branch
-- `--dry-run` - Show what would be translated without making API calls
-- `--verbose` - Show detailed output
+1. CLI flags
+2. environment variables
+3. defaults
 
-**Examples:**
+### Environment variables
 
 ```bash
-# Normal usage (auto-detects branch from git)
-npx vocoder sync
-
-# Specify branch manually
-npx vocoder sync --branch feature/new-ui
-
-# See what would be translated without making API calls
-npx vocoder sync --dry-run
-
-# Force translation even if not on a target branch
-npx vocoder sync --force
-
-# Verbose output for debugging
-npx vocoder sync --verbose
+VOCODER_API_KEY=vc_xxx
+VOCODER_API_URL=https://vocoder.app
+VOCODER_EXTRACTION_PATTERN=src/**/*.{tsx,jsx,ts,js}
 ```
 
-## Workflow
+`VOCODER_API_KEY` must come from the environment.
 
-### First Run (100 strings)
-```bash
-$ npx vocoder sync
-✓ Detected branch: main
-✓ Loaded config for project: abc123
-✓ Extracted 100 strings from src/**/*.{tsx,jsx,ts,js}
-✓ Submitted to API - Batch ID: batch-xyz
-  Found 100 new strings to translate
-⏳ Translating to 3 locales (es, fr, de)
-  Estimated time: ~30 seconds
-✓ Translations complete!
-✓ Wrote 3 locale files
-
-✅ Translation complete! (32.4s)
-```
+## `vocoder init`
 
-### Second Run (Same strings, 0 new)
-```bash
-$ npx vocoder sync
-✓ Detected branch: main
-✓ Loaded config for project: abc123
-✓ Extracted 100 strings from src/**/*.{tsx,jsx,ts,js}
-✓ Submitted to API - Batch ID: batch-abc
-  Found 0 new strings to translate
-
-✅ No new strings - using existing translations
-✓ Wrote 3 locale files
+Bootstraps a project by opening a browser authorization flow, then provisioning
+a workspace/project API key.
 
-✅ Translation complete! (0.8s)
-```
+During browser completion, you can paste a DeepL API key (BYOK) or reuse an
+existing org-level DeepL key.
 
-### Incremental Run (1 new string)
 ```bash
-$ npx vocoder sync
-✓ Detected branch: main
-✓ Loaded config for project: abc123
-✓ Extracted 101 strings from src/**/*.{tsx,jsx,ts,js}
-✓ Submitted to API - Batch ID: batch-def
-  Found 1 new strings to translate
-⏳ Translating to 3 locales (es, fr, de)
-  Estimated time: ~1 seconds
-✓ Translations complete!
-✓ Wrote 3 locale files
-
-✅ Translation complete! (1.2s)
-```
-
-## Branch-Scoped Translations
-
-Translations are isolated per git branch:
-
-- **Main branch** translations are shared across the team
-- **Feature branches** get their own translations
-- Feature branches fall back to main branch translations
-- Merge to main to promote feature translations
-
-This allows you to:
-- Test translations in feature branches
-- Preview translations before merging
-- Avoid conflicts between features
-
-## Performance
-
-The CLI is optimized for incremental updates:
-
-| Scenario | Time | Cost |
-|----------|------|------|
-| 100 new strings | ~30s | 100 strings × 3 locales |
-| 0 new strings | <1s | No API calls |
-| 1 new string | ~1s | 1 string × 3 locales |
-
-**Speedup: 30x faster** for incremental updates!
-
-## Output
-
-Translations are written to `.vocoder/locales/`:
-
-```
-.vocoder/
-└── locales/
-    ├── es.json
-    ├── fr.json
-    └── de.json
-```
-
-Each file contains a flat key-value mapping:
-
-```json
-{
-  "Welcome to our app!": "¡Bienvenido a nuestra aplicación!",
-  "Hello, {name}!": "¡Hola, {name}!",
-  "You have {count} messages": "Tienes {count} mensajes"
-}
-```
-
-**Add to `.gitignore`:**
-
-```
-.vocoder/
-```
-
-Translations are generated at build time, not checked into git.
-
-## Integration with React
-
-Use the generated locale files with `@vocoder/react`:
-
-```tsx
-import { VocoderProvider } from '@vocoder/react';
-import en from './.vocoder/locales/en.json';
-import es from './.vocoder/locales/es.json';
-import fr from './.vocoder/locales/fr.json';
-
-export default function App({ children }) {
-  return (
-    <VocoderProvider
-      translations={{ en, es, fr }}
-      defaultLocale="en"
-    >
-      {children}
-    </VocoderProvider>
-  );
-}
+pnpm exec vocoder init
 ```
 
 ## Troubleshooting
 
-### "VOCODER_API_KEY is required"
-
-Create a `.env` file in your project root:
+### `VOCODER_API_KEY is required`
 
-```bash
-VOCODER_API_KEY=your-api-key
-```
+Set `VOCODER_API_KEY` in `.env` or your environment.
 
-### "No translatable strings found"
+### No strings found
 
-Make sure you're using `<T>` components from `@vocoder/react`:
+Use `<T>` (from `@vocoder/react`) around translatable JSX text.
 
-```tsx
-import { T } from '@vocoder/react';
+### Wrong branch / skipped sync
 
-// ✅ Good
-<T>Welcome!</T>
+Use:
 
-// ❌ Bad (not detected)
-<span>Welcome!</span>
+```bash
+pnpm exec vocoder sync --branch main
 ```
 
-### "Not a git repository"
-
-The CLI auto-detects the branch from git. Either:
-- Initialize git: `git init`
-- Specify branch manually: `vocoder sync --branch main`
-
-### "Skipping translations (not a target branch)"
-
-The CLI only runs on target branches (`main`, `master`, `production`, `staging`) by default. Either:
-- Merge to a target branch
-- Use `--force` flag: `vocoder sync --force`
-
-## Development
+or force:
 
 ```bash
-# Install dependencies
-pnpm install
-
-# Build
-pnpm build
-
-# Run tests
-pnpm test
-
-# Run unit tests only (fast)
-pnpm test:unit
-
-# Run integration tests (requires API)
-pnpm test:integration
-
-# Watch mode
-pnpm test:watch
+pnpm exec vocoder sync --force
 ```
-
-## License
-
-MIT