@gringow/gringow-vite 0.0.5 → 0.0.6

package/README.md

@@ -1,57 +1,260 @@
 # @gringow/gringow-vite
 
-Vite plugin that scans your project for Gringow template literals, keeps the translation cache in sync, and lets you drive builds with the Gringow CLI-style flags. Pair it with the core `@gringow/gringow` package to automate translation discovery during development or CI builds.
+[![npm version](https://img.shields.io/npm/v/@gringow/gringow-vite)](https://www.npmjs.com/package/@gringow/gringow-vite)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Highlights
-- Pre-transform hook that extracts every `g` tagged template literal from your source graph
-- Automatically calls the Gringow runtime to populate `gringow/gringow.json`
-- Removes stale cache entries when strings disappear from source
-- Supports fast cache bootstrap via `--gringow=build|clear|reset` flags
-- Small surface area: Vite 7 compatible, tree-shakeable ESM/CJS exports
+Vite plugin for Gringow that automatically extracts translation strings during development and build. Scans your source code for `g` tagged templates, manages cache synchronization, and provides CLI flags for cache maintenance.
+
+## Features
+
+- 🔍 **Automatic Extraction** - Finds all `g` tagged templates in your code
+- 🔄 **Cache Synchronization** - Keeps translations in sync with source code
+- 🧹 **Smart Cleanup** - Removes unused translations automatically
+- ⚡ **Build-Time Translation** - Generates cache during Vite builds
+- 🛠️ **CLI Flags** - `--gringow=build|clear|reset` for cache management
+- 📦 **Vite 7 Compatible** - Works with latest Vite version
 
 ## Installation
+
 ```bash
+# Using pnpm (recommended)
 pnpm add -D @gringow/gringow @gringow/gringow-vite
-# npm install -D @gringow/gringow @gringow/gringow-vite
-# yarn add -D @gringow/gringow @gringow/gringow-vite
+
+# Using npm
+npm install -D @gringow/gringow @gringow/gringow-vite
+
+# Using yarn
+yarn add -D @gringow/gringow @gringow/gringow-vite
 ```
 
-## Usage
-Add the plugin to your Vite config and run Vite as usual. The plugin relies on the Gringow config file (`gringow.config.js` or similar) to know which files to scan.
+## Quick Start
+
+### 1. Add Plugin to Vite Config
 
-```ts
+```typescript
 // vite.config.ts
 import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
 import Gringow from '@gringow/gringow-vite'
 
 export default defineConfig({
-  plugins: [Gringow({ debug: false })],
+  plugins: [
+    react(),
+    Gringow({ debug: false })
+  ]
 })
 ```
 
-During development the plugin parses transformed modules, calculates cache IDs, and asks the Gringow core library to ensure translations exist. The generated cache lives at `./gringow/gringow.json` by default.
+### 2. Create Gringow Config (Optional)
+
+```javascript
+// gringow.config.js
+export default {
+  llm: {
+    choice: 'huggingface',
+    model: 'Xenova/nllb-200-distilled-600M',
+  },
+  languages: ['pt-BR', 'es-ES', 'fr-CA'],
+  sourceLanguage: 'en-US',
+  globby: './src/**/*.{js,jsx,ts,tsx}', // Files to scan
+}
+```
+
+### 3. Use in Your Code
+
+```tsx
+// App.tsx
+import { g } from '@gringow/gringow-react'
+
+export default function App() {
+  return <h1>{g`Welcome to Gringow`}</h1>
+}
+```
+
+### 4. Build or Develop
+
+```bash
+# Development mode - extracts translations on the fly
+pnpm run dev
+
+# Build mode - generates complete cache
+pnpm run build
+```
+
+The plugin automatically:
+- Scans your source files for `g` tagged templates
+- Generates translations using configured LLM
+- Writes to `./gringow/gringow.json`
+- Updates cache as you code
+
+## CLI Flags
+
+Control cache lifecycle with special flags during Vite builds or dev server startup.
+
+### Build Cache
+
+Scan all source files and generate complete translation cache.
+
+```bash
+vite build --gringow=build
+
+# Useful for:
+# - CI/CD pipelines
+# - Initial cache generation
+# - Pre-deployment translation updates
+```
+
+### Clear Cache
 
-### Command line helpers
-Run Vite with extra flags to control the cache lifecycle without leaving your workflow:
+Delete the entire cache file and exit.
 
 ```bash
-vite build --gringow=build  # Scan all sources up front and build the cache
-vite build --gringow=clear  # Delete the cache file and exit
-vite build --gringow=reset  # Clear then rebuild the cache in one go
+vite build --gringow=clear
+
+# Use when:
+# - Starting fresh
+# - Cleaning up old translations
+# - Debugging cache issues
+```
+
+### Reset Cache
+
+Clear existing cache and rebuild from scratch in one command.
+
+```bash
+vite build --gringow=reset
+
+# Equivalent to:
+# vite build --gringow=clear && vite build --gringow=build
+```
+
+**Note**: These commands exit immediately after completing the operation, making them perfect for CI scripts.
+
+## Configuration
+
+### Plugin Options
+
+```typescript
+interface GringowVitePluginOptions {
+  debug?: boolean  // Log plugin operations (default: false)
+}
+```
+
+**Example:**
+```typescript
+Gringow({ debug: true }) // Logs file scanning and extraction
 ```
 
-These commands exit after completing the requested action so they can be used in CI scripts.
+### Gringow Config Options
 
-## Configuration reference
-- `debug?: boolean` (default `false`): log plugin options during startup for troubleshooting.
+The plugin reads your `gringow.config.js` for:
 
-The plugin reads the Gringow workspace configuration to locate files:
-- `globby`: glob pattern that determines which source files are scanned (defaults to `./src/**/*.{js,jsx,ts,tsx}`).
+- **`globby`** - File pattern to scan (default: `'./src/**/*.{js,jsx,ts,tsx}'`)
+- **`cache.dir`** - Cache directory (default: `'./gringow'`)
+- **`cache.file`** - Cache filename (default: `'gringow.json'`)
+- **`llm.*`** - LLM provider configuration
+- **`languages`** - Target languages array
 
-## How it works
-- `transform`: checks each loaded module, finds `g\`...\`` usage, and seeds the translation cache via `@gringow/gringow`.
-- `buildEnd`: prunes cache entries that no longer exist in source and backfills any new strings discovered by static scanning.
-- `buildStart`: watches for the `--gringow=` flag to run cache maintenance chores outside of normal Vite flows.
+See [@gringow/gringow](https://www.npmjs.com/package/@gringow/gringow) for full config schema.
+
+## How It Works
+
+The plugin hooks into Vite's transform pipeline:
+
+### Transform Hook
+
+- **Scans modules** - Checks each transformed file for `g` tagged templates
+- **Extracts strings** - Parses template literals and dynamic values
+- **Generates IDs** - Creates content-based cache IDs
+- **Calls core library** - Invokes `@gringow/gringow` to translate and cache
+
+### Build End Hook
+
+- **Static analysis** - Scans all files matching `globby` pattern
+- **Cache pruning** - Removes translations no longer in source code
+- **Backfill** - Ensures all discovered strings are translated
+
+### Build Start Hook
+
+- **CLI flag detection** - Watches for `--gringow=build|clear|reset`
+- **Cache operations** - Executes maintenance tasks
+- **Early exit** - Terminates Vite after flag operations
+
+## Usage Examples
+
+### Basic React + Vite Setup
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import Gringow from '@gringow/gringow-vite'
+
+export default defineConfig({
+  plugins: [react(), Gringow()]
+})
+```
+
+```tsx
+// src/App.tsx
+import { g } from '@gringow/gringow-react'
+
+export default function App() {
+  const user = { name: 'Alice' }
+  return (
+    <div>
+      {g`Hello ${user.name}!`}
+      {g`Welcome to our platform`}
+    </div>
+  )
+}
+```
+
+### CI/CD Pipeline
+
+```yaml
+# .github/workflows/deploy.yml
+- name: Generate translations
+  run: pnpm vite build --gringow=build
+
+- name: Build application
+  run: pnpm vite build
+```
+
+### Custom File Patterns
+
+```javascript
+// gringow.config.js
+export default {
+  // Scan TypeScript files only
+  globby: './src/**/*.{ts,tsx}',
+  
+  // Or include multiple patterns
+  globby: [
+    './src/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    '!./src/**/*.test.tsx'
+  ],
+  
+  languages: ['pt-BR', 'es-ES'],
+}
+```
+
+### Multi-Environment Setup
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import Gringow from '@gringow/gringow-vite'
+
+export default defineConfig(({ mode }) => ({
+  plugins: [
+    Gringow({
+      debug: mode === 'development'
+    })
+  ]
+}))
+```
 
 ## Development scripts
 ```bash
@@ -61,3 +264,79 @@ pnpm run watch   # Continuous rebuild for local development
 
 ## License
 MIT © Renato Gaspar
+
+## Best Practices
+
+1. **Run build flag before deployment** - `vite build --gringow=build` ensures complete cache
+2. **Gitignore cache file** - Add `/gringow/gringow.json` to `.gitignore` if regenerating in CI
+3. **Or commit cache** - Commit cache file for faster deploys without LLM calls
+4. **Use glob patterns wisely** - Exclude test files and node_modules
+5. **Enable debug mode** - Use `debug: true` when troubleshooting extraction issues
+
+## Troubleshooting
+
+### Translations Not Extracted
+
+```typescript
+// ❌ Won't work - not using g tag
+const text = `Hello world`
+
+// ✅ Works - using g tag
+const text = g`Hello world`
+```
+
+### Cache Not Updating
+
+```bash
+# Clear and rebuild
+pnpm vite build --gringow=reset
+
+# Or manually delete
+rm -rf gringow/gringow.json
+```
+
+### Missing Translations
+
+Check your `globby` pattern includes all source files:
+
+```javascript
+// gringow.config.js
+export default {
+  globby: './src/**/*.{js,jsx,ts,tsx}', // Adjust to your structure
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the plugin
+pnpm run build
+
+# Watch mode
+pnpm run watch
+```
+
+## Related Packages
+
+- **[@gringow/gringow](https://www.npmjs.com/package/@gringow/gringow)** - Core translation library
+- **[@gringow/gringow-react](https://www.npmjs.com/package/@gringow/gringow-react)** - React bindings
+- **[@gringow/gringow-shadow](https://www.npmjs.com/package/@gringow/gringow-shadow)** - Web Component layer
+- **[@gringow/cli](https://www.npmjs.com/package/@gringow/gringow-cli)** - CLI tool
+- **[@gringow/gringow-nextjs](https://www.npmjs.com/package/@gringow/gringow-nextjs)** - Next.js plugin (experimental)
+
+## Resources
+
+- [Documentation](https://gringow.dev)
+- [GitHub Repository](https://github.com/rntgspr/gringow)
+- [Example: Vite + React](https://github.com/rntgspr/gringow/tree/main/example-gringow-vite)
+
+## License
+
+MIT © [Renato Gaspar](https://github.com/rntgspr)
+
+---
+
+**Questions?** Open an issue on [GitHub](https://github.com/rntgspr/gringow/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gringow/gringow-vite",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "A Vite plugin for Gringow AI-powered translation tool",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -40,7 +40,7 @@
   "dependencies": {
     "globby": "14.1.0",
     "vite": "7.0.0",
-    "@gringow/gringow": "0.1.3"
+    "@gringow/gringow": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "22.15.0",