gtx-cli 2.1.8 → 2.1.10

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # gtx-cli
 
+## 2.1.10
+
+### Patch Changes
+
+- [#600](https://github.com/generaltranslation/gt/pull/600) [`e94aac2`](https://github.com/generaltranslation/gt/commit/e94aac2b2554a279245d090b0872f6f64eb71c62) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Added handling of fragment URLs (i.e. href="#my-mdx-id") for correct routing across locales.
+
+## 2.1.9
+
+### Patch Changes
+
+- [#604](https://github.com/generaltranslation/gt/pull/604) [`43c6a76`](https://github.com/generaltranslation/gt/commit/43c6a76be3d3be420e892b86188ef41c45ae8ffe) Thanks [@archie-mckenzie](https://github.com/archie-mckenzie)! - Refactored useGT and useMessages in order to make useMessages function like an unlintable useGT
+
+## 2.1.8
+
+### Patch Changes
+
+- [#599](https://github.com/generaltranslation/gt/pull/599) [`5950592`](https://github.com/generaltranslation/gt/commit/5950592ca44197915216ec5c8e26f9714cb4f55c) Thanks [@ErnestM1234](https://github.com/ErnestM1234)! - feat: msg() function
+
 ## 2.1.8
 
 ### Patch Changes

package/dist/cli/commands/translate.js

@@ -5,6 +5,7 @@ import { getStagedVersions } from '../../fs/config/updateVersions.js';
 import copyFile from '../../fs/copyFile.js';
 import flattenJsonFiles from '../../utils/flattenJsonFiles.js';
 import localizeStaticUrls from '../../utils/localizeStaticUrls.js';
+import processAnchorIds from '../../utils/processAnchorIds.js';
 import { noFilesError, noVersionIdError } from '../../console/index.js';
 // Downloads translations that were completed
 export async function handleTranslate(options, settings, filesTranslationResponse) {
@@ -34,13 +35,16 @@ export async function handleDownload(options, settings) {
     await checkFileTranslations(stagedVersionData, settings.locales, options.timeout, (sourcePath, locale) => fileMapping[locale][sourcePath] ?? null, settings);
 }
 export async function postProcessTranslations(settings) {
-    // Localize static urls (/docs -> /[locale]/docs) for non-default locales only
+    // Localize static urls (/docs -> /[locale]/docs) and preserve anchor IDs for non-default locales
     // Default locale is processed earlier in the flow in base.ts
     if (settings.options?.experimentalLocalizeStaticUrls) {
         const nonDefaultLocales = settings.locales.filter((locale) => locale !== settings.defaultLocale);
         if (nonDefaultLocales.length > 0) {
             await localizeStaticUrls(settings, nonDefaultLocales);
         }
+        // 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'
+        await processAnchorIds(settings);
     }
     // Flatten json files into a single file
     if (settings.options?.experimentalFlattenJsonFiles) {

package/dist/react/jsx/utils/constants.d.ts

@@ -1,3 +1,8 @@
+export declare const MSG_TRANSLATION_HOOK = "msg";
+export declare const INLINE_TRANSLATION_HOOK = "useGT";
+export declare const INLINE_TRANSLATION_HOOK_ASYNC = "getGT";
+export declare const INLINE_MESSAGE_HOOK = "useMessages";
+export declare const INLINE_MESSAGE_HOOK_ASYNC = "getMessages";
 export declare const GT_TRANSLATION_FUNCS: string[];
 export declare const VARIABLE_COMPONENTS: string[];
 export declare const GT_ATTRIBUTES_WITH_SUGAR: string[];

package/dist/react/jsx/utils/constants.js

@@ -1,7 +1,15 @@
+export const MSG_TRANSLATION_HOOK = 'msg';
+export const INLINE_TRANSLATION_HOOK = 'useGT';
+export const INLINE_TRANSLATION_HOOK_ASYNC = 'getGT';
+export const INLINE_MESSAGE_HOOK = 'useMessages';
+export const INLINE_MESSAGE_HOOK_ASYNC = 'getMessages';
 // GT translation functions
 export const GT_TRANSLATION_FUNCS = [
-    'useGT',
-    'getGT',
+    INLINE_TRANSLATION_HOOK,
+    INLINE_TRANSLATION_HOOK_ASYNC,
+    INLINE_MESSAGE_HOOK,
+    INLINE_MESSAGE_HOOK_ASYNC,
+    MSG_TRANSLATION_HOOK,
     'T',
     'Var',
     'DateTime',

package/dist/react/jsx/utils/parseStringFunction.js

@@ -1,6 +1,6 @@
 import * as t from '@babel/types';
 import { isStaticExpression } from '../evaluateJsx.js';
-import { GT_ATTRIBUTES_WITH_SUGAR, mapAttributeName } from './constants.js';
+import { GT_ATTRIBUTES_WITH_SUGAR, MSG_TRANSLATION_HOOK, INLINE_TRANSLATION_HOOK, INLINE_TRANSLATION_HOOK_ASYNC, mapAttributeName, INLINE_MESSAGE_HOOK, INLINE_MESSAGE_HOOK_ASYNC, } from './constants.js';
 import { warnNonStaticExpressionSync, warnNonStringSync, warnTemplateLiteralSync, warnAsyncUseGT, warnSyncGetGT, } from '../../../console/index.js';
 import generateModule from '@babel/generator';
 import traverseModule from '@babel/traverse';
@@ -22,7 +22,7 @@ import resolve from 'resolve';
  * - Metadata extraction from options object
  * - Error reporting for non-static expressions and template literals with expressions
  */
-function processTranslationCall(tPath, updates, errors, file) {
+function processTranslationCall(tPath, updates, errors, file, ignoreAdditionalData, ignoreDynamicContent) {
     if (tPath.parent.type === 'CallExpression' &&
         tPath.parent.arguments.length > 0) {
         const arg = tPath.parent.arguments[0];
@@ -43,7 +43,7 @@ function processTranslationCall(tPath, updates, errors, file) {
                             if (!result.isStatic) {
                                 errors.push(warnNonStaticExpressionSync(file, attribute, generate(prop.value).code, `${prop.loc?.start?.line}:${prop.loc?.start?.column}`));
                             }
-                            if (result.isStatic && result.value) {
+                            if (result.isStatic && result.value && !ignoreAdditionalData) {
                                 // Map $id and $context to id and context
                                 metadata[mapAttributeName(attribute)] = result.value;
                             }
@@ -59,10 +59,14 @@ function processTranslationCall(tPath, updates, errors, file) {
         }
         else if (t.isTemplateLiteral(arg)) {
             // warn if template literal
-            errors.push(warnTemplateLiteralSync(file, generate(arg).code, `${arg.loc?.start?.line}:${arg.loc?.start?.column}`));
+            if (!ignoreDynamicContent) {
+                errors.push(warnTemplateLiteralSync(file, generate(arg).code, `${arg.loc?.start?.line}:${arg.loc?.start?.column}`));
+            }
         }
         else {
-            errors.push(warnNonStringSync(file, generate(arg).code, `${arg.loc?.start?.line}:${arg.loc?.start?.column}`));
+            if (!ignoreDynamicContent) {
+                errors.push(warnNonStringSync(file, generate(arg).code, `${arg.loc?.start?.line}:${arg.loc?.start?.column}`));
+            }
         }
     }
 }
@@ -145,11 +149,11 @@ function resolveVariableAliases(scope, variableName, visited = new Set()) {
  * This covers both direct translation calls (t('hello')) and prop drilling
  * where the translation callback is passed to other functions (getData(t)).
  */
-function handleFunctionCall(tPath, updates, errors, file, importMap) {
+function handleFunctionCall(tPath, updates, errors, file, importMap, ignoreAdditionalData, ignoreDynamicContent) {
     if (tPath.parent.type === 'CallExpression' &&
         tPath.parent.callee === tPath.node) {
         // Direct translation call: t('hello')
-        processTranslationCall(tPath, updates, errors, file);
+        processTranslationCall(tPath, updates, errors, file, ignoreAdditionalData, ignoreDynamicContent);
     }
     else if (tPath.parent.type === 'CallExpression' &&
         t.isExpression(tPath.node) &&
@@ -161,7 +165,7 @@ function handleFunctionCall(tPath, updates, errors, file, importMap) {
             const calleeBinding = tPath.scope.getBinding(callee.name);
             if (calleeBinding && calleeBinding.path.isFunction()) {
                 const functionPath = calleeBinding.path;
-                processFunctionIfMatches(callee.name, argIndex, functionPath.node, functionPath, updates, errors, file);
+                processFunctionIfMatches(callee.name, argIndex, functionPath.node, functionPath, updates, errors, file, ignoreAdditionalData, ignoreDynamicContent);
             }
             // Handle arrow functions assigned to variables: const getData = (t) => {...}
             else if (calleeBinding &&
@@ -170,14 +174,14 @@ function handleFunctionCall(tPath, updates, errors, file, importMap) {
                 (t.isArrowFunctionExpression(calleeBinding.path.node.init) ||
                     t.isFunctionExpression(calleeBinding.path.node.init))) {
                 const initPath = calleeBinding.path.get('init');
-                processFunctionIfMatches(callee.name, argIndex, calleeBinding.path.node.init, initPath, updates, errors, file);
+                processFunctionIfMatches(callee.name, argIndex, calleeBinding.path.node.init, initPath, updates, errors, file, ignoreAdditionalData, ignoreDynamicContent);
             }
             // If not found locally, check if it's an imported function
             else if (importMap.has(callee.name)) {
                 const importPath = importMap.get(callee.name);
                 const resolvedPath = resolveImportPath(file, importPath);
                 if (resolvedPath) {
-                    findFunctionInFile(resolvedPath, callee.name, argIndex, updates, errors);
+                    findFunctionInFile(resolvedPath, callee.name, argIndex, updates, errors, ignoreAdditionalData, ignoreDynamicContent);
                 }
             }
         }
@@ -188,12 +192,12 @@ function handleFunctionCall(tPath, updates, errors, file, importMap) {
  * Validates the function has enough parameters and traces how the translation callback
  * is used within that function's body.
  */
-function processFunctionIfMatches(_functionName, argIndex, functionNode, functionPath, updates, errors, filePath) {
+function processFunctionIfMatches(_functionName, argIndex, functionNode, functionPath, updates, errors, filePath, ignoreAdditionalData, ignoreDynamicContent) {
     if (functionNode.params.length > argIndex) {
         const param = functionNode.params[argIndex];
         const paramName = extractParameterName(param);
         if (paramName) {
-            findFunctionParameterUsage(functionPath, paramName, updates, errors, filePath);
+            findFunctionParameterUsage(functionPath, paramName, updates, errors, filePath, ignoreAdditionalData, ignoreDynamicContent);
         }
     }
 }
@@ -205,7 +209,7 @@ function processFunctionIfMatches(_functionName, argIndex, functionNode, functio
  * Example: In function getInfo(t) { return t('hello'); }, this finds the t('hello') call.
  * Example: In function getData(t) { return getFooter(t); }, this finds and traces into getFooter.
  */
-function findFunctionParameterUsage(functionPath, parameterName, updates, errors, file) {
+function findFunctionParameterUsage(functionPath, parameterName, updates, errors, file, ignoreAdditionalData, ignoreDynamicContent) {
     // Look for the function body and find all usages of the parameter
     if (functionPath.isFunction()) {
         const functionScope = functionPath.scope;
@@ -220,7 +224,7 @@ function findFunctionParameterUsage(functionPath, parameterName, updates, errors
             const binding = functionScope.bindings[name];
             if (binding) {
                 binding.referencePaths.forEach((refPath) => {
-                    handleFunctionCall(refPath, updates, errors, file, importMap);
+                    handleFunctionCall(refPath, updates, errors, file, importMap, ignoreAdditionalData, ignoreDynamicContent);
                 });
             }
         });
@@ -299,7 +303,7 @@ function resolveImportPath(currentFile, importPath) {
  * - export function getInfo(t) { ... }
  * - const getInfo = (t) => { ... }
  */
-function findFunctionInFile(filePath, functionName, argIndex, updates, errors) {
+function findFunctionInFile(filePath, functionName, argIndex, updates, errors, ignoreAdditionalData, ignoreDynamicContent) {
     try {
         const code = fs.readFileSync(filePath, 'utf8');
         const ast = parse(code, {
@@ -310,7 +314,7 @@ function findFunctionInFile(filePath, functionName, argIndex, updates, errors) {
             // Handle function declarations: function getInfo(t) { ... }
             FunctionDeclaration(path) {
                 if (path.node.id?.name === functionName) {
-                    processFunctionIfMatches(functionName, argIndex, path.node, path, updates, errors, filePath);
+                    processFunctionIfMatches(functionName, argIndex, path.node, path, updates, errors, filePath, ignoreAdditionalData, ignoreDynamicContent);
                 }
             },
             // Handle variable declarations: const getInfo = (t) => { ... }
@@ -321,7 +325,7 @@ function findFunctionInFile(filePath, functionName, argIndex, updates, errors) {
                     (t.isArrowFunctionExpression(path.node.init) ||
                         t.isFunctionExpression(path.node.init))) {
                     const initPath = path.get('init');
-                    processFunctionIfMatches(functionName, argIndex, path.node.init, initPath, updates, errors, filePath);
+                    processFunctionIfMatches(functionName, argIndex, path.node.init, initPath, updates, errors, filePath, ignoreAdditionalData, ignoreDynamicContent);
                 }
             },
         });
@@ -348,21 +352,40 @@ export function parseStrings(importName, originalName, path, updates, errors, fi
     const importMap = buildImportMap(path.scope.getProgramParent().path);
     const referencePaths = path.scope.bindings[importName]?.referencePaths || [];
     for (const refPath of referencePaths) {
-        // Find call expressions of useGT() / await getGT()
+        // Handle msg() calls directly without variable assignment
+        if (originalName === MSG_TRANSLATION_HOOK) {
+            const ignoreAdditionalData = false;
+            const ignoreDynamicContent = false;
+            // Check if this is a direct call to msg('string')
+            if (refPath.parent.type === 'CallExpression' &&
+                refPath.parent.callee === refPath.node) {
+                processTranslationCall(refPath, updates, errors, file, ignoreAdditionalData, ignoreDynamicContent);
+            }
+            continue;
+        }
+        // Handle useGT(), getGT(), useMessages(), and getMessages() calls that need variable assignment
         const callExpr = refPath.findParent((p) => p.isCallExpression());
         if (callExpr) {
             // Get the parent, handling both await and non-await cases
             const parentPath = callExpr.parentPath;
             const parentFunction = refPath.getFunctionParent();
             const asyncScope = parentFunction?.node.async;
-            if (asyncScope && originalName === 'useGT') {
+            if (asyncScope &&
+                (originalName === INLINE_TRANSLATION_HOOK ||
+                    originalName === INLINE_MESSAGE_HOOK)) {
                 errors.push(warnAsyncUseGT(file, `${refPath.node.loc?.start?.line}:${refPath.node.loc?.start?.column}`));
                 return;
             }
-            else if (!asyncScope && originalName === 'getGT') {
+            else if (!asyncScope &&
+                (originalName === INLINE_TRANSLATION_HOOK_ASYNC ||
+                    originalName === INLINE_MESSAGE_HOOK_ASYNC)) {
                 errors.push(warnSyncGetGT(file, `${refPath.node.loc?.start?.line}:${refPath.node.loc?.start?.column}`));
                 return;
             }
+            const isMessageHook = originalName === INLINE_MESSAGE_HOOK ||
+                originalName === INLINE_MESSAGE_HOOK_ASYNC;
+            const ignoreAdditionalData = isMessageHook;
+            const ignoreDynamicContent = isMessageHook;
             const effectiveParent = parentPath?.node.type === 'AwaitExpression'
                 ? parentPath.parentPath
                 : parentPath;
@@ -372,10 +395,16 @@ export function parseStrings(importName, originalName, path, updates, errors, fi
                 const tFuncName = effectiveParent.node.id.name;
                 // Get the scope from the variable declaration
                 const variableScope = effectiveParent.scope;
-                const tReferencePaths = variableScope.bindings[tFuncName]?.referencePaths || [];
-                for (const tPath of tReferencePaths) {
-                    handleFunctionCall(tPath, updates, errors, file, importMap);
-                }
+                // Resolve all aliases of the translation function
+                // Example: translate -> [translate, t, a, b] for const t = translate; const a = t; const b = a;
+                const allTranslationNames = resolveVariableAliases(variableScope, tFuncName);
+                // Process references for all translation function names and their aliases
+                allTranslationNames.forEach((name) => {
+                    const tReferencePaths = variableScope.bindings[name]?.referencePaths || [];
+                    for (const tPath of tReferencePaths) {
+                        handleFunctionCall(tPath, updates, errors, file, importMap, ignoreAdditionalData, ignoreDynamicContent);
+                    }
+                });
             }
         }
     }

package/dist/react/jsx/utils/validateStringFunction.js

@@ -1,4 +1,5 @@
 import { warnAsyncUseGT, warnSyncGetGT } from '../../../console/index.js';
+import { INLINE_TRANSLATION_HOOK, INLINE_TRANSLATION_HOOK_ASYNC, } from './constants.js';
 /**
  * Validate useGT() / await getGT() calls
  * 1. Validates that the call does not violate the rules of React (no hooks in async functions)
@@ -12,13 +13,13 @@ export function validateStringFunction(localImportName, path, updates, errors, f
                 callPath.node.callee.name === localImportName) {
                 // Check the function scope
                 const functionScope = callPath.getFunctionParent();
-                if (originalImportName === 'useGT') {
+                if (originalImportName === INLINE_TRANSLATION_HOOK) {
                     // useGT should NOT be in an async function
                     if (functionScope && functionScope.node.async) {
                         errors.push(warnAsyncUseGT(file, `${callPath.node.loc?.start?.line}:${callPath.node.loc?.start?.column}`));
                     }
                 }
-                else if (originalImportName === 'getGT') {
+                else if (originalImportName === INLINE_TRANSLATION_HOOK_ASYNC) {
                     // getGT should be in an async function
                     if (!functionScope || !functionScope.node.async) {
                         errors.push(warnSyncGetGT(file, `${callPath.node.loc?.start?.line}:${callPath.node.loc?.start?.column}`));

package/dist/react/parse/createInlineUpdates.js

@@ -8,7 +8,7 @@ import { parseJSXElement } from '../jsx/utils/parseJsx.js';
 import { parseStrings } from '../jsx/utils/parseStringFunction.js';
 import { extractImportName } from '../jsx/utils/parseAst.js';
 import { logError } from '../../console/logging.js';
-import { GT_TRANSLATION_FUNCS } from '../jsx/utils/constants.js';
+import { GT_TRANSLATION_FUNCS, INLINE_TRANSLATION_HOOK, INLINE_TRANSLATION_HOOK_ASYNC, INLINE_MESSAGE_HOOK, INLINE_MESSAGE_HOOK_ASYNC, MSG_TRANSLATION_HOOK, } from '../jsx/utils/constants.js';
 import { matchFiles } from '../../fs/matchFiles.js';
 import { DEFAULT_SRC_PATTERNS } from '../../config/generateSettings.js';
 export async function createInlineUpdates(pkg, validate, filePatterns) {
@@ -38,7 +38,11 @@ export async function createInlineUpdates(pkg, validate, filePatterns) {
                 if (path.node.source.value.startsWith(pkg)) {
                     const importName = extractImportName(path.node, pkg, GT_TRANSLATION_FUNCS);
                     for (const name of importName) {
-                        if (name.original === 'useGT' || name.original === 'getGT') {
+                        if (name.original === INLINE_TRANSLATION_HOOK ||
+                            name.original === INLINE_TRANSLATION_HOOK_ASYNC ||
+                            name.original === INLINE_MESSAGE_HOOK ||
+                            name.original === INLINE_MESSAGE_HOOK_ASYNC ||
+                            name.original === MSG_TRANSLATION_HOOK) {
                             translationPaths.push({
                                 localName: name.local,
                                 path,
@@ -65,7 +69,11 @@ export async function createInlineUpdates(pkg, validate, filePatterns) {
                         if (parentPath.isVariableDeclaration()) {
                             const importName = extractImportName(parentPath.node, pkg, GT_TRANSLATION_FUNCS);
                             for (const name of importName) {
-                                if (name.original === 'useGT' || name.original === 'getGT') {
+                                if (name.original === INLINE_TRANSLATION_HOOK ||
+                                    name.original === INLINE_TRANSLATION_HOOK_ASYNC ||
+                                    name.original === INLINE_MESSAGE_HOOK ||
+                                    name.original === INLINE_MESSAGE_HOOK_ASYNC ||
+                                    name.original === MSG_TRANSLATION_HOOK) {
                                     translationPaths.push({
                                         localName: name.local,
                                         path: parentPath,

package/dist/types/index.d.ts

@@ -21,6 +21,7 @@ export type Options = {
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     experimentalLocalizeStaticImports?: boolean;
+    experimentalAddHeaderAnchorIds?: 'mintlify';
 };
 export type TranslateFlags = {
     config?: string;
@@ -41,6 +42,7 @@ export type TranslateFlags = {
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     experimentalLocalizeStaticImports?: boolean;
+    experimentalAddHeaderAnchorIds?: 'mintlify';
     excludeStaticUrls?: string[];
     excludeStaticImports?: string[];
 };
@@ -139,6 +141,7 @@ export type AdditionalOptions = {
     copyFiles?: string[];
     experimentalLocalizeStaticImports?: boolean;
     experimentalLocalizeStaticUrls?: boolean;
+    experimentalAddHeaderAnchorIds?: 'mintlify';
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     baseDomain?: string;

package/dist/utils/addExplicitAnchorIds.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Represents a heading with its position and metadata
+ */
+export interface HeadingInfo {
+    text: string;
+    level: number;
+    slug: string;
+    position: number;
+}
+/**
+ * Extracts heading information from content (read-only, no modifications)
+ */
+export declare function extractHeadingInfo(mdxContent: string): HeadingInfo[];
+/**
+ * Applies anchor IDs to translated content based on source heading mapping
+ */
+export declare function addExplicitAnchorIds(translatedContent: string, sourceHeadingMap: HeadingInfo[], settings?: any, sourcePath?: string, translatedPath?: string): {
+    content: string;
+    hasChanges: boolean;
+    addedIds: Array<{
+        heading: string;
+        id: string;
+    }>;
+};

package/dist/utils/addExplicitAnchorIds.js

@@ -0,0 +1,263 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkMdx from 'remark-mdx';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkStringify from 'remark-stringify';
+import { visit } from 'unist-util-visit';
+import { logErrorAndExit } from '../console/logging.js';
+/**
+ * Generates a slug from heading text
+ */
+function generateSlug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, '') // Remove special chars except spaces and hyphens
+        .trim()
+        .replace(/\s+/g, '-') // Replace spaces with hyphens
+        .replace(/-+/g, '-') // Replace multiple hyphens with single hyphen
+        .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+}
+/**
+ * Extracts text content from heading nodes
+ */
+function extractHeadingText(heading) {
+    let text = '';
+    visit(heading, ['text', 'inlineCode'], (node) => {
+        if ('value' in node && typeof node.value === 'string') {
+            text += node.value;
+        }
+    });
+    return text;
+}
+/**
+ * Checks if a heading is already wrapped in a div with id
+ */
+function hasExplicitId(heading, ast) {
+    const lastChild = heading.children[heading.children.length - 1];
+    if (lastChild?.type === 'text') {
+        return /(\{#[^}]+\}|\[[^\]]+\])$/.test(lastChild.value);
+    }
+    return false;
+}
+/**
+ * Extracts heading information from content (read-only, no modifications)
+ */
+export function extractHeadingInfo(mdxContent) {
+    const headings = [];
+    // Parse the MDX content into an AST
+    let processedAst;
+    try {
+        const parseProcessor = unified()
+            .use(remarkParse)
+            .use(remarkFrontmatter, ['yaml', 'toml'])
+            .use(remarkMdx);
+        const ast = parseProcessor.parse(mdxContent);
+        processedAst = parseProcessor.runSync(ast);
+    }
+    catch (error) {
+        console.warn(`Failed to parse MDX content: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+    let position = 0;
+    visit(processedAst, 'heading', (heading) => {
+        const headingText = extractHeadingText(heading);
+        if (headingText) {
+            const slug = generateSlug(headingText);
+            headings.push({
+                text: headingText,
+                level: heading.depth,
+                slug,
+                position: position++,
+            });
+        }
+    });
+    return headings;
+}
+/**
+ * Applies anchor IDs to translated content based on source heading mapping
+ */
+export function addExplicitAnchorIds(translatedContent, sourceHeadingMap, settings, sourcePath, translatedPath) {
+    const addedIds = [];
+    const useDivWrapping = settings?.options?.experimentalAddHeaderAnchorIds === 'mintlify';
+    // Extract headings from translated content
+    const translatedHeadings = extractHeadingInfo(translatedContent);
+    // Pre-processing validation: check if header counts match
+    if (sourceHeadingMap.length !== translatedHeadings.length) {
+        const sourceFile = sourcePath
+            ? `Source file: ${sourcePath}`
+            : 'Source file';
+        const translatedFile = translatedPath
+            ? `translated file: ${translatedPath}`
+            : 'translated file';
+        logErrorAndExit(`Header count mismatch detected! ${sourceFile} has ${sourceHeadingMap.length} headers but ${translatedFile} has ${translatedHeadings.length} headers. ` +
+            `This likely means your source file was edited after translation was requested, causing a mismatch between ` +
+            `the number of headers in your source file vs the translated file. Please re-translate this file to resolve the issue.`);
+    }
+    // Create ID mapping based on positional matching
+    const idMappings = new Map();
+    sourceHeadingMap.forEach((sourceHeading, index) => {
+        const translatedHeading = translatedHeadings[index];
+        // Match by position and level for safety
+        if (translatedHeading && translatedHeading.level === sourceHeading.level) {
+            idMappings.set(index, sourceHeading.slug);
+            addedIds.push({
+                heading: translatedHeading.text,
+                id: sourceHeading.slug,
+            });
+        }
+    });
+    if (idMappings.size === 0) {
+        return {
+            content: translatedContent,
+            hasChanges: false,
+            addedIds: [],
+        };
+    }
+    // Apply IDs to translated content
+    let content;
+    if (useDivWrapping) {
+        content = applyDivWrappedIds(translatedContent, translatedHeadings, idMappings);
+    }
+    else {
+        content = applyInlineIds(translatedContent, idMappings);
+    }
+    return {
+        content,
+        hasChanges: addedIds.length > 0,
+        addedIds,
+    };
+}
+/**
+ * Adds inline {#id} syntax to headings (standard markdown approach)
+ */
+function applyInlineIds(translatedContent, idMappings) {
+    // Parse the translated content
+    let processedAst;
+    try {
+        const parseProcessor = unified()
+            .use(remarkParse)
+            .use(remarkFrontmatter, ['yaml', 'toml'])
+            .use(remarkMdx);
+        const ast = parseProcessor.parse(translatedContent);
+        processedAst = parseProcessor.runSync(ast);
+    }
+    catch (error) {
+        console.warn(`Failed to parse translated MDX content: ${error instanceof Error ? error.message : String(error)}`);
+        return translatedContent;
+    }
+    // Apply IDs to headings based on position
+    let headingIndex = 0;
+    visit(processedAst, 'heading', (heading) => {
+        const id = idMappings.get(headingIndex);
+        if (id) {
+            // Skip if heading already has explicit ID
+            if (hasExplicitId(heading, processedAst)) {
+                headingIndex++;
+                return;
+            }
+            // Add the ID to the heading
+            const lastChild = heading.children[heading.children.length - 1];
+            if (lastChild?.type === 'text') {
+                lastChild.value += ` {#${id}}`;
+            }
+            else {
+                // If last child is not text, add a new text node
+                heading.children.push({
+                    type: 'text',
+                    value: ` {#${id}}`,
+                });
+            }
+        }
+        headingIndex++;
+    });
+    // Convert the modified AST back to MDX string
+    try {
+        const stringifyProcessor = unified()
+            .use(remarkStringify, {
+            bullet: '-',
+            emphasis: '_',
+            strong: '*',
+            rule: '-',
+            ruleRepetition: 3,
+            ruleSpaces: false,
+            handlers: {
+                // Custom handler to prevent escaping of {#id} syntax
+                text(node) {
+                    return node.value;
+                },
+            },
+        })
+            .use(remarkFrontmatter, ['yaml', 'toml'])
+            .use(remarkMdx);
+        let content = stringifyProcessor.stringify(processedAst);
+        // Handle newline formatting to match original input
+        if (content.endsWith('\n') && !translatedContent.endsWith('\n')) {
+            content = content.slice(0, -1);
+        }
+        // Preserve leading newlines from original content
+        if (translatedContent.startsWith('\n') && !content.startsWith('\n')) {
+            content = '\n' + content;
+        }
+        return content;
+    }
+    catch (error) {
+        console.warn(`Failed to stringify translated MDX content: ${error instanceof Error ? error.message : String(error)}`);
+        return translatedContent;
+    }
+}
+/**
+ * Wraps headings in divs with IDs (Mintlify approach)
+ */
+function applyDivWrappedIds(translatedContent, translatedHeadings, idMappings) {
+    // Extract all heading lines from the translated markdown
+    const lines = translatedContent.split('\n');
+    const headingLines = [];
+    lines.forEach((line, index) => {
+        const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+        if (headingMatch) {
+            const level = headingMatch[1].length;
+            headingLines.push({ line, level, index });
+        }
+    });
+    // Use string-based approach to wrap headings in divs
+    let content = translatedContent;
+    const headingsToWrap = [];
+    // Match translated headings with their corresponding lines by position and level
+    translatedHeadings.forEach((heading, position) => {
+        const id = idMappings.get(position);
+        if (id) {
+            // Find the corresponding original line for this heading
+            const matchingLine = headingLines.find((hl) => {
+                // Extract clean text from the original line for comparison
+                const lineCleanText = hl.line.replace(/^#{1,6}\s+/, '').trim();
+                // Create a version without markdown formatting for comparison
+                const cleanLineText = lineCleanText
+                    .replace(/\*\*(.*?)\*\*/g, '$1') // Remove bold
+                    .replace(/\*(.*?)\*/g, '$1') // Remove italic
+                    .replace(/`(.*?)`/g, '$1') // Remove inline code
+                    .replace(/\[(.*?)\]\(.*?\)/g, '$1') // Remove links, keep text
+                    .trim();
+                return cleanLineText === heading.text && hl.level === heading.level;
+            });
+            if (matchingLine) {
+                headingsToWrap.push({
+                    originalLine: matchingLine.line,
+                    id,
+                });
+            }
+        }
+    });
+    if (headingsToWrap.length > 0) {
+        // Process headings from longest to shortest original line to avoid partial matches
+        const sortedHeadings = headingsToWrap.sort((a, b) => b.originalLine.length - a.originalLine.length);
+        for (const heading of sortedHeadings) {
+            // Escape the original line for use in regex
+            const escapedLine = heading.originalLine.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const headingPattern = new RegExp(`^${escapedLine}\\s*$`, 'gm');
+            content = content.replace(headingPattern, (match) => {
+                return `<div id="${heading.id}">\n  ${match.trim()}\n</div>\n`;
+            });
+        }
+    }
+    return content;
+}

package/dist/utils/localizeStaticUrls.js

@@ -87,6 +87,10 @@ export default async function localizeStaticUrls(settings, targetLocales) {
  * Determines if a URL should be processed based on pattern matching
  */
 function shouldProcessUrl(originalUrl, patternHead, targetLocale, defaultLocale, baseDomain) {
+    // Check fragment-only URLs like "#id-name"
+    if (/^\s*#/.test(originalUrl)) {
+        return false;
+    }
     const patternWithoutSlash = patternHead.replace(/\/$/, '');
     // Handle absolute URLs with baseDomain
     let urlToCheck = originalUrl;

package/dist/utils/processAnchorIds.d.ts

@@ -0,0 +1,6 @@
+import { Settings } from '../types/index.js';
+/**
+ * Processes all translated MD/MDX files to add explicit anchor IDs
+ * This preserves navigation links when headings are translated
+ */
+export default function processAnchorIds(settings: Settings): Promise<void>;

package/dist/utils/processAnchorIds.js

@@ -0,0 +1,43 @@
+import { addExplicitAnchorIds, extractHeadingInfo, } from './addExplicitAnchorIds.js';
+import { readFile } from '../fs/findFilepath.js';
+import { createFileMapping } from '../formats/files/fileMapping.js';
+import * as fs from 'fs';
+/**
+ * Processes all translated MD/MDX files to add explicit anchor IDs
+ * This preserves navigation links when headings are translated
+ */
+export default async function processAnchorIds(settings) {
+    if (!settings.files)
+        return;
+    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+    // Process each locale's translated files
+    const processPromises = Object.entries(fileMapping)
+        .filter(([locale, filesMap]) => locale !== settings.defaultLocale) // Skip default locale
+        .map(async ([locale, filesMap]) => {
+        // Get all translated files that are md or mdx
+        const translatedFiles = Object.values(filesMap).filter((path) => path && (path.endsWith('.md') || path.endsWith('.mdx')));
+        for (const translatedPath of translatedFiles) {
+            try {
+                // Find the corresponding source file
+                const sourcePath = Object.keys(filesMap).find((key) => filesMap[key] === translatedPath);
+                if (!sourcePath) {
+                    continue;
+                }
+                // Extract heading info from source file
+                const sourceContent = readFile(sourcePath);
+                const sourceHeadingMap = extractHeadingInfo(sourceContent);
+                // Read translated file and apply anchor IDs
+                const translatedContent = readFile(translatedPath);
+                const result = addExplicitAnchorIds(translatedContent, sourceHeadingMap, settings, sourcePath, translatedPath);
+                if (result.hasChanges) {
+                    fs.writeFileSync(translatedPath, result.content, 'utf8');
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to process IDs for ${translatedPath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    });
+    await Promise.all(processPromises);
+}

package/package.json

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