poly-lexis 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -33,11 +33,112 @@ interface ValidationResult {
 declare const DEFAULT_CONFIG: Required<TranslationConfig>;
 declare const DEFAULT_LANGUAGES: readonly ["en", "fr", "it", "pl", "es", "pt", "de", "de_at", "nl", "sv", "hu", "cs", "ja", "zh_hk"];
 
+interface AddKeyOptions {
+    /** Namespace for the translation key */
+    namespace: string;
+    /** Translation key */
+    key: string;
+    /** Translation value (English) */
+    value: string;
+    /** Auto-translate to all languages */
+    autoTranslate?: boolean;
+    /** Google Translate API key */
+    apiKey?: string;
+}
+/**
+ * Add a new translation key to all languages
+ */
+declare function addTranslationKey(projectRoot: string, options: AddKeyOptions): Promise<void>;
+/**
+ * Add multiple translation keys at once
+ */
+declare function addTranslationKeys(projectRoot: string, entries: TranslationEntry[], autoTranslate?: boolean, apiKey?: string): Promise<void>;
+
+interface AutoFillOptions {
+    /** Language to fill translations for */
+    language?: string;
+    /** Google Translate API key */
+    apiKey?: string;
+    /** Maximum number of translations to process */
+    limit?: number;
+    /** Delay between translations in milliseconds */
+    delayMs?: number;
+    /** Dry run - don't actually write translations */
+    dryRun?: boolean;
+}
+/**
+ * Automatically fill empty or missing translations for a language
+ */
+declare function autoFillTranslations(projectRoot?: string, options?: AutoFillOptions): Promise<void>;
+/**
+ * Fill translations for a specific namespace and language
+ */
+declare function fillNamespace(projectRoot: string, language: string, namespace: string, apiKey: string): Promise<void>;
+
+/**
+ * Generate TypeScript types from translation files
+ */
+declare function generateTranslationTypes(projectRoot?: string): void;
+
+/**
+ * Detect existing translation structure in common locations
+ */
+declare function detectExistingTranslations(projectRoot: string): {
+    path: string | null;
+    languages: string[];
+};
+/**
+ * Initialize translation structure for a project
+ */
+declare function initTranslations(projectRoot: string, config?: TranslationConfig): void;
+/**
+ * Load translation configuration from .translationsrc.json
+ */
+declare function loadConfig(projectRoot: string): Required<TranslationConfig>;
+
+/**
+ * Interactive initialization of translation structure
+ */
+declare function initTranslationsInteractive(projectRoot?: string): Promise<void>;
+
+interface ManageTranslationsOptions {
+    /** Auto-fill missing translations */
+    autoFill?: boolean;
+    /** Google Translate API key for auto-fill */
+    apiKey?: string;
+    /** Maximum translations to fill */
+    limit?: number;
+    /** Specific language to process */
+    language?: string;
+    /** Skip type generation */
+    skipTypes?: boolean;
+    /** Dry run mode */
+    dryRun?: boolean;
+}
+/**
+ * Smart translation management - handles init, validation, auto-fill, and type generation
+ * based on the current state of the project
+ */
+declare function manageTranslations(projectRoot?: string, options?: ManageTranslationsOptions): Promise<void>;
+
+/**
+ * Validate all translations against the source language
+ * Checks for missing keys and empty values
+ */
+declare function validateTranslations(projectRoot?: string): ValidationResult;
+/**
+ * Get all missing or empty translations for a specific language
+ */
+declare function getMissingForLanguage(projectRoot: string, language: string): Array<MissingTranslation & {
+    type: 'missing' | 'empty';
+}>;
+
 /**
  * Supported language codes for translations
- * Based on ISO 639-1 and regional variants
+ * Based on Google Translate API supported languages (ISO 639-1 and regional variants)
+ * Complete list of all languages supported by Google Cloud Translation API
  */
-declare const SUPPORTED_LANGUAGES: readonly ["en", "fr", "it", "pl", "es", "pt", "de", "de_at", "nl", "sv", "hu", "cs", "ja", "zh_hk", "zh_cn", "ko", "ru", "ar", "he", "tr", "da", "fi", "no", "pt_br"];
+declare const SUPPORTED_LANGUAGES: readonly ["af", "sq", "am", "ar", "hy", "as", "ay", "az", "bm", "eu", "be", "bn", "bho", "bs", "bg", "ca", "ceb", "ny", "zh", "zh_cn", "zh_tw", "co", "hr", "cs", "da", "dv", "doi", "nl", "en", "eo", "et", "ee", "tl", "fi", "fr", "gl", "ka", "de", "el", "gn", "gu", "ht", "ha", "haw", "iw", "he", "hi", "hmn", "hu", "is", "ig", "ilo", "id", "ga", "it", "ja", "jw", "kn", "kk", "km", "rw", "gom", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "lg", "lb", "mk", "mai", "mg", "ms", "ml", "mt", "mi", "mr", "mni", "lus", "mn", "my", "ne", "no", "or", "om", "ps", "fa", "pl", "pt", "pt_br", "pa", "qu", "ro", "ru", "sm", "sa", "gd", "sr", "st", "sn", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "ts", "tr", "tk", "ak", "uk", "ur", "ug", "uz", "vi", "cy", "xh", "yi", "yo", "zu"];
 type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
 /**
  * JSON Schema for .translationsrc.json
@@ -58,7 +159,7 @@ declare const TRANSLATION_CONFIG_SCHEMA: {
             description: string;
             items: {
                 type: string;
-                enum: readonly ["en", "fr", "it", "pl", "es", "pt", "de", "de_at", "nl", "sv", "hu", "cs", "ja", "zh_hk", "zh_cn", "ko", "ru", "ar", "he", "tr", "da", "fi", "no", "pt_br"];
+                enum: readonly ["af", "sq", "am", "ar", "hy", "as", "ay", "az", "bm", "eu", "be", "bn", "bho", "bs", "bg", "ca", "ceb", "ny", "zh", "zh_cn", "zh_tw", "co", "hr", "cs", "da", "dv", "doi", "nl", "en", "eo", "et", "ee", "tl", "fi", "fr", "gl", "ka", "de", "el", "gn", "gu", "ht", "ha", "haw", "iw", "he", "hi", "hmn", "hu", "is", "ig", "ilo", "id", "ga", "it", "ja", "jw", "kn", "kk", "km", "rw", "gom", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "lg", "lb", "mk", "mai", "mg", "ms", "ml", "mt", "mi", "mr", "mni", "lus", "mn", "my", "ne", "no", "or", "om", "ps", "fa", "pl", "pt", "pt_br", "pa", "qu", "ro", "ru", "sm", "sa", "gd", "sr", "st", "sn", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "ts", "tr", "tk", "ak", "uk", "ur", "ug", "uz", "vi", "cy", "xh", "yi", "yo", "zu"];
             };
             minItems: number;
             uniqueItems: boolean;
@@ -66,7 +167,7 @@ declare const TRANSLATION_CONFIG_SCHEMA: {
         sourceLanguage: {
             type: string;
             description: string;
-            enum: readonly ["en", "fr", "it", "pl", "es", "pt", "de", "de_at", "nl", "sv", "hu", "cs", "ja", "zh_hk", "zh_cn", "ko", "ru", "ar", "he", "tr", "da", "fi", "no", "pt_br"];
+            enum: readonly ["af", "sq", "am", "ar", "hy", "as", "ay", "az", "bm", "eu", "be", "bn", "bho", "bs", "bg", "ca", "ceb", "ny", "zh", "zh_cn", "zh_tw", "co", "hr", "cs", "da", "dv", "doi", "nl", "en", "eo", "et", "ee", "tl", "fi", "fr", "gl", "ka", "de", "el", "gn", "gu", "ht", "ha", "haw", "iw", "he", "hi", "hmn", "hu", "is", "ig", "ilo", "id", "ga", "it", "ja", "jw", "kn", "kk", "km", "rw", "gom", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "lg", "lb", "mk", "mai", "mg", "ms", "ml", "mt", "mi", "mr", "mni", "lus", "mn", "my", "ne", "no", "or", "om", "ps", "fa", "pl", "pt", "pt_br", "pa", "qu", "ro", "ru", "sm", "sa", "gd", "sr", "st", "sn", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "ts", "tr", "tk", "ak", "uk", "ur", "ug", "uz", "vi", "cy", "xh", "yi", "yo", "zu"];
             default: string;
         };
         typesOutputPath: {
@@ -91,154 +192,156 @@ declare function validateLanguages(languages: string[]): {
 };
 
 /**
- * Read all translation files for a specific language
+ * Translation provider interface
+ * Implement this interface to create custom translation providers
  */
-declare function readTranslations(translationsPath: string, language: string): TranslationFiles;
 /**
- * Write translation file for a specific language and namespace
- */
-declare function writeTranslation(translationsPath: string, language: string, namespace: string, translations: TranslationFile): void;
-/**
- * Get all available languages from the translations directory
- */
-declare function getAvailableLanguages(translationsPath: string): string[];
-/**
- * Get all namespaces for a specific language
+ * Options for translating text
  */
-declare function getNamespaces(translationsPath: string, language: string): string[];
+interface TranslateOptions {
+    /** The text to translate */
+    text: string;
+    /** Source language code (e.g., 'en', 'fr') */
+    sourceLang: string;
+    /** Target language code (e.g., 'es', 'pt_BR') */
+    targetLang: string;
+    /** API key or credentials (optional, depending on provider) */
+    apiKey?: string;
+    /** Additional provider-specific options */
+    [key: string]: unknown;
+}
 /**
- * Check if a string contains interpolation variables (e.g., {{variable}})
+ * Result of a translation operation
  */
-declare function hasInterpolation(text: string): boolean;
+interface TranslationResult {
+    /** The translated text */
+    translatedText: string;
+    /** Optional metadata from the translation service */
+    metadata?: Record<string, unknown>;
+}
 /**
- * Extract interpolation variable names from a string
+ * Translation provider interface
+ * All custom translation providers must implement this interface
  */
-declare function extractVariables(text: string): string[];
+interface TranslationProvider {
+    /**
+     * Translate a single text string
+     * @param options - Translation options
+     * @returns Promise resolving to the translated text
+     */
+    translate(options: TranslateOptions): Promise<string>;
+    /**
+     * Translate multiple texts in batch
+     * @param texts - Array of texts to translate
+     * @param sourceLang - Source language code
+     * @param targetLang - Target language code
+     * @param apiKey - API key or credentials (optional)
+     * @param delayMs - Optional delay between requests to avoid rate limiting
+     * @returns Promise resolving to array of translated texts
+     */
+    translateBatch(texts: string[], sourceLang: string, targetLang: string, apiKey?: string, delayMs?: number): Promise<string[]>;
+    /**
+     * Optional method to validate the provider configuration
+     * @returns Promise resolving to true if configuration is valid
+     */
+    validateConfig?(): Promise<boolean>;
+}
 /**
- * Validate that translated text has the same variables as source text
+ * Type for a function that creates a translation provider
  */
-declare function validateVariables(sourceText: string, translatedText: string): boolean;
+type TranslationProviderFactory = () => TranslationProvider;
+
 /**
- * Sort object keys alphabetically
+ * Google Translate provider implementation
+ * Uses Google Cloud Translation API v2
  */
-declare function sortKeys<T extends Record<string, unknown>>(obj: T): T;
+
 /**
- * Ensure translations path exists and has proper structure
+ * Google Translate provider
+ * Implements the TranslationProvider interface
  */
-declare function ensureTranslationsStructure(translationsPath: string, languages: string[]): void;
+declare class GoogleTranslateProvider implements TranslationProvider {
+    translate(options: TranslateOptions): Promise<string>;
+    translateBatch(texts: string[], sourceLang: string, targetLang: string, apiKey?: string, delayMs?: number): Promise<string[]>;
+    validateConfig(): Promise<boolean>;
+}
 
 /**
- * Translation utilities for translating text using Google Translate API
+ * Translation utilities with support for custom translation providers
  * Only translates content outside of {{variable}} interpolations
  */
+
 /**
- * Translate text using Google Translate API
- * Preserves {{variable}} interpolations by temporarily replacing them
+ * Set a custom translation provider
+ * @param provider - Custom translation provider implementing TranslationProvider interface
  */
-declare function translateText(text: string, targetLang: string, sourceLang?: string, apiKey?: string): Promise<string>;
+declare function setTranslationProvider(provider: TranslationProvider): void;
 /**
- * Translate multiple texts in batch
+ * Get the active translation provider (custom or default)
  */
-declare function translateBatch(texts: string[], targetLang: string, sourceLang?: string, apiKey?: string, delayMs?: number): Promise<string[]>;
-
+declare function getTranslationProvider(): TranslationProvider;
 /**
- * Detect existing translation structure in common locations
+ * Reset to the default Google Translate provider
  */
-declare function detectExistingTranslations(projectRoot: string): {
-    path: string | null;
-    languages: string[];
-};
+declare function resetTranslationProvider(): void;
 /**
- * Initialize translation structure for a project
+ * Translate text using the active translation provider
+ * Preserves {{variable}} interpolations by temporarily replacing them
+ *
+ * @param text - Text to translate
+ * @param targetLang - Target language code
+ * @param sourceLang - Source language code (default: "en")
+ * @param apiKey - API key for the translation service
+ * @returns Promise resolving to translated text
  */
-declare function initTranslations(projectRoot: string, config?: TranslationConfig): void;
+declare function translateText(text: string, targetLang: string, sourceLang?: string, apiKey?: string): Promise<string>;
 /**
- * Load translation configuration from .translationsrc.json
+ * Translate multiple texts in batch
+ *
+ * @param texts - Array of texts to translate
+ * @param targetLang - Target language code
+ * @param sourceLang - Source language code (default: "en")
+ * @param apiKey - API key for the translation service
+ * @param delayMs - Delay between requests in milliseconds (default: 100)
+ * @returns Promise resolving to array of translated texts
  */
-declare function loadConfig(projectRoot: string): Required<TranslationConfig>;
+declare function translateBatch(texts: string[], targetLang: string, sourceLang?: string, apiKey?: string, delayMs?: number): Promise<string[]>;
 
 /**
- * Interactive initialization of translation structure
+ * Read all translation files for a specific language
  */
-declare function initTranslationsInteractive(projectRoot?: string): Promise<void>;
-
-interface AddKeyOptions {
-    /** Namespace for the translation key */
-    namespace: string;
-    /** Translation key */
-    key: string;
-    /** Translation value (English) */
-    value: string;
-    /** Auto-translate to all languages */
-    autoTranslate?: boolean;
-    /** Google Translate API key */
-    apiKey?: string;
-}
+declare function readTranslations(translationsPath: string, language: string): TranslationFiles;
 /**
- * Add a new translation key to all languages
+ * Write translation file for a specific language and namespace
  */
-declare function addTranslationKey(projectRoot: string, options: AddKeyOptions): Promise<void>;
+declare function writeTranslation(translationsPath: string, language: string, namespace: string, translations: TranslationFile): void;
 /**
- * Add multiple translation keys at once
+ * Get all available languages from the translations directory
  */
-declare function addTranslationKeys(projectRoot: string, entries: TranslationEntry[], autoTranslate?: boolean, apiKey?: string): Promise<void>;
-
+declare function getAvailableLanguages(translationsPath: string): string[];
 /**
- * Validate all translations against the source language
- * Checks for missing keys and empty values
+ * Get all namespaces for a specific language
  */
-declare function validateTranslations(projectRoot?: string): ValidationResult;
+declare function getNamespaces(translationsPath: string, language: string): string[];
 /**
- * Get all missing or empty translations for a specific language
+ * Check if a string contains interpolation variables (e.g., {{variable}})
  */
-declare function getMissingForLanguage(projectRoot: string, language: string): Array<MissingTranslation & {
-    type: 'missing' | 'empty';
-}>;
-
-interface AutoFillOptions {
-    /** Language to fill translations for */
-    language?: string;
-    /** Google Translate API key */
-    apiKey?: string;
-    /** Maximum number of translations to process */
-    limit?: number;
-    /** Delay between translations in milliseconds */
-    delayMs?: number;
-    /** Dry run - don't actually write translations */
-    dryRun?: boolean;
-}
+declare function hasInterpolation(text: string): boolean;
 /**
- * Automatically fill empty or missing translations for a language
+ * Extract interpolation variable names from a string
  */
-declare function autoFillTranslations(projectRoot?: string, options?: AutoFillOptions): Promise<void>;
+declare function extractVariables(text: string): string[];
 /**
- * Fill translations for a specific namespace and language
+ * Validate that translated text has the same variables as source text
  */
-declare function fillNamespace(projectRoot: string, language: string, namespace: string, apiKey: string): Promise<void>;
-
+declare function validateVariables(sourceText: string, translatedText: string): boolean;
 /**
- * Generate TypeScript types from translation files
+ * Sort object keys alphabetically
  */
-declare function generateTranslationTypes(projectRoot?: string): void;
-
-interface ManageTranslationsOptions {
-    /** Auto-fill missing translations */
-    autoFill?: boolean;
-    /** Google Translate API key for auto-fill */
-    apiKey?: string;
-    /** Maximum translations to fill */
-    limit?: number;
-    /** Specific language to process */
-    language?: string;
-    /** Skip type generation */
-    skipTypes?: boolean;
-    /** Dry run mode */
-    dryRun?: boolean;
-}
+declare function sortKeys<T extends Record<string, unknown>>(obj: T): T;
 /**
- * Smart translation management - handles init, validation, auto-fill, and type generation
- * based on the current state of the project
+ * Ensure translations path exists and has proper structure
  */
-declare function manageTranslations(projectRoot?: string, options?: ManageTranslationsOptions): Promise<void>;
+declare function ensureTranslationsStructure(translationsPath: string, languages: string[]): void;
 
-export { DEFAULT_CONFIG, DEFAULT_LANGUAGES, type ManageTranslationsOptions, type MissingTranslation, SUPPORTED_LANGUAGES, type SupportedLanguage, TRANSLATION_CONFIG_SCHEMA, type TranslationConfig, type TranslationEntry, type TranslationFile, type TranslationFiles, type ValidationResult, addTranslationKey, addTranslationKeys, autoFillTranslations, detectExistingTranslations, ensureTranslationsStructure, extractVariables, fillNamespace, generateTranslationTypes, getAvailableLanguages, getMissingForLanguage, getNamespaces, hasInterpolation, initTranslations, initTranslationsInteractive, isValidLanguage, loadConfig, manageTranslations, readTranslations, sortKeys, translateBatch, translateText, validateLanguages, validateTranslations, validateVariables, writeTranslation };
+export { DEFAULT_CONFIG, DEFAULT_LANGUAGES, GoogleTranslateProvider, type ManageTranslationsOptions, type MissingTranslation, SUPPORTED_LANGUAGES, type SupportedLanguage, TRANSLATION_CONFIG_SCHEMA, type TranslateOptions, type TranslationConfig, type TranslationEntry, type TranslationFile, type TranslationFiles, type TranslationProvider, type TranslationProviderFactory, type TranslationResult, type ValidationResult, addTranslationKey, addTranslationKeys, autoFillTranslations, detectExistingTranslations, ensureTranslationsStructure, extractVariables, fillNamespace, generateTranslationTypes, getAvailableLanguages, getMissingForLanguage, getNamespaces, getTranslationProvider, hasInterpolation, initTranslations, initTranslationsInteractive, isValidLanguage, loadConfig, manageTranslations, readTranslations, resetTranslationProvider, setTranslationProvider, sortKeys, translateBatch, translateText, validateLanguages, validateTranslations, validateVariables, writeTranslation };