poly-lexis 0.8.0 → 0.9.0

package/README.md

@@ -150,7 +150,8 @@ poly-lexis uses a `.translationsrc.json` file in your project root for configura
   "languages": ["en", "es", "fr", "de"],
   "sourceLanguage": "en",
   "typesOutputPath": "src/types/i18nTypes.ts",
-  "provider": "deepl"
+  "provider": "deepl",
+  "protectedTerms": ["MyBrand", "ProductName"]
 }
 ```
 
@@ -161,6 +162,19 @@ poly-lexis uses a `.translationsrc.json` file in your project root for configura
 - `sourceLanguage` - Source language for translations (default: `"en"`)
 - `typesOutputPath` - Path to output TypeScript types (default: `src/types/i18nTypes.ts`)
 - `provider` - Translation provider to use: `"deepl"` or `"google"` (default: `"deepl"`)
+- `protectedTerms` - Words or phrases that should never be translated (default: `[]`)
+
+### Protected Terms
+
+Use `protectedTerms` to prevent specific words or phrases from being translated — useful for brand names, product names, or any term that must remain unchanged across all languages.
+
+```json
+{
+  "protectedTerms": ["Vandelay Industries", "MyProduct"]
+}
+```
+
+These terms are replaced with placeholders before the text is sent to the translation API and restored afterwards, so the translation service never sees them.
 
 ### Environment Variables
 

package/dist/cli/translations.js

@@ -710,7 +710,8 @@ var init_types = __esm({
       provider: "deepl",
       useFallbackLanguages: true,
       searchPaths: ["src", "app", "pages", "components"],
-      searchExtensions: [".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte"]
+      searchExtensions: [".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte"],
+      protectedTerms: []
     };
     DEFAULT_LANGUAGES = ["en", "fr", "it", "pl", "es", "pt", "de", "nl", "sv", "hu", "cs", "ja"];
   }
@@ -903,7 +904,7 @@ function generateTranslationTypes(projectRoot = process.cwd()) {
   if (!fs3.existsSync(outputDir)) {
     fs3.mkdirSync(outputDir, { recursive: true });
   }
-  const typeString = typeTemplate(allKeys, namespaces);
+  const typeString = typeTemplate(allKeys, namespaces, config.languages);
   fs3.writeFileSync(outputFilePath, typeString, "utf8");
   console.log(`Generated types with ${allKeys.length} keys and ${namespaces.length} namespaces`);
   console.log(`Output: ${outputFilePath}`);
@@ -926,12 +927,14 @@ var init_generate_types = __esm({
     init_utils();
     init_init();
     PLURAL_SUFFIXES = ["_zero", "_one", "_two", "_few", "_many", "_other"];
-    typeTemplate = (translationKeys, namespaceKeys) => `
+    typeTemplate = (translationKeys, namespaceKeys, languages) => `
   export const translationKeys = [${translationKeys.map((key) => `"${key}"`).join(", ")}] as const;
   export const namespaceKeys = [${namespaceKeys.map((key) => `"${key}"`).join(", ")}] as const;
+  export const languages = [${languages.map((lang) => `"${lang}"`).join(", ")}] as const;
 
   export type TranslationKey = typeof translationKeys[number];
   export type TranslationNamespace = typeof namespaceKeys[number];
+  export type Language = typeof languages[number];
 `;
   }
 });
@@ -1319,10 +1322,20 @@ import * as path5 from "path";
 // src/translations/utils/deepl-translate-provider.ts
 init_esm_shims();
 init_language_fallback();
