vite-plugin-ai-auto-i18n 0.5.5 → 0.5.6

package/dist/index.d.ts

@@ -1,25 +1,39 @@
 import { Plugin } from "vite";
+/**
+ * What a message was extracted from: `text` for JSX text, `attribute` for a translatable attribute, `mixed` for JSX text
+ * containing expressions (which become `{name}` placeholders), and `string` for a string literal marked for translation.
+ */
 type MessageKind = "text" | "attribute" | "mixed" | "string";
+/** A translatable string found in a source file, before it has an ID. */
 interface ExtractedMessage {
+  /** The source text, with any HTML entities already decoded. */
   source: string;
+  /** Whitespace that surrounded the raw text. It is re-emitted around the translation so layout is unchanged. */
   prefix?: string;
   suffix?: string;
   kind: MessageKind;
   /** For "mixed" messages: placeholder names in the order of the element's expression children. */
   placeholders?: string[];
+  /** Source file the message was found in. */
   file: string;
+  /** Character offsets of the message in the file. */
   start: number;
   end: number;
+  /** Tag or call the message belongs to, for example `button`. */
   tag: string;
+  /** Enclosing component name. Used with `fingerprint` to match a message to its registry entry. */
   component: string;
   attribute?: string;
+  /** Position within the component, such as the enclosing element. Shown to translators as `Component > context`. */
   context: string;
+  /** Hash of the source and its location fields (kind, tag, component, attribute, context), used to match registry entries. */
   fingerprint: string;
 }
 /** A message with the stable ID that the registry assigned to it. */
 type ResolvedMessage = ExtractedMessage & {
   id: string;
 };
+/** One message remembered in the registry. Entries are kept across builds so stable IDs survive edits. */
 type RegistryEntry = Pick<ExtractedMessage, "source" | "kind" | "tag" | "component" | "attribute" | "context" | "fingerprint"> & {
   id: string;
   location: string;
@@ -27,11 +41,14 @@ type RegistryEntry = Pick<ExtractedMessage, "source" | "kind" | "tag" | "compone
   firstSeen: string;
   lastSeen: string;
 };
+/** The persisted `registry.json`: all known messages keyed by ID. `version` allows a future format change. */
 interface Registry {
   version: 1;
   entries: Record<string, RegistryEntry>;
 }
+/** Maps message IDs to text. */
 type Catalog = Record<string, string>;
