poly-lexis 0.3.2 → 0.4.1

package/dist/index.d.ts

@@ -1,3 +1,156 @@
+/**
+ * Language fallback utilities
+ * Provides intelligent fallback logic for unsupported language codes
+ */
+
+/**
+ * Result of language fallback resolution
+ */
+interface LanguageFallbackResult {
+    /** The resolved language code to use */
+    resolvedLanguage: string;
+    /** Whether a fallback was used */
+    usedFallback: boolean;
+    /** The original language code requested */
+    originalLanguage: string;
+    /** Chain of fallback attempts made */
+    fallbackChain?: string[];
+}
+/**
+ * Resolve language code with fallback logic
+ * Tries to find a supported language for the given provider
+ *
+ * @param language - Original language code requested
+ * @param provider - Translation provider type ('deepl' or 'google')
+ * @param enableFallback - Whether to enable fallback logic (default: true)
+ * @returns LanguageFallbackResult with resolved language and metadata
+ */
+declare function resolveLanguageWithFallback(language: string, provider: TranslationProviderType, enableFallback?: boolean): LanguageFallbackResult;
+/**
+ * Log fallback information to console
+ * Informs user when a language fallback is being used
+ */
+declare function logLanguageFallback(result: LanguageFallbackResult, provider: TranslationProviderType): void;
+/**
+ * Get all registered fallback mappings
+ * Useful for debugging and documentation
+ */
+declare function getFallbackMappings(): Record<string, string[]>;
+
+/**
+ * Translation provider types
+ */
+declare const TRANSLATION_PROVIDERS: readonly ["deepl", "google"];
+type TranslationProviderType = (typeof TRANSLATION_PROVIDERS)[number];
+/**
+ * DeepL supported target languages
+ * Based on DeepL API v2 documentation
+ */
+declare const DEEPL_LANGUAGES: readonly ["ar", "bg", "cs", "da", "de", "el", "en", "en_gb", "en_us", "es", "es_419", "et", "fi", "fr", "he", "hu", "id", "it", "ja", "ko", "lt", "lv", "nb", "nl", "pl", "pt", "pt_br", "pt_pt", "ro", "ru", "sk", "sl", "sv", "th", "tr", "uk", "vi", "zh", "zh_hans", "zh_hant"];
+/**
+ * Google Translate supported languages
+ * Based on Google Cloud Translation API v2
+ * Reference: https://docs.cloud.google.com/translate/docs/languages
+ */
+declare const GOOGLE_LANGUAGES: readonly ["af", "sq", "am", "ar", "hy", "az", "eu", "be", "bn", "bs", "bg", "ca", "ceb", "zh", "zh_cn", "zh_tw", "co", "hr", "cs", "da", "nl", "en", "eo", "et", "fi", "fr", "fy", "gl", "ka", "de", "el", "gu", "ht", "ha", "haw", "he", "hi", "hmn", "hu", "is", "ig", "id", "ga", "it", "ja", "jv", "kn", "kk", "km", "rw", "ko", "ku", "ky", "lo", "la", "lv", "lt", "lb", "mk", "mg", "ms", "ml", "mt", "mi", "mr", "mn", "my", "ne", "no", "ny", "or", "ps", "fa", "pl", "pt", "pt_br", "pa", "ro", "ru", "sm", "gd", "sr", "st", "sn", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "sv", "tl", "tg", "ta", "tt", "te", "th", "tr", "tk", "uk", "ur", "ug", "uz", "vi", "cy", "xh", "yi", "yo", "zu"];
+/**
+ * All supported language codes (union of DeepL and Google Translate)
+ */
+declare const SUPPORTED_LANGUAGES: readonly string[];
+type DeepLLanguage = (typeof DEEPL_LANGUAGES)[number];
+type GoogleLanguage = (typeof GOOGLE_LANGUAGES)[number];
+type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
+/**
+ * JSON Schema for .translationsrc.json
+ */
+declare const TRANSLATION_CONFIG_SCHEMA: {
+    title: string;
+    description: string;
+    type: string;
+    properties: {
+        $schema: {
+            type: string;
+            description: string;
+        };
+        translationsPath: {
+            type: string;
+            description: string;
+            default: string;
+            examples: string[];
+        };
+        languages: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                enum: readonly string[];
+            };
+            minItems: number;
+            uniqueItems: boolean;
+            default: string[];
+        };
+        sourceLanguage: {
+            type: string;
+            description: string;
+            enum: readonly string[];
+            default: string;
+        };
+        typesOutputPath: {
+            type: string;
+            description: string;
+            default: string;
+            examples: string[];
+        };
+        provider: {
+            type: string;
+            description: string;
+            enum: readonly ["deepl", "google"];
+            default: string;
+        };
+        useFallbackLanguages: {
+            type: string;
+            description: string;
+            default: boolean;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+/**
+ * Validate if a language code is supported
+ */
+declare function isValidLanguage(lang: string): lang is SupportedLanguage;
+/**
+ * Validate if a language is supported by DeepL
+ */
+declare function isValidDeepLLanguage(lang: string): lang is DeepLLanguage;
+/**
+ * Validate if a language is supported by Google Translate
+ */
+declare function isValidGoogleLanguage(lang: string): lang is GoogleLanguage;
+/**
+ * Validate if a language is supported by a specific provider
+ */
+declare function isValidLanguageForProvider(lang: string, provider: TranslationProviderType): boolean;
+/**
+ * Validate languages array
+ */
+declare function validateLanguages(languages: string[]): {
+    valid: boolean;
+    invalid: string[];
+};
+/**
+ * Validate languages array for a specific provider
+ */
+declare function validateLanguagesForProvider(languages: string[], provider: TranslationProviderType): {
+    valid: boolean;
+    invalid: string[];
+};
+/**
+ * Get supported languages for a specific provider
+ */
+declare function getSupportedLanguages(provider: TranslationProviderType): readonly string[];
+
 interface TranslationConfig {
     /** Path to the translations directory (default: public/static/locales) */
     translationsPath?: string;
@@ -7,6 +160,10 @@ interface TranslationConfig {
     sourceLanguage?: string;
     /** Path to output i18n types (default: src/types/i18nTypes.ts) */
     typesOutputPath?: string;
+    /** Translation provider to use (default: 'deepl') */
+    provider?: TranslationProviderType;
+    /** Enable automatic language fallback for unsupported regional variants (default: true) */
+    useFallbackLanguages?: boolean;
 }
 interface TranslationEntry {
     namespace: string;
@@ -31,7 +188,7 @@ interface ValidationResult {
     empty: MissingTranslation[];
 }
 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"];
+declare const DEFAULT_LANGUAGES: readonly ["en", "fr", "it", "pl", "es", "pt", "de", "nl", "sv", "hu", "cs", "ja"];
 
 interface AddKeyOptions {
     /** Namespace for the translation key */
@@ -57,7 +214,7 @@ declare function addTranslationKeys(projectRoot: string, entries: TranslationEnt
 interface AutoFillOptions {
     /** Language to fill translations for */
     language?: string;
-    /** Google Translate API key */
+    /** Translation API key (for DeepL or Google Translate) */
     apiKey?: string;
     /** Maximum number of translations to process */
     limit?: number;
@@ -134,115 +291,6 @@ declare function getMissingForLanguage(projectRoot: string, language: string): A
     type: 'missing' | 'empty';
 }>;
 
-/**
- * Translation provider types
- */
-declare const TRANSLATION_PROVIDERS: readonly ["deepl", "google"];
-type TranslationProviderType = (typeof TRANSLATION_PROVIDERS)[number];
-/**
- * DeepL supported target languages
- * Based on DeepL API v2 documentation
- */
-declare const DEEPL_LANGUAGES: readonly ["ar", "bg", "cs", "da", "de", "el", "en", "en_gb", "en_us", "es", "es_419", "et", "fi", "fr", "he", "hu", "id", "it", "ja", "ko", "lt", "lv", "nb", "nl", "pl", "pt", "pt_br", "pt_pt", "ro", "ru", "sk", "sl", "sv", "th", "tr", "uk", "vi", "zh", "zh_hans", "zh_hant"];
-/**
- * Google Translate supported languages
- * Based on Google Cloud Translation API v2
- * Reference: https://docs.cloud.google.com/translate/docs/languages
- */
-declare const GOOGLE_LANGUAGES: readonly ["af", "sq", "am", "ar", "hy", "az", "eu", "be", "bn", "bs", "bg", "ca", "ceb", "zh", "zh_cn", "zh_tw", "co", "hr", "cs", "da", "nl", "en", "eo", "et", "fi", "fr", "fy", "gl", "ka", "de", "el", "gu", "ht", "ha", "haw", "he", "hi", "hmn", "hu", "is", "ig", "id", "ga", "it", "ja", "jv", "kn", "kk", "km", "rw", "ko", "ku", "ky", "lo", "la", "lv", "lt", "lb", "mk", "mg", "ms", "ml", "mt", "mi", "mr", "mn", "my", "ne", "no", "ny", "or", "ps", "fa", "pl", "pt", "pt_br", "pa", "ro", "ru", "sm", "gd", "sr", "st", "sn", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "sv", "tl", "tg", "ta", "tt", "te", "th", "tr", "tk", "uk", "ur", "ug", "uz", "vi", "cy", "xh", "yi", "yo", "zu"];
-/**
- * All supported language codes (union of DeepL and Google Translate)
- */
-declare const SUPPORTED_LANGUAGES: readonly string[];
-type DeepLLanguage = (typeof DEEPL_LANGUAGES)[number];
-type GoogleLanguage = (typeof GOOGLE_LANGUAGES)[number];
-type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
-/**
- * JSON Schema for .translationsrc.json
- */
-declare const TRANSLATION_CONFIG_SCHEMA: {
-    title: string;
-    description: string;
-    type: string;
-    properties: {
-        $schema: {
-            type: string;
-            description: string;
-        };
-        translationsPath: {
-            type: string;
-            description: string;
-            default: string;
-            examples: string[];
-        };
-        languages: {
-            type: string;
-            description: string;
-            items: {
-                type: string;
-                enum: readonly string[];
-            };
-            minItems: number;
-            uniqueItems: boolean;
-            default: string[];
-        };
-        sourceLanguage: {
-            type: string;
-            description: string;
-            enum: readonly string[];
-            default: string;
-        };
-        typesOutputPath: {
-            type: string;
-            description: string;
-            default: string;
-            examples: string[];
-        };
-        provider: {
-            type: string;
-            description: string;
-            enum: readonly ["deepl", "google"];
-            default: string;
-        };
-    };
-    required: string[];
-    additionalProperties: boolean;
-};
-/**
- * Validate if a language code is supported
- */
-declare function isValidLanguage(lang: string): lang is SupportedLanguage;
-/**
- * Validate if a language is supported by DeepL
- */
-declare function isValidDeepLLanguage(lang: string): lang is DeepLLanguage;
-/**
- * Validate if a language is supported by Google Translate
- */
-declare function isValidGoogleLanguage(lang: string): lang is GoogleLanguage;
-/**
- * Validate if a language is supported by a specific provider
- */
-declare function isValidLanguageForProvider(lang: string, provider: TranslationProviderType): boolean;
-/**
- * Validate languages array
- */
-declare function validateLanguages(languages: string[]): {
-    valid: boolean;
-    invalid: string[];
-};
-/**
- * Validate languages array for a specific provider
- */
-declare function validateLanguagesForProvider(languages: string[], provider: TranslationProviderType): {
-    valid: boolean;
-    invalid: string[];
-};
-/**
- * Get supported languages for a specific provider
- */
-declare function getSupportedLanguages(provider: TranslationProviderType): readonly string[];
-
 /**
  * Translation provider interface
  * Implement this interface to create custom translation providers
@@ -259,6 +307,8 @@ interface TranslateOptions {
     targetLang: string;
     /** API key or credentials (optional, depending on provider) */
     apiKey?: string;
+    /** Enable automatic language fallback for unsupported regional variants (default: true) */
+    useFallbackLanguages?: boolean;
     /** Additional provider-specific options */
     [key: string]: unknown;
 }
@@ -344,9 +394,10 @@ declare function resetTranslationProvider(): void;
  * @param targetLang - Target language code
  * @param sourceLang - Source language code (default: "en")
  * @param apiKey - API key for the translation service
+ * @param useFallbackLanguages - Enable automatic language fallback (default: true)
  * @returns Promise resolving to translated text
  */
-declare function translateText(text: string, targetLang: string, sourceLang?: string, apiKey?: string): Promise<string>;
+declare function translateText(text: string, targetLang: string, sourceLang?: string, apiKey?: string, useFallbackLanguages?: boolean): Promise<string>;
 /**
  * Translate multiple texts in batch
  *
@@ -395,5 +446,30 @@ declare function sortKeys<T extends Record<string, unknown>>(obj: T): T;
  * Ensure translations path exists and has proper structure
  */
 declare function ensureTranslationsStructure(translationsPath: string, languages: string[]): void;
+/**
+ * Create an empty translation structure from a source translation file
+ * All values are set to empty strings, preserving the key structure
+ */
+declare function createEmptyTranslationStructure(sourceFile: TranslationFile): TranslationFile;
+interface SyncResult {
+    createdFolders: string[];
+    createdFiles: Array<{
+        language: string;
+        namespace: string;
+        path: string;
+    }>;
+    skippedFiles: Array<{
+        language: string;
+        namespace: string;
+        reason: string;
+    }>;
+}
+/**
+ * Synchronize translation structure based on source language
+ * - Ensures all configured languages have folders
+ * - Ensures all namespaces from source language exist in target languages
+ * - Creates files with empty values matching source structure
+ */
+declare function syncTranslationStructure(translationsPath: string, languages: string[], sourceLanguage: string): SyncResult;
 
-export { DEEPL_LANGUAGES, DEFAULT_CONFIG, DEFAULT_LANGUAGES, type DeepLLanguage, GOOGLE_LANGUAGES, type GoogleLanguage, GoogleTranslateProvider, type ManageTranslationsOptions, type MissingTranslation, SUPPORTED_LANGUAGES, type SupportedLanguage, TRANSLATION_CONFIG_SCHEMA, TRANSLATION_PROVIDERS, type TranslateOptions, type TranslationConfig, type TranslationEntry, type TranslationFile, type TranslationFiles, type TranslationProvider, type TranslationProviderFactory, type TranslationProviderType, type TranslationResult, type ValidationResult, addTranslationKey, addTranslationKeys, autoFillTranslations, detectExistingTranslations, ensureTranslationsStructure, extractVariables, fillNamespace, generateTranslationTypes, getAvailableLanguages, getMissingForLanguage, getNamespaces, getSupportedLanguages, getTranslationProvider, hasInterpolation, initTranslations, initTranslationsInteractive, isValidDeepLLanguage, isValidGoogleLanguage, isValidLanguage, isValidLanguageForProvider, loadConfig, manageTranslations, readTranslations, resetTranslationProvider, setTranslationProvider, sortKeys, translateBatch, translateText, validateLanguages, validateLanguagesForProvider, validateTranslations, validateVariables, writeTranslation };
+export { DEEPL_LANGUAGES, DEFAULT_CONFIG, DEFAULT_LANGUAGES, type DeepLLanguage, GOOGLE_LANGUAGES, type GoogleLanguage, GoogleTranslateProvider, type LanguageFallbackResult, type ManageTranslationsOptions, type MissingTranslation, SUPPORTED_LANGUAGES, type SupportedLanguage, type SyncResult, TRANSLATION_CONFIG_SCHEMA, TRANSLATION_PROVIDERS, type TranslateOptions, type TranslationConfig, type TranslationEntry, type TranslationFile, type TranslationFiles, type TranslationProvider, type TranslationProviderFactory, type TranslationProviderType, type TranslationResult, type ValidationResult, addTranslationKey, addTranslationKeys, autoFillTranslations, createEmptyTranslationStructure, detectExistingTranslations, ensureTranslationsStructure, extractVariables, fillNamespace, generateTranslationTypes, getAvailableLanguages, getFallbackMappings, getMissingForLanguage, getNamespaces, getSupportedLanguages, getTranslationProvider, hasInterpolation, initTranslations, initTranslationsInteractive, isValidDeepLLanguage, isValidGoogleLanguage, isValidLanguage, isValidLanguageForProvider, loadConfig, logLanguageFallback, manageTranslations, readTranslations, resetTranslationProvider, resolveLanguageWithFallback, setTranslationProvider, sortKeys, syncTranslationStructure, translateBatch, translateText, validateLanguages, validateLanguagesForProvider, validateTranslations, validateVariables, writeTranslation };