translate-kit 0.1.0 → 0.2.0

package/README.md

@@ -1,37 +1,58 @@
 # translate-kit
 
-AI-powered translation SDK for build time. No intermediaries, no vendor lock-in.
+AI-powered i18n for your codebase. Scan, transform, and translate — at build time.
 
 [![npm version](https://img.shields.io/npm/v/translate-kit.svg)](https://www.npmjs.com/package/translate-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![CI](https://github.com/guillermolg00/translate-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/guillermolg00/translate-kit/actions/workflows/ci.yml)
 
-Uses your own AI models via [Vercel AI SDK](https://sdk.vercel.ai/) to translate your app at build time. Compatible with [next-intl](https://next-intl.dev/).
+translate-kit extracts translatable strings from your JSX/TSX, generates semantic keys with AI, replaces hardcoded text with i18n calls, and translates everything to your target locales — using your own AI models via [Vercel AI SDK](https://sdk.vercel.ai/). Compatible with [next-intl](https://next-intl.dev/).
+
+**[Documentation](https://translate-kit.com/docs)** · **[Getting Started](https://translate-kit.com/docs/getting-started)** · **[Configuration](https://translate-kit.com/docs/configuration)**
+
+---
 
 ## Features
 
-- **Build-time AI translation** — translate JSON message files using any AI model
-- **Incremental** — only new or modified keys get translated via a lock file system
-- **Any provider** — OpenAI, Anthropic, Google, Mistral, Groq, or any Vercel AI SDK provider
-- **Scanner** — extract translatable strings from JSX/TSX source code automatically
-- **Codegen** — replace hardcoded strings with `t()` calls and inject imports/hooks
+- **Build-time AI translation** — no runtime overhead, translations are generated at build time
+- **Incremental** — lock file tracks source hashes, re-runs only translate what changed
+- **Any AI provider** — OpenAI, Anthropic, Google, Mistral, Groq, or any Vercel AI SDK provider
+- **Scanner** — extract translatable strings from JSX/TSX using Babel AST analysis
+- **Codegen** — replace hardcoded strings with `t()` calls or `<T>` components automatically
+- **Two modes** — keys mode (`t("key")`) or inline mode (`<T id="key">text</T>`)
 - **next-intl ready** — generates `useTranslations`-compatible message files
 
 ## Quick Start
 
 ```bash
-# Install
-npm install translate-kit @ai-sdk/openai
-# or
+# Install translate-kit and an AI provider
 bun add translate-kit @ai-sdk/openai
 
-# Create config
-npx translate-kit init
+# Interactive setup
+bunx translate-kit init
 
 # Translate
-npx translate-kit translate
+bunx translate-kit translate
 ```
 
+The `init` wizard creates your config, sets up locales, and optionally runs the full pipeline.
+
+> See the full [Getting Started](https://translate-kit.com/docs/getting-started) guide for detailed setup instructions.
+
+## How It Works
+
+```
+scan → codegen → translate
+```
+
+| Step | What it does |
+|------|-------------|
+| **scan** | Parses JSX/TSX files, extracts translatable strings, generates semantic keys via AI |
+| **codegen** | Replaces hardcoded strings with `t("key")` calls or `<T>` components, injects imports |
+| **translate** | Diffs source messages against lock file, translates only new/modified keys |
+
+You can use any step independently. The `translate` command is the most commonly used on its own — write your source messages and let translate-kit handle the rest.
+
 ## Configuration
 
 ```ts
@@ -42,113 +63,125 @@ import { openai } from "@ai-sdk/openai";
 export default defineConfig({
   model: openai("gpt-4o-mini"),
   sourceLocale: "en",
-  targetLocales: ["es", "fr", "de"],
+  targetLocales: ["es", "fr", "de", "ja"],
   messagesDir: "./messages",
-
-  translation: {
-    batchSize: 50,
-    concurrency: 3,
-    context: "SaaS application for project management",
-    glossary: { Acme: "Acme" },
-    tone: "professional",
-    retries: 2,
-  },
-
-  scan: {
-    include: ["src/**/*.tsx", "app/**/*.tsx"],
-    exclude: ["**/*.test.*"],
-    keyStrategy: "hash",
-    translatableProps: ["placeholder", "title", "alt", "aria-label"],
-    i18nImport: "next-intl",
-  },
 });
 ```
 
-## Commands
+> See the full [Configuration reference](https://translate-kit.com/docs/configuration) for all options including translation context, glossary, tone, batching, and scanner settings.
 
-### `translate-kit translate`
+## Two Modes
 
-Translate messages to all target locales.
+### Keys mode (default)
 
-```bash
-translate-kit translate              # Translate all locales
-translate-kit translate --locale es  # Only Spanish
-translate-kit translate --dry-run    # Preview without translating
-translate-kit translate --force      # Re-translate everything
-translate-kit translate --verbose    # Verbose output
+Hardcoded strings are replaced with `t("key")` calls. Source text lives in JSON files.
+
+```tsx
+// Before
+<h1>Welcome back</h1>
+
+// After
+<h1>{t("hero.welcomeBack")}</h1>
 ```
 
-### `translate-kit scan`
+### Inline mode
 
-Scan source code for translatable strings (JSX text, attributes, object properties).
+Source text stays visible in your code. A `<T>` component handles runtime resolution.
 
-```bash
-translate-kit scan           # Scan and write to source locale file
-translate-kit scan --dry-run # Preview found strings
+```tsx
+// Before
+<h1>Welcome back</h1>
+
+// After
+<h1><T id="hero.welcomeBack">Welcome back</T></h1>
 ```
 
-### `translate-kit codegen`
+> See the [Inline Mode](https://translate-kit.com/docs/guides/inline-mode) guide for setup and usage.
 
-Replace hardcoded strings with `t()` calls and inject `useTranslations` imports.
+## AI Providers
+
+Any [Vercel AI SDK](https://sdk.vercel.ai/) provider works. Install the provider package and set your API key:
 
 ```bash
-translate-kit codegen           # Transform source files
-translate-kit codegen --dry-run # Preview changes
+bun add @ai-sdk/openai       # OpenAI
+bun add @ai-sdk/anthropic    # Anthropic
+bun add @ai-sdk/google       # Google
+bun add @ai-sdk/mistral      # Mistral
+bun add @ai-sdk/groq         # Groq
 ```
 
-### `translate-kit init`
+```ts
+import { openai } from "@ai-sdk/openai";       // model: openai("gpt-4o-mini")
+import { anthropic } from "@ai-sdk/anthropic";  // model: anthropic("claude-sonnet-4-20250514")
+import { google } from "@ai-sdk/google";        // model: google("gemini-2.0-flash")
+```
 
-Interactive setup wizard. Creates a config file, optionally scaffolds next-intl integration, and can run the full pipeline (scan → codegen → translate).
+> See the [AI Providers](https://translate-kit.com/docs/guides/providers) guide for all providers and recommended models.
 
-## How It Works
+## Commands
 
-```
-scan → codegen → translate
+### `translate-kit init`
+
+Interactive setup wizard. Creates config, scaffolds i18n integration, and optionally runs the full pipeline.
+
+```bash
+bunx translate-kit init
 ```
 
-1. **Scan** — parse JSX/TSX files with Babel, extract translatable strings, generate semantic keys via AI, write source locale JSON
-2. **Codegen** — replace hardcoded strings with `t("key")` calls, add `useTranslations` imports and hooks
-3. **Translate** — diff source messages against lock file, translate only new/modified keys, write target locale JSONs
+### `translate-kit scan`
 
-Only changed keys are sent to the AI. A `.translate-lock.json` file tracks source hashes so re-runs are fast and cheap.
+Extracts translatable strings from your source code and generates semantic keys with AI.
 
-## AI Providers
+```bash
+bunx translate-kit scan           # Scan and generate keys
+bunx translate-kit scan --dry-run # Preview found strings
+```
 
-translate-kit works with any provider supported by Vercel AI SDK:
+### `translate-kit codegen`
 
-```ts
-import { openai } from "@ai-sdk/openai";
-import { anthropic } from "@ai-sdk/anthropic";
-import { google } from "@ai-sdk/google";
-import { mistral } from "@ai-sdk/mistral";
+Replaces hardcoded strings with i18n calls and injects imports/hooks.
 
-// OpenAI
-model: openai("gpt-4o-mini")
+```bash
+bunx translate-kit codegen           # Transform source files
+bunx translate-kit codegen --dry-run # Preview changes
+```
 
-// Anthropic
-model: anthropic("claude-sonnet-4-20250514")
+### `translate-kit translate`
 
-// Google
-model: google("gemini-2.0-flash")
+Translates messages to all target locales. Only new or modified keys are sent to the AI.
 
-// Mistral
-model: mistral("mistral-large-latest")
+```bash
+bunx translate-kit translate              # Translate all locales
+bunx translate-kit translate --locale es  # Only Spanish
+bunx translate-kit translate --dry-run    # Preview what would be translated
+bunx translate-kit translate --force      # Ignore cache, re-translate everything
 ```
 
-## Scanner
+> See the [Commands](https://translate-kit.com/docs/commands/init) documentation for detailed usage and flags.
+
+## Incremental Translations
+
+A `.translate-lock.json` file stores SHA-256 hashes of source values. On each run, translate-kit computes a diff:
+
+- **Added** — new keys, not yet translated
+- **Modified** — source text changed since last translation
+- **Unchanged** — hash matches, skipped
+- **Removed** — keys no longer in source, cleaned up
 
-The scanner extracts translatable strings from your source code:
+Only added and modified keys are sent to the AI. This keeps API calls fast and costs low.
 
-- **JSX text** — `<h1>Welcome</h1>`
-- **JSX attributes** — `<input placeholder="Enter name" />`
-- **Expression containers** — `<div>{"Hello"}</div>`
-- **Object properties** — `{ title: "Dashboard" }`
+> See the [Incremental Translations](https://translate-kit.com/docs/guides/incremental) guide for details.
 
-It automatically filters out non-translatable content like URLs, CSS classes, constants, and code identifiers. Keys are generated using AI for semantic, namespace-style naming (`common.save`, `nav.dashboard`, `form.enterName`).
+## Documentation
 
-## Docs
+Full documentation is available at **[translate-kit.com](https://translate-kit.com/docs)**.
 
-Full documentation available at [translate-kit.vercel.app](https://translate-kit.vercel.app).
+- [Getting Started](https://translate-kit.com/docs/getting-started)
+- [Configuration](https://translate-kit.com/docs/configuration)
+- [AI Providers](https://translate-kit.com/docs/guides/providers)
+- [Inline Mode](https://translate-kit.com/docs/guides/inline-mode)
+- [Incremental Translations](https://translate-kit.com/docs/guides/incremental)
+- [next-intl Integration](https://translate-kit.com/docs/guides/next-intl)
 
 ## License