@gringow/gringow 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,18 @@
 # @gringow/gringow
 
-Core library for Gringow to translate strings and template strings using different LLM providers.
+[![npm version](https://img.shields.io/npm/v/@gringow/gringow)](https://www.npmjs.com/package/@gringow/gringow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+AI-powered translation library for template strings using multiple LLM providers (Hugging Face, Anthropic, Gemini). Gringow provides smart caching, deterministic content hashing, and seamless integration for modern JavaScript/TypeScript projects.
+
+## Features
+
+- 🌍 **Multi-language translation** using LLM providers
+- 🏷️ **Tagged template literal** syntax for inline translations
+- 💾 **Smart caching** with content-based hashing
+- 🔌 **Three LLM providers**: Hugging Face (local), Anthropic, Gemini
+- 🚀 **Zero configuration** - works out of the box with Hugging Face
+- 📦 **Optimized builds** via Vite/Next.js plugins
 
 ## Installation
 
@@ -12,76 +24,342 @@ pnpm add @gringow/gringow
 yarn add @gringow/gringow
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import Gringow from '@gringow/gringow'
 
 // Simple string translation
-const result = await Gringow`Hello world`
-console.log(result.translation) // { "pt-BR": "Olá mundo", "fr-CA": "Bonjour le monde" }
+const { cacheId, translation } = await Gringow`Hello world`
+console.log(translation.translation)
+// => { "pt-BR": "Olá mundo", "fr-CA": "Bonjour le monde" }
 
-// Template string translation
-const name = "John"
-const result2 = await Gringow`Hello ${name}`
-console.log(result2.translation) // { "pt-BR": "Olá João", "fr-CA": "Bonjour John" }
+// Template string with dynamic values
+const name = 'John'
+const { translation: result } = await Gringow`Welcome, ${name}!`
+console.log(result.translation)
+// => { "pt-BR": "Bem-vindo, John!", "fr-CA": "Bienvenue, John!" }
+```
+
+## Usage Examples
+
+### Basic Translation
+
+```typescript
+import Gringow from '@gringow/gringow'
+
+// Translate a static string
+const { translation } = await Gringow`Hello world`
+console.log(translation.translation['pt-BR']) // "Olá mundo"
+```
+
+### Dynamic Content
+
+```typescript
+// Template literals are flattened before hashing - dynamic values preserved
+const user = { name: 'Alice', role: 'admin' }
+const { translation } = await Gringow`User ${user.name} has ${user.role} privileges`
+
+console.log(translation.translation['pt-BR'])
+// => "Usuário Alice tem privilégios de admin"
+```
+
+### Cache Management
+
+```typescript
+import Gringow, { rebuild, checkCache } from '@gringow/gringow'
+
+const { cacheId } = await Gringow`Hello world`
+
+// Check if translation exists in cache
+const cached = await checkCache(cacheId)
+console.log(cached) // GringowCacheItem or undefined
+
+// Force re-translation by rebuilding cache entry
+const refreshed = await rebuild(cacheId)
+console.log(refreshed.translation.translation)
+```
+
+### Browser Usage
+
+For client-side interpolation without Node.js dependencies:
+
+```typescript
+import { interpolateTemplate } from '@gringow/gringow/browser'
+
+const template = 'Hello {name}, you have {count} messages'
+const result = interpolateTemplate(template, { name: 'Alice', count: 5 })
+console.log(result) // "Hello Alice, you have 5 messages"
 ```
 
 ## Configuration
 
-Create a `gringow.config.js` file in your project root:
+Gringow uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to load configuration from your project root. Supported formats: `gringow.config.js`, `gringow.config.mjs`, `gringow.config.json`, or a `gringow` field in `package.json`.
+
+### Default Configuration
+
+```js
+// gringow.config.js
+export default {
+  debug: false,
+  log: { level: 'info' },
+  cache: {
+    dir: './gringow',
+    file: 'gringow.json',
+    prefix: 'grw',
+    write: true,
+  },
+  keys: {
+    anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+    geminiApiKey: process.env.GEMINI_API_KEY,
+  },
+  sourceLanguage: 'en-US',
+  languages: ['pt-BR', 'fr-CA'],
+  llm: {
+    choice: 'huggingface', // 'huggingface' | 'anthropic' | 'gemini'
+    model: 'Xenova/nllb-200-distilled-600M',
+    temperature: 1.0,
+    sleep: 0,
+  },
+  globby: './src/**/*.{js,jsx,ts,tsx}',
+}
+```
+
+### Example: Using Gemini
 
-```javascript
+```js
+// gringow.config.js
 export default {
-  sourceLanguage: "en-US",
-  languages: ["pt-BR", "fr-CA"],
+  keys: {
+    geminiApiKey: process.env.GEMINI_API_KEY,
+  },
   llm: {
-    choice: "huggingface", // or "anthropic", "gemini"
-    model: "Xenova/nllb-200-distilled-600M"
+    choice: 'gemini',
+    model: 'gemini-2.0-flash',
+    prePromptAppend: 'Please respond in a friendly tone.',
   },
+  languages: ['es-ES', 'de-DE', 'ja-JP'],
+}
+```
+
+### Example: Using Anthropic
+
+```js
+// gringow.config.js
+export default {
   keys: {
-    // anthropicApiKey: "your-key-here", // if using Anthropic
-    // geminiApiKey: "your-key-here"     // if using Gemini
-  }
+    anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+  },
+  llm: {
+    choice: 'anthropic',
+    model: 'claude-3-5-sonnet-20241022',
+    temperature: 0.7,
+  },
+}
+```
+
+### Prompt Customization
+
+Fine-tune LLM behavior with prompt options:
+
+```js
+export default {
+  llm: {
+    choice: 'huggingface',
+    prePrompt: 'Translate the following text:', // Default prompt prefix
+    postPrompt: 'Ensure translations are natural.', // Additional context
+    prePromptAppend: 'Use formal language.', // Appended to pre-prompt
+    postPromptPrepend: 'Maintain original formatting.', // Prepended to post-prompt
+    prePromptReplace: 'Custom instruction here', // Replaces entire pre-prompt
+  },
 }
 ```
 
 ## LLM Providers
 
-- **Hugging Face** (default): Local models, no API key required
-- **Anthropic**: Requires `anthropicApiKey`
-- **Gemini**: Requires `geminiApiKey`
+### Hugging Face (Default)
+
+Runs local models via `@huggingface/transformers`. **No API key required.**
+
+```js
+// gringow.config.js
+export default {
+  llm: {
+    choice: 'huggingface',
+    model: 'Xenova/nllb-200-distilled-600M', // Multilingual translation model
+  },
+}
+```
+
+**Pros**: Free, private, offline-capable  
+**Cons**: Slower first run (model download), higher memory usage
 
-## API
+### Anthropic
 
-### Gringow(strings, ...values)
+Uses Claude models via Anthropic API. **Requires API key.**
 
-Main function for template string translation.
+```js
+// gringow.config.js
+export default {
+  keys: {
+    anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+  },
+  llm: {
+    choice: 'anthropic',
+    model: 'claude-3-5-sonnet-20241022',
+  },
+}
+```
 
-**Parameters:**
-- `strings`: TemplateStringsArray or string
-- `values`: Values for interpolation
+**Pros**: High-quality translations, fast  
+**Cons**: API costs, requires internet
 
-**Returns:** Promise<GringowResponse>
+### Gemini
 
-### GringowResponse
+Uses Google's Gemini models. **Requires API key.**
 
-```typescript
-type GringowResponse = {
-  cacheId: string
-  translation: GringowCacheItem
+```js
+// gringow.config.js
+export default {
+  keys: {
+    geminiApiKey: process.env.GEMINI_API_KEY,
+  },
+  llm: {
+    choice: 'gemini',
+    model: 'gemini-2.0-flash',
+  },
 }
+```
+
+**Pros**: Fast, cost-effective  
+**Cons**: API costs, requires internet
+
+## API Reference
+
+### Core Functions
+
+#### `Gringow(strings, ...values): Promise<GringowResponse>`
+
+Main translation function. Accepts tagged template literals or plain strings.
+
+```typescript
+const result = await Gringow`Hello ${name}`
+```
+
+**Returns**: `Promise<GringowResponse>` with `{ cacheId, translation }`
+
+#### `rebuild(cacheId: string): Promise<GringowResponse>`
+
+Re-translates a cached entry using the current LLM configuration.
+
+```typescript
+const refreshed = await rebuild('grw_abc123')
+```
+
+### Cache Helpers
+
+```typescript
+import {
+  checkCache,      // Check if cacheId exists
+  getCache,        // Get entire cache object
+  getOrCreateCache,// Get cache or create empty one
+  writeCacheToDisk,// Manually write cache entry
+  deleteCacheItem, // Remove cache entry
+  clearCache,      // Clear all cache entries
+} from '@gringow/gringow'
+```
+
+### Utilities
+
+```typescript
+import {
+  createCacheId,         // Generate cache ID from string
+  flatTemplateString,    // Flatten template literal to string
+  interpolateTemplate,   // Browser-safe interpolation (from /browser export)
+  awaitedConfig,         // Access resolved configuration
+  isLocalConfigFound,    // Check if local config exists
+  getConfigSource,       // Get config file path
+} from '@gringow/gringow'
+```
+
+### Type Definitions
+
+```typescript
+type GringowTranslation = Record<string, string>
 
 type GringowCacheItem = {
   original: string
   translation: GringowTranslation
+  append?: string
+  prepend?: string
+  rebuild?: boolean
 }
 
-type GringowTranslation = {
-  [key: string]: string
+type GringowResponse = {
+  cacheId: string
+  translation: GringowCacheItem
 }
 ```
 
+## How It Works
+
+1. **Input Processing**: Template strings are flattened to plain text (preserving dynamic values)
+2. **Cache ID Generation**: Content-based hash created using `createCacheId()`
+3. **Cache Lookup**: Check `./gringow/gringow.json` for existing translation
+4. **LLM Query**: If not cached, request translation from configured provider
+5. **Response Parsing**: Parse provider response to `GringowCacheItem` format
+6. **Cache Storage**: Write to disk when `cache.write` is `true`
+
+**Example cache structure:**
+
+```json
+{
+  "grw_a1b2c3": {
+    "original": "Hello world",
+    "translation": {
+      "pt-BR": "Olá mundo",
+      "fr-CA": "Bonjour le monde"
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm run build
+
+# Run tests
+pnpm run test
+
+# Watch mode
+pnpm run test:watch
+```
+
+## Integrations
+
+Gringow has official integrations for modern web frameworks:
+
+- **[@gringow/cli](https://www.npmjs.com/package/@gringow/gringow-cli)** - Command-line interface for cache management and translations
+- **[@gringow/gringow-vite](https://www.npmjs.com/package/@gringow/gringow-vite)** - Vite plugin for build-time translation extraction
+- **[@gringow/gringow-react](https://www.npmjs.com/package/@gringow/gringow-react)** - React hooks and components
+- **[@gringow/gringow-shadow](https://www.npmjs.com/package/@gringow/gringow-shadow)** - Web Component layer (vanilla JS)
+- **[@gringow/gringow-nextjs](https://www.npmjs.com/package/@gringow/gringow-nextjs)** - Next.js plugin (experimental)
+
+## Related Resources
+
+- [Documentation](https://gringow.dev)
+- [GitHub Repository](https://github.com/rntgspr/gringow)
+- [Examples](https://github.com/rntgspr/gringow/tree/main/example-gringow-vite)
+
 ## License
 
-MIT
+MIT © [Renato Gaspar](https://github.com/rntgspr)
+
+---
+
+**Questions or Issues?** Open an issue on [GitHub](https://github.com/rntgspr/gringow/issues)

package/dist/browser.d.mts

@@ -1,5 +1,6 @@
-export { createCacheId } from './data/create-cache-id.mjs';
+export { createCacheId } from './create-cache-id.mjs';
 export { flatTemplateString } from './flat-template-string.mjs';
+export { interpolateTemplate } from './interpolate-template.mjs';
 
 declare const GRINGOW_IO_URL = "https://gringow.io";
 

package/dist/browser.mjs

@@ -1,8 +1,52 @@
-import CryptoJS from 'crypto-js';
+// src/data/md5.ts
+var INITIAL_STATE = [1831565813, 461845907, 2246822507, 3266489909];
+var MULTIPLIERS = [668265261, 374761393, 2654435769, 2496678331];
+var AVA_MULT1 = 2146121005;
+var AVA_MULT2 = 2221713035;
+function seedState(input) {
+  const state = [...INITIAL_STATE];
+  for (const char of input) {
+    const codePoint = char.codePointAt(0) ?? 0;
+    for (let i = 0; i < state.length; i++) {
+      state[i] = Math.imul(state[i] ^ codePoint, MULTIPLIERS[i]);
+      state[i] = rotateLeft(state[i], (i + 1) * 3);
+    }
+    state[0] ^= state[3] >>> 11;
+    state[1] ^= state[0] << 7;
+    state[2] ^= state[1] >>> 13;
+    state[3] ^= state[2] << 5;
+  }
+  return state;
+}
+function rotateLeft(value, shift) {
+  return value << shift | value >>> 32 - shift;
+}
+function avalanche(value) {
+  value ^= value >>> 16;
+  value = Math.imul(value, AVA_MULT1);
+  value ^= value >>> 15;
+  value = Math.imul(value, AVA_MULT2);
+  value ^= value >>> 16;
+  return value >>> 0;
+}
+function toHex(value) {
+  return (value >>> 0).toString(16).padStart(8, "0");
+}
+function mixState([h1, h2, h3, h4]) {
+  h1 = avalanche(h1 ^ h3);
+  h2 = avalanche(h2 ^ h4);
+  h3 = avalanche(h3 ^ h1);
+  h4 = avalanche(h4 ^ h2);
+  return [h1, h2, h3, h4];
+}
+function md5(input) {
+  const state = mixState(seedState(input));
+  return state.map(toHex).join("");
+}
 
-// src/data/create-cache-id.ts
+// src/create-cache-id.ts
 function createCacheId(text) {
-  const hexHash = CryptoJS.MD5(text).toString();
+  const hexHash = md5(text);
   const cacheId = `gid_${hexHash}`;
   return cacheId;
 }
@@ -22,7 +66,20 @@ function flatTemplateString(givenStrings, givenValues) {
   return flatted;
 }
 
+// src/interpolate-template.ts
+function interpolateTemplate(template, values) {
+  if (!values || values.length === 0) return template;
+  let valueIndex = 0;
+  return template.replace(/\$\{[^}]*\}/g, () => {
+    if (valueIndex < values.length) {
+      const value = values[valueIndex++];
+      return value === null || value === void 0 ? "" : String(value);
+    }
+    return "";
+  });
+}
+
 // src/browser.ts
 var GRINGOW_IO_URL = "https://gringow.io";
 
-export { GRINGOW_IO_URL, createCacheId, flatTemplateString };
+export { GRINGOW_IO_URL, createCacheId, flatTemplateString, interpolateTemplate };

package/dist/config.d.mts

@@ -40,6 +40,7 @@ declare const awaitedConfig: Promise<{
         write?: boolean | undefined;
     };
     sourceLanguage: string;
+    defaultLanguage: string;
     languages: string[];
     llm: {
         choice: "gemini" | "anthropic" | "huggingface";

package/dist/config.mjs

@@ -18,6 +18,7 @@ var defaultConfig = {
   },
   keys: {},
   sourceLanguage: "en-US",
+  defaultLanguage: "pt-BR",
   languages: ["pt-BR", "fr-CA"],
   llm: {
     choice: "huggingface",
@@ -45,6 +46,7 @@ var configSchema = z.object({
     geminiApiKey: z.string().optional()
   }),
   sourceLanguage: languageSchema,
+  defaultLanguage: languageSchema,
   languages: z.array(languageSchema),
   llm: z.object({
     choice: llmOptionsSchema,
@@ -107,9 +109,9 @@ async function loadUserConfig() {
 var awaitedConfig = loadUserConfig();
 function defaultPrePrompt(config, extraInstructions) {
   return `
-You are a translation generator.
+You are a ultimate translation generator server api.
 
-Your task is to output **only one valid JSON object**, with **no text, explanations, or formatting outside the JSON**.
+Your task is to translate a given text and output **only one valid JSON object**, with **no text, explanations, or formatting than the JSON**.
 
 Follow these rules strictly:
 
@@ -119,7 +121,7 @@ Follow these rules strictly:
    - Apply these creatively but **without altering the meaning or punctuation** of the original text.
 3. Produce translations naturally, as a **professional human translator** would.
 4. Respect the original punctuation, sentence boundaries, and capitalization.
-5. Consider only the following target languages: ${(config?.languages ? config.languages : []).join(", ")}.
+5. Consider only the following target languages: ${(config?.languages ? Array.from(/* @__PURE__ */ new Set(["es-ES", ...config.languages, config.sourceLanguage])) : []).join(", ")}.
 6. The final output must be a **valid JSON** following this exact schema:
 
 {