poly-lexis 0.9.3 → 0.11.0

package/dist/index.d.ts

@@ -218,6 +218,15 @@ interface OrphanedTranslation {
     language: string;
     value: string;
 }
+interface StaleTranslation {
+    namespace: string;
+    key: string;
+    language: string;
+    /** Current source value (the translation should be regenerated from this) */
+    sourceValue: string;
+    /** The existing, potentially outdated, translated value */
+    currentValue: string;
+}
 interface UnusedTranslation {
     namespace: string;
     key: string;
@@ -229,6 +238,12 @@ interface ValidationResult {
     missing: MissingTranslation[];
     empty: MissingTranslation[];
     orphaned: OrphanedTranslation[];
+    /**
+     * Translations whose source value has changed since they were generated.
+     * Only detectable for translations written with source-hash tracking enabled.
+     * Reported as a warning; does not affect `valid`.
+     */
+    stale: StaleTranslation[];
 }
 interface UnusedKeysResult {
     unused: UnusedTranslation[];
@@ -282,6 +297,10 @@ interface AutoFillOptions {
     dryRun?: boolean;
     /** Number of concurrent translation requests (default: 5) */
     concurrency?: number;
+    /** Re-translate keys whose source value has changed since they were written */
+    retranslateChanged?: boolean;
+    /** Re-translate every key, even ones that already have an up-to-date value */
+    force?: boolean;
 }
 /**
  * Automatically fill empty or missing translations for a language
@@ -348,6 +367,10 @@ interface ManageTranslationsOptions {
     skipTypes?: boolean;
     /** Dry run mode */
     dryRun?: boolean;
+    /** Re-translate keys whose source value has changed (stale translations) */
+    retranslateChanged?: boolean;
+    /** Re-translate every key, regardless of current value */
+    force?: boolean;
 }
 /**
  * Smart translation management - handles init, validation, auto-fill, and type generation
@@ -361,12 +384,39 @@ declare function manageTranslations(projectRoot?: string, options?: ManageTransl
  * Checks for missing keys, empty values, and orphaned keys (keys removed from source)
  */
 declare function validateTranslations(projectRoot?: string): ValidationResult;
+type FillableType = 'missing' | 'empty' | 'stale';
+interface GetMissingOptions {
+    /** Also include translations whose source value has changed (stale) */
+    includeStale?: boolean;
+}
 /**
- * Get all missing or empty translations for a specific language
+ * Get all missing or empty translations for a specific language.
+ * When `includeStale` is set, also returns translations whose source value has
+ * changed since they were written (so they can be re-translated).
  */
-declare function getMissingForLanguage(projectRoot: string, language: string): Array<MissingTranslation & {
-    type: 'missing' | 'empty';
+declare function getMissingForLanguage(projectRoot: string, language: string, options?: GetMissingOptions): Array<MissingTranslation & {
+    type: FillableType;
 }>;
+interface BaselineResult {
+    /** Number of existing translations newly recorded against their current source value */
+    recorded: number;
+    /** Whether the metadata sidecar file was created by this call */
+    created: boolean;
+}
+/**
+ * Establish a change-tracking baseline for an existing translation set.
+ *
+ * For every key that already has a non-empty translation but no recorded source
+ * hash, record the hash of its *current* source value. This lets existing
+ * codebases (whose translations predate change tracking) start detecting future
+ * source changes without re-translating anything.
+ *
+ * Keys that already have a recorded hash are left untouched — overwriting them
+ * would erase the signal that a translation has gone stale. As a result, this
+ * treats whatever is currently in the repo as the up-to-date baseline: a
+ * translation that is already stale at adoption time will be accepted as current.
+ */
+declare function ensureBaselineMetadata(projectRoot?: string): BaselineResult;
 
 /**
  * Translation provider interface
@@ -447,6 +497,72 @@ declare class GoogleTranslateProvider implements TranslationProvider {
     validateConfig(): Promise<boolean>;
 }
 
+/**
+ * Name of the sidecar file (stored at the root of the translations directory)
+ * that records a hash of the source value each translation was generated from.
+ * This lets us detect when a source string has changed since its translations
+ * were written, so we can flag stale translations and optionally re-translate them.
+ */
+declare const METADATA_FILE_NAME = ".translations-meta.json";
+/**
+ * Per-language map of namespace -> key -> source value hash.
+ */
+interface TranslationMetadata {
+    /** Schema version, for forward compatibility */
+    version: number;
+    /** language -> namespace -> key -> hash of the source value at translation time */
+    languages: {
+        [language: string]: {
+            [namespace: string]: {
+                [key: string]: string;
+            };
+        };
+    };
+}
+/**
+ * Create an empty metadata structure
+ */
+declare function emptyMetadata(): TranslationMetadata;
+/**
+ * Compute a stable hash of a source value. Used to detect changes to source
+ * strings after their translations have been generated.
+ */
+declare function hashSourceValue(value: string): string;
+/**
+ * Absolute path to the metadata sidecar file
+ */
+declare function getMetadataPath(translationsPath: string): string;
+/**
+ * Whether a metadata sidecar file exists for this translations directory
+ */
+declare function metadataExists(translationsPath: string): boolean;
+/**
+ * Read the metadata sidecar file. Returns an empty structure if it does not
+ * exist or cannot be parsed.
+ */
+declare function readMetadata(translationsPath: string): TranslationMetadata;
+/**
+ * Write the metadata sidecar file
+ */
+declare function writeMetadata(translationsPath: string, metadata: TranslationMetadata): void;
+/**
+ * Record (in memory) the source value a translation was generated from.
+ * Mutates and returns the provided metadata object so callers can batch many
+ * updates before a single {@link writeMetadata} call.
+ */
+declare function setSourceHash(metadata: TranslationMetadata, language: string, namespace: string, key: string, sourceValue: string): TranslationMetadata;
+/**
+ * Get the stored source value hash for a translation, or undefined if none was
+ * recorded (e.g. for translations written before tracking was enabled).
+ */
+declare function getSourceHash(metadata: TranslationMetadata, language: string, namespace: string, key: string): string | undefined;
+/**
+ * Remove any recorded hashes that no longer correspond to a key present in the
+ * source translations. `sourceKeysByNamespace` maps each source namespace to the
+ * set of keys it currently contains. Returns true if anything was pruned.
+ */
+declare function pruneMetadata(metadata: TranslationMetadata, sourceKeysByNamespace: Record<string, Set<string>>): boolean;
+
 /**
  * Translation utilities with support for custom translation providers
  * Only translates content outside of {{variable}} interpolations
@@ -584,4 +700,4 @@ interface SyncResult {
  */
 declare function syncTranslationStructure(translationsPath: string, languages: string[], sourceLanguage: string): SyncResult;
 
-export { DEEPL_LANGUAGES, DEFAULT_CONFIG, DEFAULT_LANGUAGES, type DeepLLanguage, type DuplicateKeysResult, type DuplicateTranslation, GOOGLE_LANGUAGES, type GoogleLanguage, GoogleTranslateProvider, type LanguageFallbackResult, type ManageTranslationsOptions, type MissingTranslation, type NestedTranslationFile, type OrphanedTranslation, 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 UnusedKeysResult, type UnusedTranslation, type ValidationResult, addTranslationKey, addTranslationKeys, autoFillTranslations, createEmptyTranslationStructure, detectExistingTranslations, ensureTranslationsStructure, extractPluralBaseKeys, extractVariables, fillNamespace, findUnusedKeys, flattenObject, generateTranslationTypes, getAvailableLanguages, getFallbackMappings, getMissingForLanguage, getNamespaces, getSupportedLanguages, getTranslationProvider, hasInterpolation, initTranslations, initTranslationsInteractive, isNestedObject, isValidDeepLLanguage, isValidGoogleLanguage, isValidLanguage, isValidLanguageForProvider, loadConfig, logLanguageFallback, manageTranslations, printUnusedKeysResult, readTranslations, resetTranslationProvider, resolveLanguageWithFallback, setTranslationProvider, sortKeys, syncTranslationStructure, translateBatch, translateText, unflattenObject, validateLanguages, validateLanguagesForProvider, validateTranslations, validateVariables, writeTranslation };
+export { type BaselineResult, DEEPL_LANGUAGES, DEFAULT_CONFIG, DEFAULT_LANGUAGES, type DeepLLanguage, type DuplicateKeysResult, type DuplicateTranslation, type FillableType, GOOGLE_LANGUAGES, type GetMissingOptions, type GoogleLanguage, GoogleTranslateProvider, type LanguageFallbackResult, METADATA_FILE_NAME, type ManageTranslationsOptions, type MissingTranslation, type NestedTranslationFile, type OrphanedTranslation, SUPPORTED_LANGUAGES, type StaleTranslation, type SupportedLanguage, type SyncResult, TRANSLATION_CONFIG_SCHEMA, TRANSLATION_PROVIDERS, type TranslateOptions, type TranslationConfig, type TranslationEntry, type TranslationFile, type TranslationFiles, type TranslationMetadata, type TranslationProvider, type TranslationProviderFactory, type TranslationProviderType, type TranslationResult, type UnusedKeysResult, type UnusedTranslation, type ValidationResult, addTranslationKey, addTranslationKeys, autoFillTranslations, createEmptyTranslationStructure, detectExistingTranslations, emptyMetadata, ensureBaselineMetadata, ensureTranslationsStructure, extractPluralBaseKeys, extractVariables, fillNamespace, findUnusedKeys, flattenObject, generateTranslationTypes, getAvailableLanguages, getFallbackMappings, getMetadataPath, getMissingForLanguage, getNamespaces, getSourceHash, getSupportedLanguages, getTranslationProvider, hasInterpolation, hashSourceValue, initTranslations, initTranslationsInteractive, isNestedObject, isValidDeepLLanguage, isValidGoogleLanguage, isValidLanguage, isValidLanguageForProvider, loadConfig, logLanguageFallback, manageTranslations, metadataExists, printUnusedKeysResult, pruneMetadata, readMetadata, readTranslations, resetTranslationProvider, resolveLanguageWithFallback, setSourceHash, setTranslationProvider, sortKeys, syncTranslationStructure, translateBatch, translateText, unflattenObject, validateLanguages, validateLanguagesForProvider, validateTranslations, validateVariables, writeMetadata, writeTranslation };