-function preserveVariables(text) {
+function preserveVariables(text, protectedTerms = []) {
   const variableMap = /* @__PURE__ */ new Map();
   let placeholderIndex = 0;
-  const textWithPlaceholders = text.replace(/\{\{([^}]+)\}\}/g, (match) => {
+  let result = text;
+  for (const term of protectedTerms) {
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    result = result.replace(new RegExp(escaped, "g"), () => {
+      const placeholder = `XXX_${placeholderIndex}_XXX`;
+      variableMap.set(placeholder, term);
+      placeholderIndex++;
+      return placeholder;
+    });
+  }
+  const textWithPlaceholders = result.replace(/\{\{([^}]+)\}\}/g, (match) => {
     const placeholder = `XXX_${placeholderIndex}_XXX`;
     variableMap.set(placeholder, match);
     placeholderIndex++;
@@ -1354,7 +1367,7 @@ var DeepLTranslateProvider = class {
     return this.isFreeApi ? "https://api-free.deepl.com/v2/translate" : "https://api.deepl.com/v2/translate";
   }
   async translate(options) {
-    const { text, sourceLang, targetLang, apiKey, useFallbackLanguages = true } = options;
+    const { text, sourceLang, targetLang, apiKey, useFallbackLanguages = true, protectedTerms = [] } = options;
     if (!apiKey) {
       throw new Error(
         "DeepL API key is required. Set DEEPL_API_KEY environment variable or provide apiKey in options."
@@ -1368,7 +1381,7 @@ var DeepLTranslateProvider = class {
       logLanguageFallback(sourceLangResult, "deepl");
       resolvedSourceLang = sourceLangResult.resolvedLanguage;
     }
-    const { textWithPlaceholders, variableMap } = preserveVariables(text);
+    const { textWithPlaceholders, variableMap } = preserveVariables(text, protectedTerms);
     const body = {
       text: [textWithPlaceholders],
       target_lang: normalizeLanguageCode(targetLangResult.resolvedLanguage),
@@ -1418,10 +1431,20 @@ var DeepLTranslateProvider = class {
 // src/translations/utils/google-translate-provider.ts
 init_esm_shims();
 init_language_fallback();
-function preserveVariables2(text) {
+function preserveVariables2(text, protectedTerms = []) {
   const variableMap = /* @__PURE__ */ new Map();
   let placeholderIndex = 0;
-  const textWithPlaceholders = text.replace(/\{\{([^}]+)\}\}/g, (match) => {
+  let result = text;
+  for (const term of protectedTerms) {
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    result = result.replace(new RegExp(escaped, "g"), () => {
+      const placeholder = `XXX_${placeholderIndex}_XXX`;
+      variableMap.set(placeholder, term);
+      placeholderIndex++;
+      return placeholder;
+    });
+  }
+  const textWithPlaceholders = result.replace(/\{\{([^}]+)\}\}/g, (match) => {
     const placeholder = `XXX_${placeholderIndex}_XXX`;
     variableMap.set(placeholder, match);
     placeholderIndex++;
@@ -1443,7 +1466,7 @@ function restoreVariables2(text, variableMap) {
 }
 var GoogleTranslateProvider = class {
   async translate(options) {
-    const { text, sourceLang, targetLang, apiKey, useFallbackLanguages = true } = options;
+    const { text, sourceLang, targetLang, apiKey, useFallbackLanguages = true, protectedTerms = [] } = options;
     if (!apiKey) {
       throw new Error(
         "Google Translate API key is required. Set GOOGLE_TRANSLATE_API_KEY environment variable or provide apiKey in options."
@@ -1457,7 +1480,7 @@ var GoogleTranslateProvider = class {
       logLanguageFallback(sourceLangResult, "google");
       resolvedSourceLang = sourceLangResult.resolvedLanguage;
     }
-    const { textWithPlaceholders, variableMap } = preserveVariables2(text);
+    const { textWithPlaceholders, variableMap } = preserveVariables2(text, protectedTerms);
     const url = `https://translation.googleapis.com/language/translate/v2?key=${apiKey}`;
     const sourceForGoogle = resolvedSourceLang?.includes("_") ? resolvedSourceLang.split("_")[0] : resolvedSourceLang;
     const targetForGoogle = targetLangResult.resolvedLanguage.includes("_") ? targetLangResult.resolvedLanguage.split("_")[0] : targetLangResult.resolvedLanguage;
@@ -1512,14 +1535,15 @@ function setTranslationProvider(provider) {
 function getTranslationProvider() {
   return customProvider || defaultProvider;
 }
-async function translateText(text, targetLang, sourceLang = "en", apiKey, useFallbackLanguages = true) {
+async function translateText(text, targetLang, sourceLang = "en", apiKey, useFallbackLanguages = true, protectedTerms = []) {
   const provider = getTranslationProvider();
   return provider.translate({
     text,
     sourceLang,
     targetLang,
     apiKey,
-    useFallbackLanguages
+    useFallbackLanguages,
+    protectedTerms
   });
 }
 
@@ -1570,7 +1594,14 @@ async function addTranslationKey(projectRoot, options) {
           targetTranslations[namespace] = {};
         }
         if (!targetTranslations[namespace][key] || targetTranslations[namespace][key].trim() === "") {
-          const translated = await translateText(value, lang, sourceLang, apiKey, config.useFallbackLanguages ?? true);
+          const translated = await translateText(
+            value,
+            lang,
+            sourceLang,
+            apiKey,
+            config.useFallbackLanguages,
+            config.protectedTerms
+          );
           targetTranslations[namespace][key] = translated;
           const sorted = sortKeys(targetTranslations[namespace]);
           writeTranslation(translationsPath, lang, namespace, sorted);
@@ -2001,7 +2032,8 @@ Processing language: ${language}`);
           language,
           config.sourceLanguage,
           apiKey,
-          config.useFallbackLanguages ?? true
+          config.useFallbackLanguages,
+          config.protectedTerms
         );
         console.log(`    ${language.toUpperCase()}: "${translated}"`);
         if (!dryRun) {
@@ -2368,8 +2400,8 @@ if (command === "find-unused") {
           message: "Enter translation key (UPPERCASE_SNAKE_CASE):",
           validate: (value2) => {
             if (!value2.trim()) return "Key is required";
-            if (!/^[A-Z0-9_]+$/.test(value2)) {
-              return "Key should use UPPERCASE_SNAKE_CASE (e.g., SAVE_CHANGES)";
+            if (!/^[A-Z0-9_]+$/.test(value2.toUpperCase())) {
+              return "Key must be SNAKE_CASE (e.g., SAVE_CHANGES)";
             }
             return true;
           },
@@ -2582,8 +2614,8 @@ if (command === "find-unused") {
             message: "Enter translation key (UPPERCASE_SNAKE_CASE):",
             validate: (value2) => {
               if (!value2.trim()) return "Key is required";
-              if (!/^[A-Z0-9_]+$/.test(value2)) {
-                return "Key should use UPPERCASE_SNAKE_CASE (e.g., SAVE_CHANGES)";
+              if (!/^[A-Z0-9_]+$/.test(value2.toUpperCase())) {
+                return "Key must be SNAKE_CASE (e.g., SAVE_CHANGES)";
               }
               return true;
             },