gtx-cli 2.5.15 → 2.5.17

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # gtx-cli
 
+## 2.5.17
+
+### Patch Changes
+
+- [#848](https://github.com/generaltranslation/gt/pull/848) [`db4ab5c`](https://github.com/generaltranslation/gt/commit/db4ab5cad2726d78dc7c4e4dd7f3a83adaa1fcfb) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Adding OpenAPI handling via `gt.config.json`
+
+## 2.5.16
+
+### Patch Changes
+
+- [#843](https://github.com/generaltranslation/gt/pull/843) [`b135cbe`](https://github.com/generaltranslation/gt/commit/b135cbed44b259619697d9a429ba61c434bed7b5) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Job polling correctly resolves locale aliases
+
 ## 2.5.15
 
 ### Patch Changes

package/dist/cli/commands/translate.js

@@ -5,6 +5,7 @@ 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 processOpenApi from '../../utils/processOpenApi.js';
 import { noFilesError, noVersionIdError } from '../../console/index.js';
 import localizeStaticImports from '../../utils/localizeStaticImports.js';
 import { logErrorAndExit } from '../../console/logging.js';
@@ -35,6 +36,8 @@ export async function handleDownload(options, settings) {
     options.force || options.forceDownload);
 }
 export async function postProcessTranslations(settings, includeFiles) {
+    // Mintlify OpenAPI localization (spec routing + validation)
+    await processOpenApi(settings, includeFiles);
     // 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) {

package/dist/config/generateSettings.js

@@ -132,6 +132,23 @@ export async function generateSettings(flags, cwd = process.cwd()) {
     };
     // Add additional options if provided
     if (mergedOptions.options) {
+        // Auto-add jsonSchema include paths for configured OpenAPI specs (Mintlify)
+        if (mergedOptions.openapi?.framework === 'mintlify' &&
+            Array.isArray(mergedOptions.openapi.files) &&
+            mergedOptions.openapi.files.length) {
+            const translateFields = mergedOptions.openapi.translateFields?.length &&
+                mergedOptions.openapi.translateFields.length > 0
+                ? mergedOptions.openapi.translateFields
+                : ['$..summary', '$..description'];
+            mergedOptions.options.jsonSchema = mergedOptions.options.jsonSchema || {};
+            for (const specFile of mergedOptions.openapi.files) {
+                if (!mergedOptions.options.jsonSchema[specFile]) {
+                    mergedOptions.options.jsonSchema[specFile] = {
+                        include: translateFields,
+                    };
+                }
+            }
+        }
         if (mergedOptions.options.jsonSchema) {
             for (const fileGlob of Object.keys(mergedOptions.options.jsonSchema)) {
                 const jsonSchema = mergedOptions.options.jsonSchema[fileGlob];

package/dist/types/index.d.ts

@@ -30,6 +30,11 @@ export type Options = {
         replace: string;
     }>;
 };
+export type OpenApiConfig = {
+    framework: 'mintlify';
+    files: string[];
+    translateFields?: string[];
+};
 export type TranslateFlags = {
     config?: string;
     apiKey?: string;
@@ -144,6 +149,7 @@ export type Settings = {
     parsingOptions: ParsingConfigOptions;
     branchOptions: BranchOptions;
     sharedStaticAssets?: SharedStaticAssetsConfig;
+    openapi?: OpenApiConfig;
 };
 export type BranchOptions = {
     currentBranch?: string;

package/dist/utils/processOpenApi.d.ts

@@ -0,0 +1,8 @@
+import { Settings } from '../types/index.js';
+/**
+ * Postprocess Mintlify OpenAPI references to point to locale-specific spec files.
+ * - Uses openapi.files (ordered) to resolve ambiguities (first match wins).
+ * - Relies on the user's json transform rules for locale paths.
+ * - Warns on missing/ambiguous references but keeps behavior deterministic.
+ */
+export default function processOpenApi(settings: Settings, includeFiles?: Set<string>): Promise<void>;

package/dist/utils/processOpenApi.js

@@ -0,0 +1,387 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkFrontmatter from 'remark-frontmatter';
+import YAML from 'yaml';
+import { logger } from '../console/logger.js';
+import { createFileMapping } from '../formats/files/fileMapping.js';
+const HTTP_METHODS = new Set([
+    'GET',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'OPTIONS',
+    'HEAD',
+    'TRACE',
+]);
+/**
+ * Postprocess Mintlify OpenAPI references to point to locale-specific spec files.
+ * - Uses openapi.files (ordered) to resolve ambiguities (first match wins).
+ * - Relies on the user's json transform rules for locale paths.
+ * - Warns on missing/ambiguous references but keeps behavior deterministic.
+ */
+export default async function processOpenApi(settings, includeFiles) {
+    if (settings.openapi?.framework !== 'mintlify')
+        return;
+    if (!settings.openapi.files?.length)
+        return;
+    if (!settings.files)
+        return;
+    const configDir = path.dirname(settings.config);
+    const specAnalyses = buildSpecAnalyses(settings.openapi.files, configDir);
+    if (!specAnalyses.length)
+        return;
+    const warnings = new Set();
+    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+    const fileMappingAbs = {};
+    for (const [locale, mapping] of Object.entries(fileMapping)) {
+        fileMappingAbs[locale] = {};
+        for (const [src, dest] of Object.entries(mapping)) {
+            const absSrc = path.resolve(configDir, src);
+            const absDest = path.resolve(configDir, dest);
+            fileMappingAbs[locale][absSrc] = absDest;
+        }
+    }
+    // Also rewrite default-locale source files so they use the deterministic spec selection
+    const defaultFiles = [
+        ...(resolvedPaths.mdx || []),
+        ...(resolvedPaths.md || []),
+    ];
+    for (const filePath of defaultFiles) {
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, 'utf8');
+        const updated = rewriteFrontmatter(content, filePath, settings.defaultLocale, specAnalyses, fileMappingAbs, warnings, configDir);
+        if (updated?.changed) {
+            await fs.promises.writeFile(filePath, updated.content, 'utf8');
+        }
+    }
+    for (const [locale, filesMap] of Object.entries(fileMapping)) {
+        const targetFiles = Object.values(filesMap).filter((p) => (p.endsWith('.md') || p.endsWith('.mdx')) &&
+            (!includeFiles || includeFiles.has(p)));
+        for (const filePath of targetFiles) {
+            if (!fs.existsSync(filePath))
+                continue;
+            const content = fs.readFileSync(filePath, 'utf8');
+            const updated = rewriteFrontmatter(content, filePath, locale, specAnalyses, fileMappingAbs, warnings, configDir);
+            if (updated?.changed) {
+                await fs.promises.writeFile(filePath, updated.content, 'utf8');
+            }
+        }
+    }
+    for (const message of warnings) {
+        logger.warn(message);
+    }
+}
+/**
+ * Resolve configured OpenAPI files to absolute paths and collect the operations,
+ * schemas, and webhooks they expose. Warns and skips when files are missing,
+ * unsupported (non-JSON), or fail to parse so later steps can continue gracefully.
+ */
+function buildSpecAnalyses(openapiFiles, configDir) {
+    const analyses = [];
+    for (const configEntry of openapiFiles) {
+        const absPath = path.resolve(configDir, configEntry);
+        if (!fs.existsSync(absPath)) {
+            logger.warn(`OpenAPI file not found: ${configEntry}`);
+            continue;
+        }
+        if (path.extname(absPath).toLowerCase() !== '.json') {
+            logger.warn(`Skipping OpenAPI file (only .json supported): ${configEntry}`);
+            continue;
+        }
+        let spec;
+        try {
+            const raw = fs.readFileSync(absPath, 'utf8');
+            spec = JSON.parse(raw);
+        }
+        catch {
+            logger.warn(`Failed to parse OpenAPI JSON: ${configEntry}`);
+            continue;
+        }
+        analyses.push({
+            absPath,
+            configPath: configEntry,
+            operations: extractOperations(spec),
+            schemas: extractSchemas(spec),
+            webhooks: extractWebhooks(spec),
+        });
+    }
+    return analyses;
+}
+function isRecord(val) {
+    return typeof val === 'object' && val !== null;
+}
+/**
+ * Collect path+method identifiers (e.g., "POST /foo") from an OpenAPI spec.
+ * Safely no-ops when paths is missing or malformed.
+ */
+function extractOperations(spec) {
+    const ops = new Set();
+    if (!isRecord(spec) || !isRecord(spec.paths))
+        return ops;
+    const paths = spec.paths;
+    for (const [route, methods] of Object.entries(paths)) {
+        if (!isRecord(methods))
+            continue;
+        for (const [method, operation] of Object.entries(methods)) {
+            if (!isRecord(operation))
+                continue;
+            const upper = method.toUpperCase();
+            if (!HTTP_METHODS.has(upper))
+                continue;
+            ops.add(`${upper} ${route}`);
+        }
+    }
+    return ops;
+}
+/**
+ * Collect schema names from components.schemas.
+ * Returns empty set if components/schemas are missing or malformed.
+ */
+function extractSchemas(spec) {
+    if (!isRecord(spec) || !isRecord(spec.components))
+        return new Set();
+    const components = spec.components;
+    if (!isRecord(components.schemas))
+        return new Set();
+    return new Set(Object.keys(components.schemas));
+}
+/**
+ * Collect webhook names from webhooks (OpenAPI 3.1+).
+ * Returns empty set if webhooks is missing or malformed.
+ */
+function extractWebhooks(spec) {
+    if (!isRecord(spec) || !isRecord(spec.webhooks))
+        return new Set();
+    return new Set(Object.keys(spec.webhooks));
+}
+/**
+ * Parse MDX/MD frontmatter, rewrite openapi/openapi-schema entries to the
+ * resolved (possibly localized) spec path, and return updated content.
+ * Uses remark to find the YAML node so the rest of the document remains
+ * untouched. When parsing fails or no relevant keys exist, it returns null.
+ */
+function rewriteFrontmatter(content, filePath, locale, specs, fileMapping, warnings, configDir) {
+    let tree;
+    try {
+        tree = unified()
+            .use(remarkParse)
+            .use(remarkFrontmatter, ['yaml', 'toml'])
+            .parse(content);
+    }
+    catch {
+        return null;
+    }
+    const yamlNode = tree.children.find((node) => node.type === 'yaml');
+    if (!yamlNode ||
+        !yamlNode.position ||
+        yamlNode.position.start?.offset === undefined) {
+        return null;
+    }
+    const start = yamlNode.position.start.offset;
+    const end = yamlNode.position.end.offset;
+    const frontmatterRaw = yamlNode.value || '';
+    let parsed;
+    try {
+        parsed = YAML.parse(frontmatterRaw, { prettyErrors: false }) || {};
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    let changed = false;
+    if (typeof parsed.openapi === 'string') {
+        const parsedValue = parseOpenApiValue(parsed.openapi);
+        if (parsedValue) {
+            const matchKey = parsedValue.kind === 'operation'
+                ? {
+                    type: 'operation',
+                    key: `${parsedValue.method.toUpperCase()} ${parsedValue.operationPath}`,
+                }
+                : { type: 'webhook', key: parsedValue.name };
+            const spec = resolveSpec(parsedValue.specPath, specs, filePath, configDir, warnings, describeOpenApiRef(parsedValue), matchKey);
+            if (spec) {
+                const descriptor = formatOpenApiDescriptor(parsedValue);
+                const localizedSpecPath = resolveLocalizedSpecPath(spec, locale, fileMapping, configDir, parsedValue.specPath || spec.configPath);
+                const newValue = `${localizedSpecPath} ${descriptor}`.trim();
+                if (newValue !== parsed.openapi) {
+                    parsed.openapi = newValue;
+                    changed = true;
+                }
+            }
+        }
+    }
+    if (typeof parsed['openapi-schema'] === 'string') {
+        const parsedValue = parseSchemaValue(parsed['openapi-schema']);
+        if (parsedValue) {
+            const spec = resolveSpec(parsedValue.specPath, specs, filePath, configDir, warnings, `schema "${parsedValue.schemaName}"`, { type: 'schema', key: parsedValue.schemaName });
+            if (spec) {
+                const localizedSpecPath = resolveLocalizedSpecPath(spec, locale, fileMapping, configDir, parsedValue.specPath || spec.configPath);
+                const newValue = `${localizedSpecPath} ${parsedValue.schemaName}`.trim();
+                if (newValue !== parsed['openapi-schema']) {
+                    parsed['openapi-schema'] = newValue;
+                    changed = true;
+                }
+            }
+        }
+    }
+    if (!changed)
+        return null;
+    const fmString = YAML.stringify(parsed).trimEnd();
+    const rebuilt = `${content.slice(0, start)}---\n${fmString}\n---${content.slice(end)}`;
+    return { changed, content: rebuilt };
+}
+function stripWrappingQuotes(value) {
+    return value.trim().replace(/^['"]|['"]$/g, '');
+}
+/**
+ * Parse frontmatter openapi string into spec/method/path or webhook.
+ * Supports optional leading spec file, the webhook keyword, quoted values,
+ * and forgiving whitespace. Returns null when the structure is unrecognized.
+ */
+function parseOpenApiValue(value) {
+    const stripped = stripWrappingQuotes(value);
+    const tokens = stripped.split(/\s+/).filter(Boolean);
+    if (!tokens.length)
+        return null;
+    let cursor = 0;
+    let specPath;
+    if (tokens[0].toLowerCase().endsWith('.json')) {
+        specPath = tokens[0];
+        cursor = 1;
+    }
+    if (cursor >= tokens.length)
+        return null;
+    const keyword = tokens[cursor];
+    if (keyword.toLowerCase() === 'webhook') {
+        const name = tokens.slice(cursor + 1).join(' ');
+        return { kind: 'webhook', specPath, name };
+    }
+    const method = keyword.toUpperCase();
+    const operationPath = tokens.slice(cursor + 1).join(' ');
+    if (!operationPath)
+        return null;
+    return { kind: 'operation', specPath, method, operationPath };
+}
+/**
+ * Parse frontmatter openapi-schema string into spec/schemaName.
+ * Accepts optional leading spec file and quoted values; returns null on invalid
+ * shapes so callers can skip rewrites gracefully.
+ */
+function parseSchemaValue(value) {
+    const stripped = stripWrappingQuotes(value);
+    const tokens = stripped.split(/\s+/).filter(Boolean);
+    if (!tokens.length)
+        return null;
+    let cursor = 0;
+    let specPath;
+    if (tokens[0].toLowerCase().endsWith('.json')) {
+        specPath = tokens[0];
+        cursor = 1;
+    }
+    const schemaName = tokens.slice(cursor).join(' ');
+    if (!schemaName)
+        return null;
+    return { specPath, schemaName };
+}
+/**
+ * Choose which configured spec a reference should use.
+ * - If an explicit spec path is provided, resolve it relative to the config
+ *   and the referencing file, warn when unknown, and bail.
+ * - Otherwise, try to match by operation/webhook/schema name; resolve
+ *   ambiguity using config order and warn when ambiguous or missing.
+ */
+function resolveSpec(explicitPath, specs, filePath, configDir, warnings, refDescription, match) {
+    if (!specs.length)
+        return null;
+    if (explicitPath) {
+        const normalizedExplicit = explicitPath.replace(/^\.?\/+/, '');
+        const candidates = [
+            path.resolve(configDir, normalizedExplicit),
+            path.resolve(path.dirname(filePath), normalizedExplicit),
+        ];
+        const foundSpec = specs.find((spec) => candidates.some((candidate) => samePath(candidate, spec.absPath)));
+        if (foundSpec)
+            return foundSpec;
+        warnings.add(`OpenAPI reference ${refDescription} in ${filePath} points to an unconfigured spec (${explicitPath}). Skipping localization for this reference.`);
+        return null;
+    }
+    // No explicit spec: try to find by contents
+    const matches = specs.filter((spec) => {
+        if (match.type === 'schema') {
+            return spec.schemas.has(match.key);
+        }
+        if (match.type === 'webhook') {
+            return spec.webhooks.has(match.key);
+        }
+        // operation
+        return spec.operations.has(match.key);
+    });
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        warnings.add(`OpenAPI reference ${refDescription} in ${filePath} is available in multiple specs. Using the first configured file (${matches[0].configPath}).`);
+        return matches[0];
+    }
+    // Not found anywhere, fall back to first configured spec
+    warnings.add(`OpenAPI reference ${refDescription} in ${filePath} was not found in any configured spec. Using ${specs[0].configPath}.`);
+    return specs[0];
+}
+/**
+ * Map a spec to the locale-specific file path when available and normalize it
+ * for frontmatter. Falls back to the source spec when the locale copy does
+ * not exist to preserve deterministic behavior.
+ */
+function resolveLocalizedSpecPath(spec, locale, fileMapping, configDir, originalPathText) {
+    const mapping = fileMapping[locale]?.[spec.absPath];
+    const chosenAbs = mapping || spec.absPath;
+    const rel = normalizeSlashes(path.relative(configDir, chosenAbs));
+    const rooted = `/${rel.replace(/^\/+/, '')}`;
+    return formatSpecPathForFrontmatter(rooted, originalPathText || spec.configPath);
+}
+/**
+ * Format the path that will be written back to frontmatter:
+ * - Preserve the user's absolute style when they used a leading slash.
+ * - Preserve upward relative references (../) exactly.
+ * - Otherwise return a repo-root-relative path with a leading slash so Mintlify
+ *   resolves consistently regardless of the MDX file location.
+ */
+function formatSpecPathForFrontmatter(relativePath, originalPathText) {
+    const normalized = normalizeSlashes(relativePath);
+    const base = normalized.replace(/^\.\//, '').replace(/\/+/g, '/');
+    if (originalPathText.startsWith('/')) {
+        // Force repo-root absolute style
+        return `/${base.replace(/^\/+/, '')}`;
+    }
+    if (originalPathText.startsWith('../')) {
+        // Preserve explicit relative upward references
+        return normalized;
+    }
+    // Default to repo-root relative with leading slash to avoid resolving relative to the MDX directory
+    return `/${base.replace(/^\/+/, '')}`;
+}
+/** Normalize the descriptive portion after the spec path for frontmatter. */
+function formatOpenApiDescriptor(value) {
+    if (value.kind === 'webhook')
+        return `webhook ${value.name}`;
+    return `${value.method.toUpperCase()} ${value.operationPath}`;
+}
+/** Human-readable description a specific OpenAPI reference. */
+function describeOpenApiRef(value) {
+    if (value.kind === 'webhook')
+        return `webhook ${value.name}`;
+    return `${value.method.toUpperCase()} ${value.operationPath}`;
+}
+/** Normalize separators for stable comparisons and output. */
+function normalizeSlashes(p) {
+    return p.replace(/\\/g, '/');
+}
+/** Compare paths after resolution to avoid casing/separator mismatches. */
+function samePath(a, b) {
+    return path.resolve(a) === path.resolve(b);
+}

package/dist/workflow/PollJobsStep.js

@@ -47,18 +47,20 @@ export class PollTranslationJobsStep extends WorkflowStep {
         // branchId:fileId:versionId:locale -> job
         const jobMap = new Map();
         Object.entries(jobData.jobData).forEach(([jobId, job]) => {
-            const key = `${job.branchId}:${job.fileId}:${job.versionId}:${job.targetLocale}`;
-            jobMap.set(key, { ...job, jobId });
+            const jobLocale = this.gt.resolveAliasLocale(job.targetLocale);
+            const key = `${job.branchId}:${job.fileId}:${job.versionId}:${jobLocale}`;
+            jobMap.set(key, { ...job, jobId, targetLocale: jobLocale });
         });
         // Build a map of jobs for quick lookup:
         // jobId -> file data for the job
         const jobFileMap = new Map();
         Object.entries(jobData.jobData).forEach(([jobId, job]) => {
+            const jobLocale = this.gt.resolveAliasLocale(job.targetLocale);
             jobFileMap.set(jobId, {
                 branchId: job.branchId,
                 fileId: job.fileId,
                 versionId: job.versionId,
-                locale: job.targetLocale,
+                locale: jobLocale,
             });
         });
         // Categorize each file query item

package/package.json

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