gtx-cli 2.3.14 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # gtx-cli
 
+## 2.4.0
+
+### Minor Changes
+
+- [#745](https://github.com/generaltranslation/gt/pull/745) [`5208937`](https://github.com/generaltranslation/gt/commit/520893719480b40774ccd749fe73727cf490f46c) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Adding local translation editing. Local user edits to translation will now be saved and used to inform future translations of the same file.
+
+### Patch Changes
+
+- Updated dependencies [[`5208937`](https://github.com/generaltranslation/gt/commit/520893719480b40774ccd749fe73727cf490f46c)]:
+  - generaltranslation@7.7.0
+
+## 2.3.15
+
+### Patch Changes
+
+- [#741](https://github.com/generaltranslation/gt/pull/741) [`559c0bf`](https://github.com/generaltranslation/gt/commit/559c0bfa7ff9e6664f65317eddbab419682a3c95) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Avoid localizing relative MDX links
+
 ## 2.3.14
 
 ### Patch Changes

package/dist/api/checkFileTranslations.js

@@ -225,6 +225,7 @@ async function checkTranslationDeployment(fileQueryData, downloadStatus, spinner
                     outputPath,
                     locale,
                     fileLocale: `${fileName}:${locale}`,
+                    fileId: translation.fileId,
                     versionId: versionMap.get(`${fileName}:${locale}`),
                 };
             })

package/dist/api/collectUserEditDiffs.d.ts

@@ -0,0 +1,14 @@
+import { Settings } from '../types/index.js';
+type UploadedFileRef = {
+    fileId: string;
+    versionId: string;
+    fileName: string;
+};
+/**
+ * Collects local user edits by diffing the latest downloaded server translation version
+ * against the current local translation file, and submits the diffs upstream.
+ *
+ * Must run before enqueueing new translations so rules are available to the generator.
+ */
+export declare function collectAndSendUserEditDiffs(uploadedFiles: UploadedFileRef[], settings: Settings): Promise<void>;
+export {};

package/dist/api/collectUserEditDiffs.js

@@ -0,0 +1,157 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getDownloadedVersions } from '../fs/config/downloadedVersions.js';
+import { createFileMapping } from '../formats/files/fileMapping.js';
+import { getGitUnifiedDiff } from '../utils/gitDiff.js';
+import { sendUserEditDiffs } from './sendUserEdits.js';
+import { gt } from '../utils/gt.js';
+const MAX_DIFF_BATCH_BYTES = 1_500_000;
+const MAX_DOWNLOAD_BATCH = 100;
+/**
+ * Collects local user edits by diffing the latest downloaded server translation version
+ * against the current local translation file, and submits the diffs upstream.
+ *
+ * Must run before enqueueing new translations so rules are available to the generator.
+ */
+export async function collectAndSendUserEditDiffs(uploadedFiles, settings) {
+    if (!settings.files)
+        return;
+    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+    const downloadedVersions = getDownloadedVersions(settings.configDirectory);
+    const tempDir = path.join(settings.configDirectory, 'tmp');
+    if (!fs.existsSync(tempDir))
+        fs.mkdirSync(tempDir, { recursive: true });
+    const candidates = [];
+    for (const uploadedFile of uploadedFiles) {
+        for (const locale of settings.locales) {
+            const resolvedLocale = gt.resolveAliasLocale(locale);
+            const outputPath = fileMapping[locale]?.[uploadedFile.fileName] ?? null;
+            if (!outputPath)
+                continue;
+            if (!fs.existsSync(outputPath))
+                continue;
+            const lockKeyById = uploadedFile.fileId
+                ? `${uploadedFile.fileId}:${resolvedLocale}`
+                : null;
+            const lockKeyByName = `${uploadedFile.fileName}:${resolvedLocale}`;
+            const lockEntry = (lockKeyById && downloadedVersions.entries[lockKeyById]) ||
+                downloadedVersions.entries[lockKeyByName];
+            const versionId = lockEntry?.versionId;
+            if (!versionId)
+                continue;
+            candidates.push({
+                fileName: uploadedFile.fileName,
+                fileId: uploadedFile.fileId,
+                versionId,
+                locale: resolvedLocale,
+                outputPath,
+            });
+        }
+    }
+    const collectedDiffs = [];
+    if (candidates.length > 0) {
+        const fileQueryData = candidates.map((c) => ({
+            versionId: c.versionId,
+            fileName: c.fileName,
+            locale: c.locale,
+        }));
+        // Single batched check to obtain translation IDs
+        const checkResponse = await gt.checkFileTranslations(fileQueryData);
+        const translations = (checkResponse?.translations || []).filter((t) => t && t.isReady && t.id && t.fileName && t.locale);
+        // Map fileName:resolvedLocale -> translationId
+        const idByKey = new Map();
+        for (const t of translations) {
+            const resolved = gt.resolveAliasLocale(t.locale);
+            idByKey.set(`${t.fileName}:${resolved}`, t.id);
+        }
+        // Collect translation IDs in batches and download contents
+        const ids = [];
+        for (const c of candidates) {
+            const id = idByKey.get(`${c.fileName}:${c.locale}`);
+            if (id)
+                ids.push(id);
+        }
+        // Helper to chunk array
+        function chunk(arr, size) {
+            const res = [];
+            for (let i = 0; i < arr.length; i += size)
+                res.push(arr.slice(i, i + size));
+            return res;
+        }
+        const serverContentByKey = new Map();
+        for (const idChunk of chunk(ids, MAX_DOWNLOAD_BATCH)) {
+            try {
+                const resp = await gt.downloadFileBatch(idChunk);
+                const files = resp?.files || [];
+                for (const f of files) {
+                    // Find corresponding candidate key via idByKey reverse lookup
+                    for (const [key, id] of idByKey.entries()) {
+                        if (id === f.id) {
+                            serverContentByKey.set(key, f.data);
+                            break;
+                        }
+                    }
+                }
+            }
+            catch {
+                // Ignore chunk failures; proceed with what we have
+            }
+        }
+        // Compute diffs using fetched server contents
+        for (const c of candidates) {
+            const key = `${c.fileName}:${c.locale}`;
+            const serverContent = serverContentByKey.get(key);
+            if (!serverContent)
+                continue;
+            try {
+                const safeName = Buffer.from(`${c.fileName}:${c.locale}`)
+                    .toString('base64')
+                    .replace(/=+$/g, '');
+                const tempServerFile = path.join(tempDir, `${safeName}.server`);
+                await fs.promises.writeFile(tempServerFile, serverContent, 'utf8');
+                const diff = await getGitUnifiedDiff(tempServerFile, c.outputPath);
+                try {
+                    await fs.promises.unlink(tempServerFile);
+                }
+                catch { }
+                if (diff && diff.trim().length > 0) {
+                    const localContent = await fs.promises.readFile(c.outputPath, 'utf8');
+                    collectedDiffs.push({
+                        fileName: c.fileName,
+                        locale: c.locale,
+                        diff,
+                        versionId: c.versionId,
+                        fileId: c.fileId,
+                        localContent,
+                    });
+                }
+            }
+            catch {
+                // Ignore failures for this file
+            }
+        }
+    }
+    if (collectedDiffs.length > 0) {
+        // Batch by payload size
+        const maxBatchBytes = MAX_DIFF_BATCH_BYTES;
+        const batches = [];
+        let currentBatch = [];
+        for (const d of collectedDiffs) {
+            const tentative = [...currentBatch, d];
+            const bytes = Buffer.byteLength(JSON.stringify({ projectId: settings.projectId, diffs: tentative }), 'utf8');
+            if (bytes > maxBatchBytes && currentBatch.length > 0) {
+                batches.push(currentBatch);
+                currentBatch = [d];
+            }
+            else {
+                currentBatch = tentative;
+            }
+        }
+        if (currentBatch.length > 0)
+            batches.push(currentBatch);
+        for (const batch of batches) {
+            await sendUserEditDiffs(batch, settings);
+        }
+    }
+}

package/dist/api/saveLocalEdits.d.ts

@@ -0,0 +1,6 @@
+import { Settings } from '../types/index.js';
+/**
+ * Uploads current source files to obtain file references, then collects and sends
+ * diffs for all locales based on last downloaded versions. Does not enqueue translations.
+ */
+export declare function saveLocalEdits(settings: Settings): Promise<void>;

package/dist/api/saveLocalEdits.js

@@ -0,0 +1,30 @@
+import { gt } from '../utils/gt.js';
+import { aggregateFiles } from '../formats/files/translate.js';
+import { collectAndSendUserEditDiffs } from './collectUserEditDiffs.js';
+/**
+ * Uploads current source files to obtain file references, then collects and sends
+ * diffs for all locales based on last downloaded versions. Does not enqueue translations.
+ */
+export async function saveLocalEdits(settings) {
+    if (!settings.files)
+        return;
+    // Collect current files from config
+    const files = await aggregateFiles(settings);
+    if (!files.length)
+        return;
+    const uploads = files.map(({ content, fileName, fileFormat, dataFormat }) => ({
+        source: {
+            content,
+            fileName,
+            fileFormat,
+            dataFormat,
+            locale: settings.defaultLocale,
+        },
+    }));
+    // Upload sources only to get file references, then compute diffs
+    const upload = await gt.uploadSourceFiles(uploads, {
+        sourceLocale: settings.defaultLocale,
+        modelProvider: settings.modelProvider,
+    });
+    await collectAndSendUserEditDiffs(upload.uploadedFiles, settings);
+}

package/dist/api/sendFiles.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { createSpinner, logErrorAndExit, logMessage, logSuccess, } from '../console/logging.js';
 import { gt } from '../utils/gt.js';
 import { TEMPLATE_FILE_NAME } from '../cli/commands/stage.js';
+import { collectAndSendUserEditDiffs } from './collectUserEditDiffs.js';
 /**
  * Sends multiple files for translation to the API
  * @param files - Array of file objects to translate
@@ -88,7 +89,20 @@ export async function sendFiles(files, options, settings) {
                 setupSpinner.stop(chalk.yellow(`Setup ${setupFailedMessage ? 'failed' : 'timed out'} — proceeding without setup${setupFailedMessage ? ` (${setupFailedMessage})` : ''}`));
             }
         }
-        // Step 3: Enqueue translations by reference
+        // Step 3: Prior to enqueue, detect and submit user edit diffs (minimal UX)
+        const prepSpinner = createSpinner('dots');
+        currentSpinner = prepSpinner;
+        prepSpinner.start('Updating translations...');
+        try {
+            await collectAndSendUserEditDiffs(upload.uploadedFiles, settings);
+        }
+        catch {
+            // Non-fatal; keep going to enqueue
+        }
+        finally {
+            prepSpinner.stop('Updated translations');
+        }
+        // Step 4: Enqueue translations by reference
         const enqueueSpinner = createSpinner('dots');
         currentSpinner = enqueueSpinner;
         enqueueSpinner.start('Enqueuing translations...');

package/dist/api/sendUserEdits.d.ts

@@ -0,0 +1,19 @@
+import { Settings } from '../types/index.js';
+export type UserEditDiff = {
+    fileName: string;
+    locale: string;
+    diff: string;
+    versionId?: string;
+    fileId?: string;
+    localContent?: string;
+};
+export type SendUserEditsPayload = {
+    projectId?: string;
+    diffs: UserEditDiff[];
+};
+/**
+ * Sends user edit diffs to the API for persistence/rule extraction.
+ * This function is intentionally decoupled from the translate pipeline
+ * so it can be called as an independent action.
+ */
+export declare function sendUserEditDiffs(diffs: UserEditDiff[], settings: Settings): Promise<void>;

package/dist/api/sendUserEdits.js

@@ -0,0 +1,15 @@
+import { gt } from '../utils/gt.js';
+/**
+ * Sends user edit diffs to the API for persistence/rule extraction.
+ * This function is intentionally decoupled from the translate pipeline
+ * so it can be called as an independent action.
+ */
+export async function sendUserEditDiffs(diffs, settings) {
+    if (!diffs.length)
+        return;
+    const payload = {
+        projectId: settings.projectId,
+        diffs,
+    };
+    await gt.submitUserEditDiffs(payload);
+}

package/dist/cli/base.d.ts

@@ -18,6 +18,7 @@ export declare class BaseCLI {
     execute(): void;
     protected setupStageCommand(): void;
     protected setupTranslateCommand(): void;
+    protected setupSendDiffsCommand(): void;
     protected handleStage(initOptions: TranslateFlags): Promise<void>;
     protected handleTranslate(initOptions: TranslateFlags): Promise<void>;
     protected setupUploadCommand(): void;

package/dist/cli/base.js

@@ -20,6 +20,7 @@ import { handleDownload, handleTranslate, postProcessTranslations, } from './com
 import { getDownloaded, clearDownloaded } from '../state/recentDownloads.js';
 import updateConfig from '../fs/config/updateConfig.js';
 import { createLoadTranslationsFile } from '../fs/createLoadTranslationsFile.js';
+import { saveLocalEdits } from '../api/saveLocalEdits.js';
 export class BaseCLI {
     library;
     additionalModules;
@@ -34,6 +35,7 @@ export class BaseCLI {
         this.setupSetupCommand();
         this.setupUploadCommand();
         this.setupLoginCommand();
+        this.setupSendDiffsCommand();
     }
     // Init is never called in a child class
     init() {
@@ -64,6 +66,17 @@ export class BaseCLI {
             endCommand('Done!');
         });
     }
+    setupSendDiffsCommand() {
+        this.program
+            .command('save-local')
+            .description('Save local edits for all configured files by sending diffs (no translation enqueued)')
+            .action(async () => {
+            const config = findFilepath(['gt.config.json']);
+            const settings = await generateSettings({ config });
+            await saveLocalEdits(settings);
+            endCommand('Saved local edits');
+        });
+    }
     async handleStage(initOptions) {
         const settings = await generateSettings(initOptions);
         if (!settings.stageTranslations) {

package/dist/cli/commands/edits.d.ts

@@ -0,0 +1,8 @@
+import { Settings } from '../../types/index.js';
+export type SendDiffsFlags = {
+    fileName: string;
+    locale: string;
+    old: string;
+    next: string;
+};
+export declare function handleSendDiffs(flags: SendDiffsFlags, settings: Settings): Promise<void>;

package/dist/cli/commands/edits.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import { getGitUnifiedDiff } from '../../utils/gitDiff.js';
+import { sendUserEditDiffs } from '../../api/sendUserEdits.js';
+import { logErrorAndExit, logMessage } from '../../console/logging.js';
+export async function handleSendDiffs(flags, settings) {
+    const { fileName, locale, old, next } = flags;
+    if (!fs.existsSync(old)) {
+        logErrorAndExit(`Old/original file not found: ${old}`);
+    }
+    if (!fs.existsSync(next)) {
+        logErrorAndExit(`New/local file not found: ${next}`);
+    }
+    let diff;
+    try {
+        diff = await getGitUnifiedDiff(old, next);
+    }
+    catch (e) {
+        logErrorAndExit('Git is required to compute diffs. Please install Git and ensure it is available on your PATH.');
+        return; // unreachable
+    }
+    if (!diff || diff.trim().length === 0) {
+        logMessage('No differences detected — nothing to send.');
+        return;
+    }
+    await sendUserEditDiffs([
+        {
+            fileName,
+            locale,
+            diff,
+        },
+    ], settings);
+}

package/dist/utils/addExplicitAnchorIds.js

@@ -36,7 +36,7 @@ function extractHeadingText(heading) {
 function hasExplicitId(heading, ast) {
     const lastChild = heading.children[heading.children.length - 1];
     if (lastChild?.type === 'text') {
-        return /(\{#[^}]+\}|\[[^\]]+\])$/.test(lastChild.value);
+        return /(\{#[^}]+\}|\\\{#[^}]+\\\}|\[[^\]]+\])\s*$/.test(lastChild.value);
     }
     return false;
 }
@@ -124,7 +124,7 @@ export function addExplicitAnchorIds(translatedContent, sourceHeadingMap, settin
     }
     return {
         content,
-        hasChanges: addedIds.length > 0,
+        hasChanges: content !== translatedContent,
         addedIds,
     };
 }
@@ -148,6 +148,7 @@ function applyInlineIds(translatedContent, idMappings) {
     }
     // Apply IDs to headings based on position
     let headingIndex = 0;
+    let actuallyModifiedContent = false;
     visit(processedAst, 'heading', (heading) => {
         const id = idMappings.get(headingIndex);
         if (id) {
@@ -168,9 +169,14 @@ function applyInlineIds(translatedContent, idMappings) {
                     value: ` \\{#${id}\\}`,
                 });
             }
+            actuallyModifiedContent = true;
         }
         headingIndex++;
     });
+    // If we didn't modify any headings, return original content
+    if (!actuallyModifiedContent) {
+        return translatedContent;
+    }
     // Convert the modified AST back to MDX string
     try {
         const stringifyProcessor = unified()
@@ -248,6 +254,10 @@ function applyDivWrappedIds(translatedContent, translatedHeadings, idMappings) {
         // 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) {
+            // If already wrapped with this id, skip (idempotent)
+            if (content.includes(`<div id="${heading.id}">`)) {
+                continue;
+            }
             // Escape the original line for use in regex
             const escapedLine = heading.originalLine.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
             const headingPattern = new RegExp(`^${escapedLine}\\s*$`, 'gm');

package/dist/utils/gitDiff.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a unified diff using the system's git, comparing two paths even if not in a repo.
+ * Uses `git diff --no-index` so neither path needs to be tracked by git.
+ *
+ * Exit codes: 0 (no changes), 1 (changes), >1 (error). We treat 0/1 as success.
+ * Throws if git is unavailable or another error occurs.
+ */
+export declare function getGitUnifiedDiff(oldPath: string, newPath: string): Promise<string>;

package/dist/utils/gitDiff.js

@@ -0,0 +1,32 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Returns a unified diff using the system's git, comparing two paths even if not in a repo.
+ * Uses `git diff --no-index` so neither path needs to be tracked by git.
+ *
+ * Exit codes: 0 (no changes), 1 (changes), >1 (error). We treat 0/1 as success.
+ * Throws if git is unavailable or another error occurs.
+ */
+export async function getGitUnifiedDiff(oldPath, newPath) {
+    const res = await execFileAsync('git', [
+        'diff',
+        '--no-index',
+        '--text',
+        '--unified=3',
+        '--no-color',
+        '--',
+        oldPath,
+        newPath,
+    ], {
+        windowsHide: true,
+    }).catch((error) => {
+        // Exit code 1 means differences found; stdout contains the diff
+        if (error && error.code === 1 && typeof error.stdout === 'string') {
+            return { stdout: error.stdout };
+        }
+        throw error;
+    });
+    // When there are no changes, stdout is empty string and exit code 0
+    return res.stdout || '';
+}

package/dist/utils/localizeStaticImports.js

@@ -163,6 +163,12 @@ function transformNonDefaultLocaleImportPathWithHidden(fullPath, patternHead, ta
  * Transforms import path for non-default locale processing with hideDefaultLocale=false
  */
 function transformNonDefaultLocaleImportPath(fullPath, patternHead, targetLocale, defaultLocale) {
+    // If already localized to target, skip
+    const expectedPathWithTarget = `${patternHead}${targetLocale}`;
+    if (fullPath.startsWith(`${expectedPathWithTarget}/`) ||
+        fullPath === expectedPathWithTarget) {
+        return null;
+    }
     const expectedPathWithLocale = `${patternHead}${defaultLocale}`;
     if (fullPath.startsWith(`${expectedPathWithLocale}/`) ||
         fullPath === expectedPathWithLocale) {

package/dist/utils/localizeStaticUrls.js

@@ -175,6 +175,10 @@ export function transformUrlPath(originalUrl, patternHead, targetLocale, default
         }
     }
     else if (hideDefaultLocale) {
+        // Avoid duplicating target locale if already present
+        if (originalPathArray?.[patternHeadArray.length] === targetLocale) {
+            return null;
+        }
         const newPathArray = [
             ...originalPathArray.slice(0, patternHeadArray.length),
             targetLocale,
@@ -256,6 +260,18 @@ function transformMdxUrls(mdxContent, defaultLocale, targetLocale, hideDefaultLo
     }
     // Helper function to transform URL based on pattern
     const transformUrl = (originalUrl, linkType) => {
+        // For Markdown links [text](path), only process absolute-root paths starting with '/'
+        // Relative markdown links should remain relative to the current page and not be localized.
+        if (linkType === 'markdown') {
+            const isFragment = /^\s*#/.test(originalUrl);
+            const isAbsoluteRoot = originalUrl.startsWith('/');
+            const looksAbsoluteWithDomain = baseDomain
+                ? shouldProcessAbsoluteUrl(originalUrl, baseDomain)
+                : false;
+            if (!isAbsoluteRoot && !looksAbsoluteWithDomain && !isFragment) {
+                return null;
+            }
+        }
         // Check if URL should be processed
         if (!shouldProcessUrl(originalUrl, patternHead, targetLocale, defaultLocale, baseDomain)) {
             return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gtx-cli",
-  "version": "2.3.14",
+  "version": "2.4.0",
   "main": "dist/index.js",
   "bin": "dist/main.js",
   "files": [
@@ -91,7 +91,7 @@
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "yaml": "^2.8.0",
-    "generaltranslation": "7.6.5"
+    "generaltranslation": "7.7.0"
   },
   "devDependencies": {
     "@babel/types": "^7.28.4",