@vocoder/cli 0.1.2 → 0.1.4

package/README.md

@@ -1,304 +1,129 @@
 # @vocoder/cli
 
-CLI tool for the Vocoder translation workflow. Extract translatable strings from your React code and get them translated automatically.
+Command-line tool for Vocoder. Handles project setup, string extraction from source code, and translation synchronization.
 
 ## Installation
 
 ```bash
-npm install -D @vocoder/cli
-# or
-pnpm add -D @vocoder/cli
-# or
-yarn add -D @vocoder/cli
+npm install -g @vocoder/cli
 ```
 
-## Quick Start
-
-1. **Set up environment variables** (create `.env` in your project root):
+Or use directly with npx:
 
 ```bash
-VOCODER_API_KEY=your-api-key-here
+npx vocoder <command>
 ```
 
-2. **Add to your build script**:
-
-```json
-{
-  "scripts": {
-    "prebuild": "vocoder sync",
-    "build": "next build"
-  }
-}
-```
-
-3. **Use `<T>` components in your code**:
-
-```tsx
-import { T } from '@vocoder/react';
-
-function MyComponent() {
-  return (
-    <div>
-      <T>Welcome to our app!</T>
-      <T name={userName}>Hello, {name}!</T>
-    </div>
-  );
-}
-```
-
-4. **Run the CLI**:
-
-```bash
-npx vocoder sync
-```
-
-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
 
-### `vocoder sync`
+### `vocoder init`
 
-Extract and translate strings.
+Connect your repository to Vocoder.
 
 ```bash
-npx vocoder sync [options]
-```
-
-**Options:**
-
-- `--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
-
-**Examples:**
-
-```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 init
 ```
 
-## Workflow
+The command detects your git remote and checks if a Vocoder project already exists for the repository. If found, it confirms the connection and prints next steps. If not, it opens a browser-based setup flow to create a new project.
 
-### 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)
-```
+**Options:**
 
-### 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
+| Flag | Description |
+|---|---|
+| `--api-url <url>` | Override Vocoder API URL |
+| `--yes` | Skip confirmation prompts |
+| `--project-name <name>` | Pre-fill project name |
+| `--source-locale <locale>` | Pre-fill source locale |
+| `--target-locales <list>` | Comma-separated target locales (e.g., `es,fr,de`) |
 
-✅ No new strings - using existing translations
-✓ Wrote 3 locale files
+### `vocoder sync`
 
-✅ Translation complete! (0.8s)
-```
+Extract translatable strings from your source code and push them to Vocoder for translation.
 
-### 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/
+vocoder sync
 ```
 
-Translations are generated at build time, not checked into git.
+This command:
 
-## Integration with React
+1. Detects the current git branch and repository
+2. Scans your source files for `<T>` components and `t()` calls
+3. Extracts the source text, file location, and any context/formality hints
+4. Sends the extracted strings to the Vocoder API
+5. Optionally waits for translations to complete (based on sync mode)
 
-Use the generated locale files with `@vocoder/react`:
+**Options:**
 
-```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';
+| Flag | Description |
+|---|---|
+| `--branch <name>` | Override branch detection |
+| `--include <pattern>` | Glob pattern(s) to include (repeatable) |
+| `--exclude <pattern>` | Glob pattern(s) to exclude (repeatable) |
+| `--force` | Sync even if not on a target branch |
+| `--mode <mode>` | Sync mode: `auto`, `required`, or `best-effort` |
+| `--max-wait-ms <ms>` | Max wait time before fallback (milliseconds) |
+| `--no-fallback` | Fail instead of falling back to cached translations |
+| `--dry-run` | Show what would be synced without sending |
+| `--verbose` | Show detailed progress |
 
-export default function App({ children }) {
-  return (
-    <VocoderProvider
-      translations={{ en, es, fr }}
-      defaultLocale="en"
-    >
-      {children}
-    </VocoderProvider>
-  );
-}
-```
+#### Sync Modes
 
-## Troubleshooting
+- **`auto`** (default) -- Checks the project's sync policy. Blocking branches (e.g., `main`, `production`) use `required` mode; other branches use `best-effort`.
+- **`required`** -- Waits for translations to complete before finishing. Fails if translations can't be completed within the timeout.
+- **`best-effort`** -- Sends strings for translation but doesn't wait. Falls back to the latest available translations.
 
-### "VOCODER_API_KEY is required"
+### `vocoder wrap`
 
-Create a `.env` file in your project root:
+Automatically wrap string literals in your source code with `<T>` and `t()`.
 
 ```bash
-VOCODER_API_KEY=your-api-key
+vocoder wrap
 ```
 
-### "No translatable strings found"
-
-Make sure you're using `<T>` components from `@vocoder/react`:
-
-```tsx
-import { T } from '@vocoder/react';
+Scans your JSX/TSX files for user-facing string literals and wraps them with the appropriate Vocoder translation markers. Uses AST analysis to detect strings that are likely user-facing (not keys, classnames, or internal identifiers).
 
-// ✅ Good
-<T>Welcome!</T>
+**Options:**
 
-// ❌ Bad (not detected)
-<span>Welcome!</span>
-```
+| Flag | Description |
+|---|---|
+| `--include <pattern>` | Glob pattern(s) to include (repeatable) |
+| `--exclude <pattern>` | Glob pattern(s) to exclude (repeatable) |
+| `--dry-run` | Preview changes without modifying files |
+| `--interactive` | Confirm each string interactively |
+| `--confidence <level>` | Minimum confidence: `high`, `medium`, `low` (default: `high`) |
+| `--verbose` | Detailed output |
 
-### "Not a git repository"
+## Environment Variables
 
-The CLI auto-detects the branch from git. Either:
-- Initialize git: `git init`
-- Specify branch manually: `vocoder sync --branch main`
+| Variable | Required | Description |
+|---|---|---|
+| `VOCODER_API_KEY` | Yes (for `sync`) | API key for authenticating with the Vocoder API |
+| `VOCODER_API_URL` | No | Override API URL (default: `https://vocoder.app`) |
 
-### "Skipping translations (not a target branch)"
+The CLI reads `.env` files in the project root automatically.
 
-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`
+## String Extraction
 
-## Development
+The CLI uses Babel to parse JSX/TSX files and extract strings from:
 
-```bash
-# Install dependencies
-pnpm install
+- `<T>` component children: `<T>Hello, world!</T>`
+- `<T>` component `msg` prop: `<T msg="{count, plural, one {# item} other {# items}}" />`
+- `t()` function calls: `t('Hello, world!')`
 
-# Build
-pnpm build
+It tracks imports from `@vocoder/react` to ensure only Vocoder components are extracted (not unrelated components that happen to be named `T`).
 
-# Run tests
-pnpm test
+Each extracted string includes:
+- The source text (used as the translation key)
+- File path and line number
+- Optional `context` and `formality` props
 
-# Run unit tests only (fast)
-pnpm test:unit
+## Git Integration
 
-# Run integration tests (requires API)
-pnpm test:integration
+The CLI auto-detects the repository and branch:
 
-# Watch mode
-pnpm test:watch
-```
+- **Repository:** Reads the git remote URL and normalizes it to a canonical format (`github:owner/repo`)
+- **Branch:** Checks CI environment variables first (GitHub Actions, Vercel, Netlify, etc.), then falls back to reading `.git/HEAD`
+- **Scope path:** For monorepos, computes the relative path from the git root to the working directory
 
 ## License