+/** A message that needs a translation, as sent to a provider. */
 interface TranslationRequest {
   id: string;
   source: string;
@@ -39,6 +56,10 @@ interface TranslationRequest {
   kind: MessageKind;
   placeholders?: string[];
 }
+/**
+ * Translates a batch of messages into one target locale. Return a catalogue with a key for each message that was
+ * translated. Missing keys are left untranslated. Throw a `PartialTranslationError` to keep the keys already done.
+ */
 interface TranslationProvider {
   translate(input: {
     sourceLocale: string;
@@ -62,6 +83,7 @@ export declare class PartialTranslationError extends Error {
   readonly failed: number;
   constructor(message: string, partial: Catalog, failed: number);
 }
+/** A provider paired with the name used to refer to it in configuration and log messages. */
 interface NamedProvider {
   name: string;
   provider: TranslationProvider;
@@ -70,6 +92,9 @@ interface NamedProvider {
  * Tries providers in order. Messages a provider did not translate (a failed request, or a partial result) are sent
  * to the next provider. Throws only when nothing could be translated, or a PartialTranslationError when some messages
  * are still missing after every provider has been tried.
+ *
+ * @param providers Providers in the order they should be tried.
+ * @param onFallback Called with a human-readable message each time a provider hands work to the next one.
  */
 export declare class FallbackProvider implements TranslationProvider {
   private readonly providers;
@@ -83,8 +108,14 @@ export declare class FallbackProvider implements TranslationProvider {
 }
 /**
  * Normalizes the `provider` option to one provider. Returns undefined when no provider is configured.
+ *
+ * A single provider (or a bare provider object) is returned as is. A named map is validated, ordered so that `primary`
+ * comes first, and wrapped in a {@link FallbackProvider} when it holds more than one entry.
+ *
+ * @throws If an entry is not a provider, or `primary` names a provider that is not configured.
  */
 export declare function resolveProvider(config: ProviderConfig | undefined, onFallback?: (message: string) => void): TranslationProvider | undefined;
+/** Tuning options shared by every HTTP provider that sends messages in batches. */
 interface BatchedProviderOptions {
   /** Messages sent per request. Smaller batches keep responses within output limits. Default 40. */
   batchSize?: number;
@@ -97,6 +128,7 @@ interface BatchedProviderOptions {
   /** Batches sent in parallel. Default 4. */
   concurrency?: number;
 }
+/** One translation call: the locale pair and the messages to translate between them. */
 interface TranslateInput {
   sourceLocale: string;
   targetLocale: string;
@@ -114,38 +146,61 @@ declare abstract class BatchedProvider<O extends BatchedProviderOptions> impleme
    * a PartialTranslationError carries the translations that succeeded.
    */
   translate(input: TranslateInput): Promise<Catalog>;
+  /**
+   * Runs one batch, retrying retryable failures with exponential backoff (`retryDelayMs * 2^attempt`, jittered)
+   * up to `maxRetries` extra attempts. Non-retryable errors are rethrown immediately.
+   */
   private translateBatch;
   /** Sends one batch to the provider and returns the translations it produced for the requested IDs. */
   protected abstract request(input: TranslateInput): Promise<Catalog>;
   /** Parses the model's text reply, which must be a JSON object mapping IDs to strings. */
   protected toCatalog(content: string | undefined, messages: TranslationRequest[]): Catalog;
 }
+/** Options for an OpenAI or OpenAI-compatible chat completions endpoint. */
 interface OpenAICompatibleOptions extends BatchedProviderOptions {
   apiKey: string;
   model: string;
+  /** Overrides the API root, for example to target a proxy or a self-hosted compatible server. */
   baseURL?: string;
 }
+/**
+ * Translates batches through the `/chat/completions` endpoint. Requests use JSON mode so the reply is a parseable
+ * object of translations.
+ */
 export declare class OpenAICompatibleProvider extends BatchedProvider<OpenAICompatibleOptions> {
   protected request(input: TranslateInput): Promise<Catalog>;
 }
+/** Options for the Anthropic Messages API. */
 interface AnthropicOptions extends BatchedProviderOptions {
   apiKey: string;
   model: string;
+  /** Overrides the API root, for example to target a proxy. */
   baseURL?: string;
   /** Maximum tokens the model may generate per batch. Default 8192. */
   maxTokens?: number;
 }
+/**
+ * Translates batches through the Anthropic Messages API. The reply's text blocks are joined before parsing.
+ */
 export declare class AnthropicProvider extends BatchedProvider<AnthropicOptions> {
+  /** Sends one batch and parses the model's text reply; a surrounding Markdown code fence is stripped first. */
   protected request(input: TranslateInput): Promise<Catalog>;
 }
+/** Options for the Gemini `generateContent` API. */
 interface GeminiOptions extends BatchedProviderOptions {
   apiKey: string;
   model: string;
+  /** Overrides the API root, for example to target a proxy. */
   baseURL?: string;
   /** Maximum tokens the model may generate per batch. Default 8192. */
   maxOutputTokens?: number;
 }
+/**
+ * Translates batches through the Gemini `generateContent` API. The system prompt goes in `systemInstruction`, and
+ * `responseMimeType` requests JSON output.
+ */
 export declare class GeminiProvider extends BatchedProvider<GeminiOptions> {
+  /** Sends one batch and parses the first candidate's text; a surrounding Markdown code fence is stripped first. */
   protected request(input: TranslateInput): Promise<Catalog>;
 }
 export interface AutoI18nOptions {
@@ -188,5 +243,15 @@ export interface AutoI18nOptions {
   /** Text of the block comment that marks a string literal for translation. Default `i18n`. */
   stringMarker?: string;
 }
+/**
+ * Vite plugin that extracts translatable strings from source files, translates them and serves the catalogues.
+ * Options are validated and the provider is resolved immediately, so a bad configuration throws before the build starts.
+ *
+ * @example
+ * ```ts
+ * import autoI18n from "vite-plugin-ai-i18n";
+ * export default defineConfig({ plugins: [autoI18n({ locales: ["en", "de"] })] });
+ * ```
+ */
 export default function autoI18n(options: AutoI18nOptions): Plugin;
 export type { AnthropicOptions, Catalog, ExtractedMessage, GeminiOptions, MessageKind, OpenAICompatibleOptions, ProviderConfig, Registry, RegistryEntry, ResolvedMessage, TranslationProvider, TranslationRequest };

package/dist/runtime/index.d.ts

@@ -2,8 +2,14 @@
  * Picks the best supported locale for a list of preferred locales (for example `navigator.languages`).
  * This function is also embedded into the generated `virtual:autoi18n` module via `toString()`,
  * so it must stay self-contained and must not reference anything outside its body.
+ *
+ * @param preferred Locales in priority order, such as `navigator.languages`.
+ * @param supported Locales the app has catalogues for.
+ * @param fallback Returned when no preferred locale matches.
+ * @returns The supported locale that matches first, preferring an exact match over a same-language match.
  */
 export declare function resolveLocale(preferred: string[], supported: string[], fallback?: string): string;
+/** Lazily imports one locale's catalogue. Resolves to a module whose default export, or the object itself, is the catalogue. */
 type LocaleLoader = () => Promise<{
   default: Record<string, string>;
 } | Record<string, string>>;
@@ -11,6 +17,10 @@ type LocaleLoader = () => Promise<{
  * Returns a cached catalogue loader. Unknown locales load the fallback, and a failed load is not cached.
  * `prime` stores a catalogue that was already fetched, such as one pushed by the dev server.
  * Serialised into the runtime module via toString(), so it must not reference anything outside its body.
+ *
+ * @param loaders Loader for each supported locale, keyed by locale code.
+ * @param fallback Locale loaded when the requested one has no loader.
+ * @returns A function that resolves a locale to its catalogue, with a `prime(locale, catalog)` method.
  */
 export declare function createLocaleLoader(loaders: Record<string, LocaleLoader>, fallback?: string): {
   (locale: string): Promise<Record<string, string>>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vite-plugin-ai-auto-i18n",
-    "version": "0.5.5",
+    "version": "0.5.6",
     "type": "module",
     "description": "Implicit, build-time AI localization for JSX applications",
     "license": "ISC",