gtx-cli 2.5.13 → 2.5.14

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # gtx-cli
 
+## 2.5.14
+
+### Patch Changes
+
+- [#837](https://github.com/generaltranslation/gt/pull/837) [`0772b57`](https://github.com/generaltranslation/gt/commit/0772b5714f1cfe8af5f5edcdf6bcb28125a1536f) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Making experimentalAddHeaderAnchorIds independent of experimentalLocalizeStaticUrls and fetching anchor IDs from source files when present
+
+- [#835](https://github.com/generaltranslation/gt/pull/835) [`79225fb`](https://github.com/generaltranslation/gt/commit/79225fb3bbea3bb7a453cc237c619b67dd0dd3da) Thanks [@brian-lou](https://github.com/brian-lou)! - When using --force translate, also force files to re-download
+
 ## 2.5.13
 
 ### Patch Changes

package/dist/cli/commands/translate.js

@@ -14,7 +14,8 @@ export async function handleTranslate(options, settings, fileVersionData, jobDat
         const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
         const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
         // Check for remaining translations
-        await downloadTranslations(fileVersionData, jobData, branchData, settings.locales, options.timeout, (sourcePath, locale) => fileMapping[locale]?.[sourcePath] ?? null, settings, options.force, options.forceDownload);
+        await downloadTranslations(fileVersionData, jobData, branchData, settings.locales, options.timeout, (sourcePath, locale) => fileMapping[locale]?.[sourcePath] ?? null, settings, options.force, options.forceDownload || options.force // if force is true should also force download
+        );
     }
 }
 // Downloads translations that were originally staged
@@ -31,7 +32,7 @@ export async function handleDownload(options, settings) {
     const stagedVersionData = await getStagedVersions(settings.configDirectory);
     // Check for remaining translations
     await downloadTranslations(stagedVersionData, undefined, undefined, settings.locales, options.timeout, (sourcePath, locale) => fileMapping[locale][sourcePath] ?? null, settings, false, // force is not applicable for downloading staged translations
-    options.forceDownload);
+    options.force || options.forceDownload);
 }
 export async function postProcessTranslations(settings, includeFiles) {
     // Localize static urls (/docs -> /[locale]/docs) and preserve anchor IDs for non-default locales
@@ -41,8 +42,12 @@ export async function postProcessTranslations(settings, includeFiles) {
         if (nonDefaultLocales.length > 0) {
             await localizeStaticUrls(settings, nonDefaultLocales, includeFiles);
         }
-        // Add explicit anchor IDs to translated MDX/MD files to preserve navigation
-        // Uses inline {#id} format by default, or div wrapping if experimentalAddHeaderAnchorIds is 'mintlify'
+    }
+    const shouldProcessAnchorIds = settings.options?.experimentalLocalizeStaticUrls ||
+        settings.options?.experimentalAddHeaderAnchorIds;
+    // Add explicit anchor IDs to translated MDX/MD files to preserve navigation
+    // Uses inline {#id} format by default, or div wrapping if experimentalAddHeaderAnchorIds is 'mintlify'
+    if (shouldProcessAnchorIds) {
         await processAnchorIds(settings, includeFiles);
     }
     // Localize static imports (import Snippet from /snippets/file.mdx -> import Snippet from /snippets/[locale]/file.mdx)

package/dist/types/index.d.ts

@@ -24,7 +24,11 @@ export type Options = {
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     experimentalLocalizeStaticImports?: boolean;
-    experimentalAddHeaderAnchorIds?: 'mintlify';
+    experimentalAddHeaderAnchorIds?: 'mintlify' | 'default';
+    docsImportRewrites?: Array<{
+        match: string;
+        replace: string;
+    }>;
 };
 export type TranslateFlags = {
     config?: string;
@@ -49,9 +53,13 @@ export type TranslateFlags = {
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     experimentalLocalizeStaticImports?: boolean;
-    experimentalAddHeaderAnchorIds?: 'mintlify';
+    experimentalAddHeaderAnchorIds?: 'mintlify' | 'default';
     excludeStaticUrls?: string[];
     excludeStaticImports?: string[];
+    docsImportRewrites?: Array<{
+        match: string;
+        replace: string;
+    }>;
 };
 export type WrapOptions = {
     src?: string[];
@@ -160,10 +168,14 @@ export type AdditionalOptions = {
     clearLocaleDirsExclude?: string[];
     experimentalLocalizeStaticImports?: boolean;
     experimentalLocalizeStaticUrls?: boolean;
-    experimentalAddHeaderAnchorIds?: 'mintlify';
+    experimentalAddHeaderAnchorIds?: 'mintlify' | 'default';
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     baseDomain?: string;
+    docsImportRewrites?: Array<{
+        match: string;
+        replace: string;
+    }>;
 };
 export type SharedStaticAssetsConfig = {
     include: string | string[];

package/dist/utils/addExplicitAnchorIds.js

@@ -30,6 +30,16 @@ function extractHeadingText(heading) {
     });
     return text;
 }
+function parseHeadingContent(text) {
+    // Support both {#id} and escaped \{#id\} forms
+    const anchorMatch = text.match(/(\\\{#([^}]+)\\\}|\{#([^}]+)\})\s*$/);
+    if (!anchorMatch) {
+        return { cleanedText: text };
+    }
+    const explicitId = anchorMatch[2] || anchorMatch[3];
+    const cleanedText = text.replace(anchorMatch[0], '').trimEnd();
+    return { cleanedText, explicitId };
+}
 /**
  * Checks if a heading is already wrapped in a div with id
  */
@@ -57,15 +67,34 @@ export function extractHeadingInfo(mdxContent) {
     }
     catch (error) {
         console.warn(`Failed to parse MDX content: ${error instanceof Error ? error.message : String(error)}`);
-        return [];
+        // Fallback: simple regex-based extraction to keep IDs usable
+        const fallbackHeadings = [];
+        const headingRegex = /^(#{1,6})\s+(.*)$/gm;
+        let position = 0;
+        let match;
+        while ((match = headingRegex.exec(mdxContent)) !== null) {
+            const hashes = match[1];
+            const rawText = match[2];
+            const { cleanedText, explicitId } = parseHeadingContent(rawText);
+            if (cleanedText || explicitId) {
+                fallbackHeadings.push({
+                    text: cleanedText,
+                    level: hashes.length,
+                    slug: explicitId ?? generateSlug(cleanedText),
+                    position: position++,
+                });
+            }
+        }
+        return fallbackHeadings;
     }
     let position = 0;
     visit(processedAst, 'heading', (heading) => {
         const headingText = extractHeadingText(heading);
-        if (headingText) {
-            const slug = generateSlug(headingText);
+        const { cleanedText, explicitId } = parseHeadingContent(headingText);
+        if (cleanedText || explicitId) {
+            const slug = explicitId ?? generateSlug(cleanedText);
             headings.push({
-                text: headingText,
+                text: cleanedText,
                 level: heading.depth,
                 slug,
                 position: position++,
@@ -114,13 +143,16 @@ export function addExplicitAnchorIds(translatedContent, sourceHeadingMap, settin
             addedIds: [],
         };
     }
+    const translatedIsMdx = translatedPath
+        ? translatedPath.toLowerCase().endsWith('.mdx')
+        : true; // default to mdx-style escaping when unknown
     // Apply IDs to translated content
     let content;
     if (useDivWrapping) {
         content = applyDivWrappedIds(translatedContent, translatedHeadings, idMappings);
     }
     else {
-        content = applyInlineIds(translatedContent, idMappings);
+        content = applyInlineIds(translatedContent, idMappings, translatedIsMdx);
     }
     return {
         content,
@@ -131,7 +163,17 @@ export function addExplicitAnchorIds(translatedContent, sourceHeadingMap, settin
 /**
  * Adds inline {#id} syntax to headings (standard markdown approach)
  */
-function applyInlineIds(translatedContent, idMappings) {
+function applyInlineIds(translatedContent, idMappings, escapeAnchors) {
+    const escapeInlineAnchors = (content) => {
+        if (!escapeAnchors)
+            return content;
+        return content.replace(/\{#([A-Za-z0-9-_]+)\}/g, (match, id, offset, str) => {
+            if (offset > 0 && str[offset - 1] === '\\') {
+                return match;
+            }
+            return `\\{#${id}\\}`;
+        });
+    };
     // Parse the translated content
     let processedAst;
     try {
@@ -144,7 +186,7 @@ function applyInlineIds(translatedContent, idMappings) {
     }
     catch (error) {
         console.warn(`Failed to parse translated MDX content: ${error instanceof Error ? error.message : String(error)}`);
-        return translatedContent;
+        return applyInlineIdsStringFallback(translatedContent, idMappings, escapeAnchors);
     }
     // Apply IDs to headings based on position
     let headingIndex = 0;
@@ -154,19 +196,33 @@ function applyInlineIds(translatedContent, idMappings) {
         if (id) {
             // Skip if heading already has explicit ID
             if (hasExplicitId(heading, processedAst)) {
+                if (escapeAnchors) {
+                    // Normalize existing inline IDs to escaped form
+                    const lastChild = heading.children[heading.children.length - 1];
+                    if (lastChild?.type === 'text') {
+                        const match = lastChild.value.match(/\{#([^}]+)\}\s*$/);
+                        const alreadyEscaped = lastChild.value.match(/\\\{#[^}]+\\\}\s*$/);
+                        if (match && !alreadyEscaped) {
+                            const anchorId = match[1];
+                            const base = lastChild.value.replace(/\s*\{#[^}]+\}\s*$/, '');
+                            lastChild.value = `${base} \\{#${anchorId}\\}`;
+                            actuallyModifiedContent = true;
+                        }
+                    }
+                }
                 headingIndex++;
                 return;
             }
             // Add the ID to the heading
             const lastChild = heading.children[heading.children.length - 1];
             if (lastChild?.type === 'text') {
-                lastChild.value += ` \\{#${id}\\}`;
+                lastChild.value += escapeAnchors ? ` \\{#${id}\\}` : ` {#${id}}`;
             }
             else {
                 // If last child is not text, add a new text node
                 heading.children.push({
                     type: 'text',
-                    value: ` \\{#${id}\\}`,
+                    value: escapeAnchors ? ` \\{#${id}\\}` : ` {#${id}}`,
                 });
             }
             actuallyModifiedContent = true;
@@ -175,7 +231,8 @@ function applyInlineIds(translatedContent, idMappings) {
     });
     // If we didn't modify any headings, return original content
     if (!actuallyModifiedContent) {
-        return translatedContent;
+        const escaped = escapeInlineAnchors(translatedContent);
+        return escaped;
     }
     // Convert the modified AST back to MDX string
     try {
@@ -208,6 +265,31 @@ function applyInlineIds(translatedContent, idMappings) {
         return translatedContent;
     }
 }
+/**
+ * Fallback string-based inline ID application when AST parsing fails
+ */
+function applyInlineIdsStringFallback(translatedContent, idMappings, escapeAnchors) {
+    let headingIndex = 0;
+    return translatedContent.replace(/^(#{1,6}\s+)(.*)$/gm, (match, prefix, text) => {
+        const id = idMappings.get(headingIndex++);
+        if (!id) {
+            return match;
+        }
+        const hasEscaped = /\\\{#[^}]+\\\}\s*$/.test(text);
+        const hasUnescaped = /\{#[^}]+\}\s*$/.test(text);
+        if (hasEscaped) {
+            return match;
+        }
+        if (hasUnescaped) {
+            if (!escapeAnchors) {
+                return match;
+            }
+            return `${prefix}${text.replace(/\{#([^}]+)\}\s*$/, '\\\\{#$1\\\\}')}`;
+        }
+        const suffix = escapeAnchors ? ` \\{#${id}\\}` : ` {#${id}}`;
+        return `${prefix}${text}${suffix}`;
+    });
+}
 /**
  * Wraps headings in divs with IDs (Mintlify approach)
  */

package/dist/utils/localizeStaticImports.js

@@ -52,7 +52,7 @@ export default async function localizeStaticImports(settings, includeFiles) {
                 const fileContent = await fs.promises.readFile(filePath, 'utf8');
                 // Localize the file using default locale
                 const localizedFile = localizeStaticImportsForFile(fileContent, settings.defaultLocale, settings.defaultLocale, // Process as default locale
-                settings.options?.docsHideDefaultLocaleImport || false, settings.options?.docsImportPattern, settings.options?.excludeStaticImports, filePath);
+                settings.options?.docsHideDefaultLocaleImport || false, settings.options?.docsImportPattern, settings.options?.excludeStaticImports, filePath, settings.options);
                 // Write the localized file back to the same path
                 await fs.promises.writeFile(filePath, localizedFile);
             }));
@@ -73,7 +73,7 @@ export default async function localizeStaticImports(settings, includeFiles) {
             // Get file content
             const fileContent = await fs.promises.readFile(filePath, 'utf8');
             // Localize the file
-            const localizedFile = localizeStaticImportsForFile(fileContent, settings.defaultLocale, locale, settings.options?.docsHideDefaultLocaleImport || false, settings.options?.docsImportPattern, settings.options?.excludeStaticImports, filePath);
+            const localizedFile = localizeStaticImportsForFile(fileContent, settings.defaultLocale, locale, settings.options?.docsHideDefaultLocaleImport || false, settings.options?.docsImportPattern, settings.options?.excludeStaticImports, filePath, settings.options);
             // Write the localized file to the target path
             await fs.promises.writeFile(filePath, localizedFile);
         }));
@@ -190,8 +190,33 @@ function transformNonDefaultLocaleImportPath(fullPath, patternHead, targetLocale
 /**
  * Main import path transformation function that delegates to specific scenarios
  */
-function transformImportPath(fullPath, patternHead, targetLocale, defaultLocale, hideDefaultLocale, currentFilePath, projectRoot = process.cwd() // fallback if not provided
-) {
+function transformImportPath(fullPath, patternHead, targetLocale, defaultLocale, hideDefaultLocale, currentFilePath, projectRoot = process.cwd(), // fallback if not provided
+rewrites) {
+    // Apply explicit rewrites first (e.g., Docusaurus @site/docs -> @site/i18n/[locale]/...)
+    if (rewrites && rewrites.length > 0) {
+        const localeMap = {
+            '[locale]': targetLocale,
+            '[defaultLocale]': defaultLocale,
+        };
+        for (const { match, replace } of rewrites) {
+            const resolvedMatch = match.replace(/\[locale\]|\[defaultLocale\]/g, (token) => localeMap[token] || token);
+            if (fullPath.startsWith(resolvedMatch)) {
+                const remainder = fullPath.slice(resolvedMatch.length);
+                const resolvedReplace = replace.replace(/\[locale\]|\[defaultLocale\]/g, (token) => localeMap[token] || token);
+                let newPath;
+                if (resolvedReplace.endsWith('/')) {
+                    newPath = `${resolvedReplace}${remainder.replace(/^\//, '')}`;
+                }
+                else if (remainder.startsWith('/')) {
+                    newPath = `${resolvedReplace}${remainder}`;
+                }
+                else {
+                    newPath = `${resolvedReplace}/${remainder}`;
+                }
+                return newPath;
+            }
+        }
+    }
     let newPath;
     if (targetLocale === defaultLocale) {
         newPath = transformDefaultLocaleImportPath(fullPath, patternHead, defaultLocale, hideDefaultLocale);
@@ -224,7 +249,7 @@ function transformImportPath(fullPath, patternHead, targetLocale, defaultLocale,
 /**
  * AST-based transformation for MDX files using remark-mdx
  */
-function transformMdxImports(mdxContent, defaultLocale, targetLocale, hideDefaultLocale, pattern = '/[locale]', exclude = [], currentFilePath) {
+function transformMdxImports(mdxContent, defaultLocale, targetLocale, hideDefaultLocale, pattern = '/[locale]', exclude = [], currentFilePath, options) {
     const transformedImports = [];
     // Don't auto-prefix relative patterns that start with . or ..
     if (!pattern.startsWith('/') && !pattern.startsWith('.')) {
@@ -310,7 +335,7 @@ function transformMdxImports(mdxContent, defaultLocale, targetLocale, hideDefaul
                         continue;
                     const fullPath = line.slice(pathStart, pathEnd);
                     // Transform the import path
-                    const newPath = transformImportPath(fullPath, patternHead, targetLocale, defaultLocale, hideDefaultLocale, currentFilePath);
+                    const newPath = transformImportPath(fullPath, patternHead, targetLocale, defaultLocale, hideDefaultLocale, currentFilePath, process.cwd(), options?.docsImportRewrites);
                     if (!newPath) {
                         continue; // No transformation needed
                     }
@@ -337,12 +362,8 @@ function transformMdxImports(mdxContent, defaultLocale, targetLocale, hideDefaul
  * AST-based transformation for MDX files only
  */
 function localizeStaticImportsForFile(file, defaultLocale, targetLocale, hideDefaultLocale, pattern = '/[locale]', // eg /docs/[locale] or /[locale]
-exclude = [], currentFilePath) {
-    // Skip .md files entirely - they cannot have imports
-    if (currentFilePath && currentFilePath.endsWith('.md')) {
-        return file;
-    }
+exclude = [], currentFilePath, options) {
     // For MDX files, use AST-based transformation
-    const result = transformMdxImports(file, defaultLocale, targetLocale, hideDefaultLocale, pattern, exclude, currentFilePath);
+    const result = transformMdxImports(file, defaultLocale, targetLocale, hideDefaultLocale, pattern, exclude, currentFilePath, options);
     return result.content;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gtx-cli",
-  "version": "2.5.13",
+  "version": "2.5.14",
   "main": "dist/index.js",
   "bin": "dist/main.js",
   "files": [