gtx-cli 2.0.7 → 2.0.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # gtx-cli
 
+## 2.0.8
+
+### Patch Changes
+
+- [#495](https://github.com/generaltranslation/gt/pull/495) [`a7eca74`](https://github.com/generaltranslation/gt/commit/a7eca74677356b392c7c1a431f664c8e28adbf0c) Thanks [@brian-lou](https://github.com/brian-lou)! - Add support for translating arbitrary JSON files (all strings). Add support for partially translating JSON files via jsonSchema config setting. Add support for composite JSON files (where there is a single JSON containing data for all translated languages). Add support for preset jsonSchemas.
+
+- Updated dependencies [[`a7eca74`](https://github.com/generaltranslation/gt/commit/a7eca74677356b392c7c1a431f664c8e28adbf0c)]:
+  - generaltranslation@7.1.4
+
 ## 2.0.7
 
 ### Patch Changes

package/dist/api/checkFileTranslations.d.ts

@@ -1,3 +1,4 @@
+import { Settings } from '../types/index.js';
 export type CheckFileTranslationData = {
     [key: string]: {
         versionId: string;
@@ -14,7 +15,7 @@ export type CheckFileTranslationData = {
  * @param timeoutDuration - The timeout duration for the wait in seconds
  * @returns True if all translations are deployed, false otherwise
  */
-export declare function checkFileTranslations(projectId: string, apiKey: string, baseUrl: string, data: {
+export declare function checkFileTranslations(data: {
     [key: string]: {
         versionId: string;
         fileName: string;
@@ -22,4 +23,4 @@ export declare function checkFileTranslations(projectId: string, apiKey: string,
 }, locales: string[], timeoutDuration: number, resolveOutputPath: (sourcePath: string, locale: string) => string, downloadStatus: {
     downloaded: Set<string>;
     failed: Set<string>;
-}): Promise<boolean>;
+}, options: Settings): Promise<boolean>;

package/dist/api/checkFileTranslations.js

@@ -14,7 +14,7 @@ import { gt } from '../utils/gt.js';
  * @param timeoutDuration - The timeout duration for the wait in seconds
  * @returns True if all translations are deployed, false otherwise
  */
-export async function checkFileTranslations(projectId, apiKey, baseUrl, data, locales, timeoutDuration, resolveOutputPath, downloadStatus) {
+export async function checkFileTranslations(data, locales, timeoutDuration, resolveOutputPath, downloadStatus, options) {
     const startTime = Date.now();
     console.log();
     const spinner = await createOraSpinner();
@@ -22,7 +22,7 @@ export async function checkFileTranslations(projectId, apiKey, baseUrl, data, lo
     // Initialize the query data
     const fileQueryData = prepareFileQueryData(data, locales);
     // Do first check immediately
-    const initialCheck = await checkTranslationDeployment(baseUrl, projectId, apiKey, fileQueryData, downloadStatus, spinner, resolveOutputPath);
+    const initialCheck = await checkTranslationDeployment(fileQueryData, downloadStatus, spinner, resolveOutputPath, options);
     if (initialCheck) {
         spinner.succeed(chalk.green('Files translated!'));
         return true;
@@ -34,7 +34,7 @@ export async function checkFileTranslations(projectId, apiKey, baseUrl, data, lo
         // Start the interval aligned with the original request time
         setTimeout(() => {
             intervalCheck = setInterval(async () => {
-                const isDeployed = await checkTranslationDeployment(baseUrl, projectId, apiKey, fileQueryData, downloadStatus, spinner, resolveOutputPath);
+                const isDeployed = await checkTranslationDeployment(fileQueryData, downloadStatus, spinner, resolveOutputPath, options);
                 const elapsed = Date.now() - startTime;
                 if (isDeployed || elapsed >= timeoutDuration * 1000) {
                     clearInterval(intervalCheck);
@@ -157,7 +157,7 @@ function generateStatusSuffixText(downloadStatus, fileQueryData) {
 /**
  * Checks translation status and downloads ready files
  */
-async function checkTranslationDeployment(baseUrl, projectId, apiKey, fileQueryData, downloadStatus, spinner, resolveOutputPath) {
+async function checkTranslationDeployment(fileQueryData, downloadStatus, spinner, resolveOutputPath, options) {
     try {
         // Only query for files that haven't been downloaded yet
         const currentQueryData = fileQueryData.filter((item) => !downloadStatus.downloaded.has(`${item.fileName}:${item.locale}`) &&
@@ -181,15 +181,17 @@ async function checkTranslationDeployment(baseUrl, projectId, apiKey, fileQueryD
                 return {
                     translationId,
                     outputPath,
+                    locale,
                     fileLocale: `${fileName}:${locale}`,
                 };
             });
             // Use batch download if there are multiple files
             if (batchFiles.length > 1) {
-                const batchResult = await downloadFileBatch(batchFiles.map(({ translationId, outputPath }) => ({
+                const batchResult = await downloadFileBatch(batchFiles.map(({ translationId, outputPath, locale }) => ({
                     translationId,
                     outputPath,
-                })));
+                    locale,
+                })), options);
                 // Process results
                 batchFiles.forEach((file) => {
                     const { translationId, fileLocale } = file;
@@ -204,7 +206,7 @@ async function checkTranslationDeployment(baseUrl, projectId, apiKey, fileQueryD
             else if (batchFiles.length === 1) {
                 // For a single file, use the original downloadFile method
                 const file = batchFiles[0];
-                const result = await downloadFile(file.translationId, file.outputPath);
+                const result = await downloadFile(file.translationId, file.outputPath, file.locale, options);
                 if (result) {
                     downloadStatus.downloaded.add(file.fileLocale);
                 }

package/dist/api/downloadFile.d.ts

@@ -1,3 +1,4 @@
+import { Settings } from '../types/index.js';
 /**
  * Downloads a file from the API and saves it to a local directory
  * @param translationId - The ID of the translation to download
@@ -5,4 +6,4 @@
  * @param maxRetries - The maximum number of retries to attempt
  * @param retryDelay - The delay between retries in milliseconds
  */
-export declare function downloadFile(translationId: string, outputPath: string, maxRetries?: number, retryDelay?: number): Promise<boolean>;
+export declare function downloadFile(translationId: string, outputPath: string, locale: string, options: Settings, maxRetries?: number, retryDelay?: number): Promise<boolean>;

package/dist/api/downloadFile.js

@@ -2,6 +2,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { logError } from '../console/logging.js';
 import { gt } from '../utils/gt.js';
+import { validateJsonSchema } from '../formats/json/utils.js';
+import { mergeJson } from '../formats/json/mergeJson.js';
+import { TextDecoder } from 'node:util';
 /**
  * Downloads a file from the API and saves it to a local directory
  * @param translationId - The ID of the translation to download
@@ -9,7 +12,7 @@ import { gt } from '../utils/gt.js';
  * @param maxRetries - The maximum number of retries to attempt
  * @param retryDelay - The delay between retries in milliseconds
  */
-export async function downloadFile(translationId, outputPath, maxRetries = 3, retryDelay = 1000) {
+export async function downloadFile(translationId, outputPath, locale, options, maxRetries = 3, retryDelay = 1000) {
     let retries = 0;
     while (retries <= maxRetries) {
         try {
@@ -20,8 +23,23 @@ export async function downloadFile(translationId, outputPath, maxRetries = 3, re
             if (!fs.existsSync(dir)) {
                 fs.mkdirSync(dir, { recursive: true });
             }
+            let data = new TextDecoder().decode(fileData);
+            if (options.options?.jsonSchema && locale) {
+                const jsonSchema = validateJsonSchema(options.options, outputPath);
+                if (jsonSchema) {
+                    const originalContent = fs.readFileSync(outputPath, 'utf8');
+                    if (originalContent) {
+                        data = mergeJson(originalContent, outputPath, options.options, [
+                            {
+                                translatedContent: data,
+                                targetLocale: locale,
+                            },
+                        ], options.defaultLocale)[0];
+                    }
+                }
+            }
             // Write the file to disk
-            await fs.promises.writeFile(outputPath, Buffer.from(fileData));
+            await fs.promises.writeFile(outputPath, data);
             return true;
         }
         catch (error) {

package/dist/api/downloadFileBatch.d.ts

@@ -1,6 +1,8 @@
+import { Settings } from '../types/index.js';
 export type BatchedFiles = Array<{
     translationId: string;
     outputPath: string;
+    locale: string;
 }>;
 export type DownloadFileBatchResult = {
     successful: string[];
@@ -13,4 +15,4 @@ export type DownloadFileBatchResult = {
  * @param retryDelay - Delay between retries in milliseconds
  * @returns Object containing successful and failed file IDs
  */
-export declare function downloadFileBatch(files: BatchedFiles, maxRetries?: number, retryDelay?: number): Promise<DownloadFileBatchResult>;
+export declare function downloadFileBatch(files: BatchedFiles, options: Settings, maxRetries?: number, retryDelay?: number): Promise<DownloadFileBatchResult>;

package/dist/api/downloadFileBatch.js

@@ -2,6 +2,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { logError, logWarning } from '../console/logging.js';
 import { gt } from '../utils/gt.js';
+import { validateJsonSchema } from '../formats/json/utils.js';
+import { mergeJson } from '../formats/json/mergeJson.js';
 /**
  * Downloads multiple translation files in a single batch request
  * @param files - Array of files to download with their output paths
@@ -9,12 +11,13 @@ import { gt } from '../utils/gt.js';
  * @param retryDelay - Delay between retries in milliseconds
  * @returns Object containing successful and failed file IDs
  */
-export async function downloadFileBatch(files, maxRetries = 3, retryDelay = 1000) {
+export async function downloadFileBatch(files, options, maxRetries = 3, retryDelay = 1000) {
     let retries = 0;
     const fileIds = files.map((file) => file.translationId);
     const result = { successful: [], failed: [] };
     // Create a map of translationId to outputPath for easier lookup
     const outputPathMap = new Map(files.map((file) => [file.translationId, file.outputPath]));
+    const localeMap = new Map(files.map((file) => [file.translationId, file.locale]));
     while (retries <= maxRetries) {
         try {
             // Download the files
@@ -25,6 +28,7 @@ export async function downloadFileBatch(files, maxRetries = 3, retryDelay = 1000
                 try {
                     const translationId = file.id;
                     const outputPath = outputPathMap.get(translationId);
+                    const locale = localeMap.get(translationId);
                     if (!outputPath) {
                         logWarning(`No output path found for file: ${translationId}`);
                         result.failed.push(translationId);
@@ -35,8 +39,23 @@ export async function downloadFileBatch(files, maxRetries = 3, retryDelay = 1000
                     if (!fs.existsSync(dir)) {
                         fs.mkdirSync(dir, { recursive: true });
                     }
+                    let data = file.data;
+                    if (options.options?.jsonSchema && locale) {
+                        const jsonSchema = validateJsonSchema(options.options, outputPath);
+                        if (jsonSchema) {
+                            const originalContent = fs.readFileSync(outputPath, 'utf8');
+                            if (originalContent) {
+                                data = mergeJson(originalContent, outputPath, options.options, [
+                                    {
+                                        translatedContent: file.data,
+                                        targetLocale: locale,
+                                    },
+                                ], options.defaultLocale)[0];
+                            }
+                        }
+                    }
                     // Write the file to disk
-                    await fs.promises.writeFile(outputPath, file.data);
+                    await fs.promises.writeFile(outputPath, data);
                     result.successful.push(translationId);
                 }
                 catch (error) {
@@ -52,18 +71,6 @@ export async function downloadFileBatch(files, maxRetries = 3, retryDelay = 1000
                 }
             }
             return result;
-            // // If we get here, the response was not OK
-            // if (retries >= maxRetries) {
-            //   logError(
-            //     `Failed to download files in batch. Status: ${response.status} after ${maxRetries + 1} attempts.`
-            //   );
-            //   // Mark all files as failed
-            //   result.failed = [...fileIds];
-            //   return result;
-            // }
-            // // Increment retry counter and wait before next attempt
-            // retries++;
-            // await new Promise((resolve) => setTimeout(resolve, retryDelay));
         }
         catch (error) {
             // If we've retried too many times, log an error and return false

package/dist/config/generateSettings.js

@@ -11,6 +11,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import { resolveConfig } from './resolveConfig.js';
 import { gt } from '../utils/gt.js';
+import { generatePreset } from './optionPresets.js';
 export const DEFAULT_SRC_PATTERNS = [
     'src/**/*.{js,jsx,ts,tsx}',
     'app/**/*.{js,jsx,ts,tsx}',
@@ -91,6 +92,18 @@ export async function generateSettings(options, cwd = process.cwd()) {
     mergedOptions.files = mergedOptions.files
         ? resolveFiles(mergedOptions.files, mergedOptions.defaultLocale, cwd)
         : undefined;
+    // Add additional options if provided
+    if (mergedOptions.options && mergedOptions.options.jsonSchema) {
+        for (const fileGlob of Object.keys(mergedOptions.options.jsonSchema)) {
+            const jsonSchema = mergedOptions.options.jsonSchema[fileGlob];
+            if (jsonSchema.preset) {
+                mergedOptions.options.jsonSchema[fileGlob] = {
+                    ...generatePreset(jsonSchema.preset),
+                    ...jsonSchema,
+                };
+            }
+        }
+    }
     // if there's no existing config file, creates one
     // does not include the API key to avoid exposing it
     if (!fs.existsSync(mergedOptions.config)) {

package/dist/config/optionPresets.d.ts

@@ -0,0 +1,2 @@
+import { JsonSchema } from '../types/index.js';
+export declare function generatePreset(preset: string): JsonSchema;

package/dist/config/optionPresets.js

@@ -0,0 +1,29 @@
+export function generatePreset(preset) {
+    switch (preset) {
+        case 'mintlify':
+            // https://mintlify.com/docs/navigation
+            return {
+                composite: {
+                    '$.navigation.languages': {
+                        type: 'array',
+                        key: '$.language',
+                        include: [
+                            '$..group',
+                            '$..tab',
+                            '$..item',
+                            '$..anchor',
+                            '$..dropdown',
+                        ],
+                        transform: {
+                            '$..pages[*]': {
+                                match: '^{locale}/(.*)$',
+                                replace: '{locale}/$1',
+                            },
+                        },
+                    },
+                },
+            };
+        default:
+            return {};
+    }
+}

package/dist/config/validateSettings.d.ts

@@ -1,3 +1,3 @@
 import { Settings } from '../types/index.js';
 export declare function validateSettings(settings: Settings): void;
-export declare function validateConfigExists(): string | undefined;
+export declare function validateConfigExists(): string;

package/dist/console/logging.d.ts

@@ -4,7 +4,8 @@ export declare function logError(message: string): void;
 export declare function logSuccess(message: string): void;
 export declare function logStep(message: string): void;
 export declare function logMessage(message: string): void;
-export declare function logErrorAndExit(message: string): void;
+export declare function logErrorAndExit(message: string): never;
+export declare function exit(code: number): never;
 export declare function startCommand(message: string): void;
 export declare function endCommand(message: string): void;
 export declare function displayHeader(introString?: string): void;

package/dist/console/logging.js

@@ -22,7 +22,10 @@ export function logMessage(message) {
 }
 export function logErrorAndExit(message) {
     log.error(message);
-    process.exit(1);
+    exit(1);
+}
+export function exit(code) {
+    process.exit(code);
 }
 // Clack prompts
 export function startCommand(message) {

package/dist/formats/files/translate.js

@@ -4,13 +4,13 @@ import { noSupportedFormatError, noLocalesError, noDefaultLocaleError, noApiKeyE
 import { logErrorAndExit, createSpinner, logError, logSuccess, } from '../../console/logging.js';
 import { resolveLocaleFiles } from '../../fs/config/parseFilesConfig.js';
 import { getRelative, readFile } from '../../fs/findFilepath.js';
-import { flattenJsonDictionary } from '../../react/utils/flattenDictionary.js';
 import path from 'node:path';
 import chalk from 'chalk';
 import { downloadFile } from '../../api/downloadFile.js';
 import { downloadFileBatch } from '../../api/downloadFileBatch.js';
 import { SUPPORTED_FILE_EXTENSIONS } from './supportedFiles.js';
 import sanitizeFileContent from '../../utils/sanitizeFileContent.js';
+import { parseJson } from '../json/parseJson.js';
 const SUPPORTED_DATA_FORMATS = ['JSX', 'ICU', 'I18NEXT'];
 /**
  * Sends multiple files to the API for translation
@@ -24,6 +24,7 @@ const SUPPORTED_DATA_FORMATS = ['JSX', 'ICU', 'I18NEXT'];
 export async function translateFiles(filePaths, placeholderPaths, transformPaths, dataFormat = 'JSX', options) {
     // Collect all files to translate
     const allFiles = [];
+    const additionalOptions = options.options || {};
     // Process JSON files
     if (filePaths.json) {
         if (!SUPPORTED_DATA_FORMATS.includes(dataFormat)) {
@@ -31,12 +32,10 @@ export async function translateFiles(filePaths, placeholderPaths, transformPaths
         }
         const jsonFiles = filePaths.json.map((filePath) => {
             const content = readFile(filePath);
-            const json = JSON.parse(content);
-            // Just to validate the JSON is valid
-            flattenJsonDictionary(json);
+            const parsedJson = parseJson(content, filePath, additionalOptions, options.defaultLocale);
             const relativePath = getRelative(filePath);
             return {
-                content,
+                content: parsedJson,
                 fileName: relativePath,
                 fileFormat: 'JSON',
                 dataFormat,
@@ -100,8 +99,8 @@ export async function translateFiles(filePaths, placeholderPaths, transformPaths
         // Process any translations that were already completed and returned with the initial response
         const downloadStatus = await processInitialTranslations(translations, fileMapping, options);
         // Check for remaining translations
-        await checkFileTranslations(options.projectId, options.apiKey, options.baseUrl, data, locales, 600, (sourcePath, locale) => fileMapping[locale][sourcePath], downloadStatus // Pass the already downloaded files to avoid duplicate requests
-        );
+        await checkFileTranslations(data, locales, 600, (sourcePath, locale) => fileMapping[locale][sourcePath], downloadStatus, // Pass the already downloaded files to avoid duplicate requests
+        options);
     }
     catch (error) {
         logErrorAndExit(`Error translating files: ${error}`);
@@ -174,6 +173,7 @@ async function processInitialTranslations(translations = [], fileMapping, option
                 translationId: id,
                 outputPath,
                 fileLocale: `${fileName}:${locale}`,
+                locale,
             };
         })
             .filter(Boolean);
@@ -182,10 +182,11 @@ async function processInitialTranslations(translations = [], fileMapping, option
         }
         // Use batch download if there are multiple files
         if (batchFiles.length > 1) {
-            const batchResult = await downloadFileBatch(batchFiles.map(({ translationId, outputPath }) => ({
+            const batchResult = await downloadFileBatch(batchFiles.map(({ translationId, outputPath, locale }) => ({
                 translationId,
                 outputPath,
-            })));
+                locale,
+            })), options);
             // Process results
             batchFiles.forEach((file) => {
                 const { translationId, fileLocale } = file;
@@ -200,7 +201,7 @@ async function processInitialTranslations(translations = [], fileMapping, option
         else if (batchFiles.length === 1) {
             // For a single file, use the original downloadFile method
             const file = batchFiles[0];
-            const result = await downloadFile(file.translationId, file.outputPath);
+            const result = await downloadFile(file.translationId, file.outputPath, file.locale, options);
             if (result) {
                 downloadStatus.downloaded.add(file.fileLocale);
             }

package/dist/formats/json/flattenJson.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Flattens a JSON object according to a list of JSON paths.
+ * @param json - The JSON object to flatten
+ * @param jsonPaths - The list of JSON paths to flatten
+ * @returns A mapping of json pointers to their values
+ */
+export declare function flattenJson(json: any, jsonPaths: string[]): Record<string, any>;
+/**
+ * Flattens a JSON object according to a list of JSON paths, only including strings
+ * @param json - The JSON object to flatten
+ * @param jsonPaths - The list of JSON paths to flatten
+ * @returns A mapping of json pointers to their values
+ */
+export declare function flattenJsonWithStringFilter(json: any, jsonPaths: string[]): Record<string, any>;

package/dist/formats/json/flattenJson.js

@@ -0,0 +1,64 @@
+import { JSONPath } from 'jsonpath-plus';
+import { logError } from '../../console/logging.js';
+/**
+ * Flattens a JSON object according to a list of JSON paths.
+ * @param json - The JSON object to flatten
+ * @param jsonPaths - The list of JSON paths to flatten
+ * @returns A mapping of json pointers to their values
+ */
+export function flattenJson(json, jsonPaths) {
+    const extractedJson = {};
+    for (const jsonPath of jsonPaths) {
+        try {
+            const results = JSONPath({
+                json,
+                path: jsonPath,
+                resultType: 'all',
+                flatten: true,
+                wrap: true,
+            });
+            if (!results || results.length === 0) {
+                continue;
+            }
+            results.forEach((result) => {
+                extractedJson[result.pointer] = result.value;
+            });
+        }
+        catch (error) {
+            logError(`Error with JSONPath pattern: ${jsonPath}`);
+        }
+    }
+    return extractedJson;
+}
+/**
+ * Flattens a JSON object according to a list of JSON paths, only including strings
+ * @param json - The JSON object to flatten
+ * @param jsonPaths - The list of JSON paths to flatten
+ * @returns A mapping of json pointers to their values
+ */
+export function flattenJsonWithStringFilter(json, jsonPaths) {
+    const extractedJson = {};
+    for (const jsonPath of jsonPaths) {
+        try {
+            const results = JSONPath({
+                json,
+                path: jsonPath,
+                resultType: 'all',
+                flatten: true,
+                wrap: true,
+            });
+            if (!results || results.length === 0) {
+                continue;
+            }
+            results.forEach((result) => {
+                if (typeof result.value === 'string') {
+                    extractedJson[result.pointer] = result.value;
+                }
+            });
+        }
+        catch (error) {
+            logError(`Error with JSONPath pattern: ${jsonPath}`);
+        }
+    }
+    return extractedJson;
+}

package/dist/formats/json/mergeJson.d.ts

@@ -0,0 +1,6 @@
+import { AdditionalOptions, SourceObjectOptions } from '../../types/index.js';
+export declare function mergeJson(originalContent: string, filePath: string, options: AdditionalOptions, targets: {
+    translatedContent: string;
+    targetLocale: string;
+}[], defaultLocale: string): string[];
+export declare function applyTransformations(sourceItem: any, transform: SourceObjectOptions['transform'], targetLocale: string, defaultLocale: string): void;

package/dist/formats/json/mergeJson.js

@@ -0,0 +1,230 @@
+import JSONPointer from 'jsonpointer';
+import { exit, logError, logWarning } from '../../console/logging.js';
+import { findMatchingItemArray, findMatchingItemObject, generateSourceObjectPointers, getSourceObjectOptionsArray, validateJsonSchema, } from './utils.js';
+import { JSONPath } from 'jsonpath-plus';
+import { getLocaleProperties } from 'generaltranslation';
+export function mergeJson(originalContent, filePath, options, targets, defaultLocale) {
+    const jsonSchema = validateJsonSchema(options, filePath);
+    if (!jsonSchema) {
+        return targets.map((target) => target.translatedContent);
+    }
+    let originalJson;
+    try {
+        originalJson = JSON.parse(originalContent);
+    }
+    catch (error) {
+        logError(`Invalid JSON file: ${filePath}`);
+        exit(1);
+    }
+    // Handle include
+    if (jsonSchema.include) {
+        const output = [];
+        for (const target of targets) {
+            // Must clone the original JSON to avoid mutations
+            const mergedJson = structuredClone(originalJson);
+            const translatedJson = JSON.parse(target.translatedContent);
+            for (const [jsonPointer, translatedValue] of Object.entries(translatedJson)) {
+                try {
+                    const value = JSONPointer.get(mergedJson, jsonPointer);
+                    if (!value)
+                        continue;
+                    JSONPointer.set(mergedJson, jsonPointer, translatedValue);
+                }
+                catch (error) { }
+            }
+            output.push(JSON.stringify(mergedJson, null, 2));
+        }
+        return output;
+    }
+    if (!jsonSchema.composite) {
+        logError('No composite property found in JSON schema');
+        exit(1);
+    }
+    // Handle composite
+    // Create a deep copy of the original JSON to avoid mutations
+    const mergedJson = structuredClone(originalJson);
+    // Create mapping of sourceObjectPointer to SourceObjectOptions
+    const sourceObjectPointers = generateSourceObjectPointers(jsonSchema.composite, originalJson);
+    // Find the source object
+    for (const [sourceObjectPointer, { sourceObjectValue, sourceObjectOptions },] of Object.entries(sourceObjectPointers)) {
+        // Find the source item
+        if (sourceObjectOptions.type === 'array') {
+            // Validate type
+            if (!Array.isArray(sourceObjectValue)) {
+                logError(`Source object value is not an array at path: ${sourceObjectPointer}`);
+                exit(1);
+            }
+            // Get source item for default locale
+            const matchingDefaultLocaleItem = findMatchingItemArray(defaultLocale, sourceObjectOptions, sourceObjectPointer, sourceObjectValue);
+            if (!matchingDefaultLocaleItem) {
+                logError(`Matching sourceItem not found at path: ${sourceObjectPointer} for locale: ${defaultLocale}. Please check your JSON schema`);
+                exit(1);
+            }
+            const { sourceItem: defaultLocaleSourceItem, keyPointer: defaultLocaleKeyPointer, } = matchingDefaultLocaleItem;
+            // For each target:
+            // 1. Validate that the targetJson has a jsonPointer for the current sourceObjectPointer
+            // 2. If it does, find the source item for the target locale
+            // 3. Override the source item with the translated values
+            // 4. Apply additional mutations to the sourceItem
+            // 5. Merge the source item with the original JSON
+            for (const target of targets) {
+                const targetJson = JSON.parse(target.translatedContent);
+                // 1. Validate that the targetJson has a jsonPointer for the current sourceObjectPointer
+                if (!targetJson[sourceObjectPointer]) {
+                    logWarning(`Translated JSON for locale: ${target.targetLocale} does not have a valid sourceObjectPointer: ${sourceObjectPointer}. Skipping this target`);
+                    continue;
+                }
+                // 2. Find the source item for the target locale
+                const matchingTargetItem = findMatchingItemArray(target.targetLocale, sourceObjectOptions, sourceObjectPointer, sourceObjectValue);
+                // If the target locale has a matching source item, use it to mutate the source item
+                // Otherwise, fallback to the default locale source item
+                const mutateSourceItem = structuredClone(defaultLocaleSourceItem);
+                const mutateSourceItemIndex = matchingTargetItem
+                    ? matchingTargetItem.itemIndex
+                    : undefined;
+                const mutateSourceItemKeyPointer = defaultLocaleKeyPointer;
+                const { identifyingLocaleProperty: targetLocaleKeyProperty } = getSourceObjectOptionsArray(target.targetLocale, sourceObjectPointer, sourceObjectOptions);
+                // 3. Override the source item with the translated values
+                JSONPointer.set(mutateSourceItem, mutateSourceItemKeyPointer, targetLocaleKeyProperty);
+                for (const [translatedKeyJsonPointer, translatedValue,] of Object.entries(targetJson[sourceObjectPointer] || {})) {
+                    try {
+                        const value = JSONPointer.get(mutateSourceItem, translatedKeyJsonPointer);
+                        if (!value)
+                            continue;
+                        JSONPointer.set(mutateSourceItem, translatedKeyJsonPointer, translatedValue);
+                    }
+                    catch (error) { }
+                }
+                // 4. Apply additional mutations to the sourceItem
+                applyTransformations(mutateSourceItem, sourceObjectOptions.transform, target.targetLocale, defaultLocale);
+                // 5. Merge the source item with the original JSON
+                if (mutateSourceItemIndex) {
+                    sourceObjectValue[mutateSourceItemIndex] = mutateSourceItem;
+                }
+                else {
+                    sourceObjectValue.push(mutateSourceItem);
+                }
+            }
+            JSONPointer.set(mergedJson, sourceObjectPointer, sourceObjectValue);
+        }
+        else {
+            // Validate type
+            if (typeof sourceObjectValue !== 'object' || sourceObjectValue === null) {
+                logError(`Source object value is not an object at path: ${sourceObjectPointer}`);
+                exit(1);
+            }
+            // Validate localeProperty
+            const matchingDefaultLocaleItem = findMatchingItemObject(defaultLocale, sourceObjectPointer, sourceObjectOptions, sourceObjectValue);
+            // Validate source item exists
+            if (!matchingDefaultLocaleItem.sourceItem) {
+                logError(`Source item not found at path: ${sourceObjectPointer}. You must specify a source item where its key matches the default locale`);
+                exit(1);
+            }
+            const { sourceItem: defaultLocaleSourceItem } = matchingDefaultLocaleItem;
+            // For each target:
+            // 1. Validate that the targetJson has a jsonPointer for the current sourceObjectPointer
+            // 2. If it does, find the source item for the target locale
+            // 3. Override the source item with the translated values
+            // 4. Apply additional mutations to the sourceItem
+            // 5. Merge the source item with the original JSON
+            for (const target of targets) {
+                const targetJson = JSON.parse(target.translatedContent);
+                // 1. Validate that the targetJson has a jsonPointer for the current sourceObjectPointer
+                if (!targetJson[sourceObjectPointer]) {
+                    logWarning(`Translated JSON for locale: ${target.targetLocale} does not have a valid sourceObjectPointer: ${sourceObjectPointer}. Skipping this target`);
+                    continue;
+                }
+                // 2. Find the source item for the target locale
+                const matchingTargetItem = findMatchingItemObject(target.targetLocale, sourceObjectPointer, sourceObjectOptions, sourceObjectValue);
+                // If the target locale has a matching source item, use it to mutate the source item
+                // Otherwise, fallback to the default locale source item
+                const mutateSourceItem = structuredClone(defaultLocaleSourceItem);
+                const mutateSourceItemKey = matchingTargetItem.keyParentProperty;
+                // 3. Override the source item with the translated values
+                for (const [translatedKeyJsonPointer, translatedValue,] of Object.entries(targetJson[sourceObjectPointer] || {})) {
+                    try {
+                        const value = JSONPointer.get(mutateSourceItem, translatedKeyJsonPointer);
+                        if (!value)
+                            continue;
+                        JSONPointer.set(mutateSourceItem, translatedKeyJsonPointer, translatedValue);
+                    }
+                    catch (error) { }
+                }
+                // 4. Apply additional mutations to the sourceItem
+                applyTransformations(mutateSourceItem, sourceObjectOptions.transform, target.targetLocale, defaultLocale);
+                // 5. Merge the source item with the original JSON
+                sourceObjectValue[mutateSourceItemKey] = mutateSourceItem;
+            }
+            JSONPointer.set(mergedJson, sourceObjectPointer, sourceObjectValue);
+        }
+    }
+    return [JSON.stringify(mergedJson, null, 2)];
+}
+// helper function to replace locale placeholders in a string
+// with the corresponding locale properties
+// ex: {locale} -> will be replaced with the locale code
+// ex: {localeName} -> will be replaced with the locale name
+function replaceLocalePlaceholders(string, localeProperties) {
+    return string.replace(/\{(\w+)\}/g, (match, property) => {
+        // Handle common aliases
+        if (property === 'locale' || property === 'localeCode') {
+            return localeProperties.code;
+        }
+        if (property === 'localeName') {
+            return localeProperties.name;
+        }
+        if (property === 'localeNativeName') {
+            return localeProperties.nativeName;
+        }
+        // Check if the property exists in localeProperties
+        if (property in localeProperties) {
+            return localeProperties[property];
+        }
+        // Return the original placeholder if property not found
+        return match;
+    });
+}
+// apply transformations to the sourceItem in-place
+export function applyTransformations(sourceItem, transform, targetLocale, defaultLocale) {
+    if (!transform)
+        return;
+    const targetLocaleProperties = getLocaleProperties(targetLocale);
+    const defaultLocaleProperties = getLocaleProperties(defaultLocale);
+    for (const [transformPath, transformOptions] of Object.entries(transform)) {
+        if (!transformOptions.replace ||
+            typeof transformOptions.replace !== 'string') {
+            continue;
+        }
+        const results = JSONPath({
+            json: sourceItem,
+            path: transformPath,
+            resultType: 'all',
+            flatten: true,
+            wrap: true,
+        });
+        if (!results || results.length === 0) {
+            continue;
+        }
+        results.forEach((result) => {
+            if (typeof result.value !== 'string') {
+                return;
+            }
+            // Replace locale placeholders in the replace string
+            let replaceString = transformOptions.replace;
+            // Replace all locale property placeholders
+            replaceString = replaceLocalePlaceholders(replaceString, targetLocaleProperties);
+            if (transformOptions.match &&
+                typeof transformOptions.match === 'string') {
+                // Replace locale placeholders in the match string using defaultLocale properties
+                let matchString = transformOptions.match;
+                matchString = replaceLocalePlaceholders(matchString, defaultLocaleProperties);
+                result.value = result.value.replace(new RegExp(matchString, 'g'), replaceString);
+            }
+            else {
+                result.value = replaceString;
+            }
+            // Update the actual sourceItem using JSONPointer
+            JSONPointer.set(sourceItem, result.pointer, result.value);
+        });
+    }
+}

package/dist/formats/json/parseJson.d.ts

@@ -0,0 +1,2 @@
+import { AdditionalOptions } from '../../types/index.js';
+export declare function parseJson(content: string, filePath: string, options: AdditionalOptions, defaultLocale: string): string;

package/dist/formats/json/parseJson.js

@@ -0,0 +1,97 @@
+import { flattenJsonWithStringFilter } from './flattenJson.js';
+import { JSONPath } from 'jsonpath-plus';
+import { exit, logError } from '../../console/logging.js';
+import { findMatchingItemArray, findMatchingItemObject, generateSourceObjectPointers, validateJsonSchema, } from './utils.js';
+// Parse a JSON file according to a JSON schema
+export function parseJson(content, filePath, options, defaultLocale) {
+    const jsonSchema = validateJsonSchema(options, filePath);
+    if (!jsonSchema) {
+        return content;
+    }
+    let json;
+    try {
+        json = JSON.parse(content);
+    }
+    catch (error) {
+        logError(`Invalid JSON file: ${filePath}`);
+        exit(1);
+    }
+    // Handle include
+    if (jsonSchema.include) {
+        const flattenedJson = flattenJsonWithStringFilter(json, jsonSchema.include);
+        return JSON.stringify(flattenedJson);
+    }
+    if (!jsonSchema.composite) {
+        logError('No composite property found in JSON schema');
+        exit(1);
+    }
+    // Construct lvl 1
+    // Create mapping of sourceObjectPointer to SourceObjectOptions
+    const sourceObjectPointers = generateSourceObjectPointers(jsonSchema.composite, json);
+    // Construct lvl 2
+    const sourceObjectsToTranslate = {};
+    for (const [sourceObjectPointer, { sourceObjectValue, sourceObjectOptions },] of Object.entries(sourceObjectPointers)) {
+        // Find the default locale in each source item in each sourceObjectValue
+        // Array: use key field
+        if (sourceObjectOptions.type === 'array') {
+            // Validate type
+            if (!Array.isArray(sourceObjectValue)) {
+                logError(`Source object value is not an array at path: ${sourceObjectPointer}`);
+                exit(1);
+            }
+            // Validate localeProperty
+            const matchingItem = findMatchingItemArray(defaultLocale, sourceObjectOptions, sourceObjectPointer, sourceObjectValue);
+            if (!matchingItem) {
+                logError(`Matching sourceItem not found at path: ${sourceObjectPointer} for locale: ${defaultLocale}. Please check your JSON schema`);
+                exit(1);
+            }
+            const { sourceItem, keyPointer } = matchingItem;
+            // Get the fields to translate from the includes
+            let itemsToTranslate = [];
+            for (const include of sourceObjectOptions.include) {
+                try {
+                    const matchingItems = JSONPath({
+                        json: sourceItem,
+                        path: include,
+                        resultType: 'all',
+                        flatten: true,
+                        wrap: true,
+                    });
+                    if (matchingItems) {
+                        itemsToTranslate.push(...matchingItems);
+                    }
+                }
+                catch (error) { }
+            }
+            itemsToTranslate = Object.fromEntries(itemsToTranslate
+                .filter((item) => item.pointer !== keyPointer)
+                .map((item) => [
+                item.pointer,
+                item.value,
+            ]));
+            // Add the items to translate to the result
+            sourceObjectsToTranslate[sourceObjectPointer] = itemsToTranslate;
+        }
+        else {
+            // Object: use the key in this object with the matching locale property
+            // Validate type
+            if (typeof sourceObjectValue !== 'object' || sourceObjectValue === null) {
+                logError(`Source object value is not an object at path: ${sourceObjectPointer}`);
+                exit(1);
+            }
+            // Validate localeProperty
+            const matchingItem = findMatchingItemObject(defaultLocale, sourceObjectPointer, sourceObjectOptions, sourceObjectValue);
+            // Validate source item exists
+            if (!matchingItem.sourceItem) {
+                logError(`Source item not found at path: ${sourceObjectPointer}. You must specify a source item where its key matches the default locale`);
+                exit(1);
+            }
+            const { sourceItem } = matchingItem;
+            // Get the fields to translate from the includes
+            const itemsToTranslate = flattenJsonWithStringFilter(sourceItem, sourceObjectOptions.include);
+            // Add the items to translate to the result
+            sourceObjectsToTranslate[sourceObjectPointer] = itemsToTranslate;
+        }
+    }
+    return JSON.stringify(sourceObjectsToTranslate);
+}

package/dist/formats/json/utils.d.ts

@@ -0,0 +1,26 @@
+import { AdditionalOptions, JsonSchema, SourceObjectOptions } from '../../types/index.js';
+export declare function findMatchingItemArray(locale: string, sourceObjectOptions: SourceObjectOptions, sourceObjectPointer: string, sourceObjectValue: any): {
+    sourceItem: any;
+    keyParentProperty: string;
+    itemIndex: number;
+    keyPointer: string;
+} | null;
+export declare function findMatchingItemObject(locale: string, sourceObjectPointer: string, sourceObjectOptions: SourceObjectOptions, sourceObjectValue: any): {
+    sourceItem: any | undefined;
+    keyParentProperty: string;
+};
+export declare function getIdentifyingLocaleProperty(locale: string, sourceObjectPointer: string, sourceObjectOptions: SourceObjectOptions): string;
+export declare function getSourceObjectOptionsArray(locale: string, sourceObjectPointer: string, sourceObjectOptions: SourceObjectOptions): {
+    identifyingLocaleProperty: string;
+    localeKeyJsonPath: string;
+};
+export declare function getSourceObjectOptionsObject(defaultLocale: string, sourceObjectPointer: string, sourceObjectOptions: SourceObjectOptions): {
+    identifyingLocaleProperty: string;
+};
+export declare function generateSourceObjectPointers(jsonSchema: {
+    [sourceObjectPath: string]: SourceObjectOptions;
+}, originalJson: any): Record<string, {
+    sourceObjectValue: any;
+    sourceObjectOptions: SourceObjectOptions;
+}>;
+export declare function validateJsonSchema(options: AdditionalOptions, filePath: string): JsonSchema | null;

package/dist/formats/json/utils.js

@@ -0,0 +1,124 @@
+import { getLocaleProperties } from 'generaltranslation';
+import { exit, logError } from '../../console/logging.js';
+import { JSONPath } from 'jsonpath-plus';
+import { flattenJson } from './flattenJson.js';
+import micromatch from 'micromatch';
+import path from 'node:path';
+const { isMatch } = micromatch;
+// Find the matching source item in an array
+// where the key matches the identifying locale property
+// If no matching item is found, exit with an error
+export function findMatchingItemArray(locale, sourceObjectOptions, sourceObjectPointer, sourceObjectValue) {
+    const { identifyingLocaleProperty, localeKeyJsonPath } = getSourceObjectOptionsArray(locale, sourceObjectPointer, sourceObjectOptions);
+    // Use the json pointer key to locate the source item
+    for (const [index, item] of sourceObjectValue.entries()) {
+        // Get the key candidates
+        const keyCandidates = JSONPath({
+            json: item,
+            path: localeKeyJsonPath,
+            resultType: 'all',
+            flatten: true,
+            wrap: true,
+        });
+        if (!keyCandidates) {
+            logError(`Source item at path: ${sourceObjectPointer} does not have a key value at path: ${localeKeyJsonPath}`);
+            exit(1);
+        }
+        else if (keyCandidates.length !== 1) {
+            logError(`Source item at path: ${sourceObjectPointer} has multiple matching keys with path: ${localeKeyJsonPath}`);
+            exit(1);
+        }
+        // Validate the key is the identifying locale property
+        if (!keyCandidates[0] ||
+            identifyingLocaleProperty !== keyCandidates[0].value) {
+            continue;
+        }
+        return {
+            sourceItem: item,
+            keyParentProperty: keyCandidates[0].parentProperty,
+            itemIndex: index,
+            keyPointer: keyCandidates[0].pointer,
+        };
+    }
+    return null;
+}
+export function findMatchingItemObject(locale, sourceObjectPointer, sourceObjectOptions, sourceObjectValue) {
+    const { identifyingLocaleProperty } = getSourceObjectOptionsObject(locale, sourceObjectPointer, sourceObjectOptions);
+    // Locate the source item
+    if (sourceObjectValue[identifyingLocaleProperty]) {
+        return {
+            sourceItem: sourceObjectValue[identifyingLocaleProperty],
+            keyParentProperty: identifyingLocaleProperty,
+        };
+    }
+    return {
+        sourceItem: undefined,
+        keyParentProperty: identifyingLocaleProperty,
+    };
+}
+export function getIdentifyingLocaleProperty(locale, sourceObjectPointer, sourceObjectOptions) {
+    // Validate localeProperty
+    const localeProperty = sourceObjectOptions.localeProperty || 'code';
+    const identifyingLocaleProperty = getLocaleProperties(locale)[localeProperty];
+    if (!identifyingLocaleProperty) {
+        logError(`Source object options localeProperty is not a valid locale property at path: ${sourceObjectPointer}`);
+        exit(1);
+    }
+    return identifyingLocaleProperty;
+}
+export function getSourceObjectOptionsArray(locale, sourceObjectPointer, sourceObjectOptions) {
+    const identifyingLocaleProperty = getIdentifyingLocaleProperty(locale, sourceObjectPointer, sourceObjectOptions);
+    const localeKeyJsonPath = sourceObjectOptions.key;
+    if (!localeKeyJsonPath) {
+        logError(`Source object options key is required for array at path: ${sourceObjectPointer}`);
+        exit(1);
+    }
+    return { identifyingLocaleProperty, localeKeyJsonPath };
+}
+export function getSourceObjectOptionsObject(defaultLocale, sourceObjectPointer, sourceObjectOptions) {
+    const identifyingLocaleProperty = getIdentifyingLocaleProperty(defaultLocale, sourceObjectPointer, sourceObjectOptions);
+    const jsonPathKey = sourceObjectOptions.key;
+    if (jsonPathKey) {
+        logError(`Source object options key is not allowed for object at path: ${sourceObjectPointer}`);
+        exit(1);
+    }
+    return { identifyingLocaleProperty };
+}
+// Generate a mapping of sourceObjectPointer to SourceObjectOptions
+// where the sourceObjectPointer is a jsonpointer to the array or object containing
+export function generateSourceObjectPointers(jsonSchema, originalJson) {
+    const sourceObjectPointers = Object.entries(jsonSchema).reduce((acc, [sourceObjectPath, sourceObjectOptions]) => {
+        const sourceObjects = flattenJson(originalJson, [sourceObjectPath]);
+        Object.entries(sourceObjects).forEach(([pointer, value]) => {
+            acc[pointer] = {
+                sourceObjectValue: value,
+                sourceObjectOptions,
+            };
+        });
+        return acc;
+    }, {});
+    return sourceObjectPointers;
+}
+export function validateJsonSchema(options, filePath) {
+    if (!options.jsonSchema) {
+        return null;
+    }
+    const fileGlobs = Object.keys(options.jsonSchema);
+    const matchingGlob = fileGlobs.find((fileGlob) => isMatch(path.relative(process.cwd(), filePath), fileGlob));
+    if (!matchingGlob || !options.jsonSchema[matchingGlob]) {
+        return null;
+    }
+    // Validate includes or composite
+    const jsonSchema = options.jsonSchema[matchingGlob];
+    if (jsonSchema.include && jsonSchema.composite) {
+        logError('include and composite cannot be used together in the same JSON schema');
+        exit(1);
+        return null;
+    }
+    if (!jsonSchema.include && !jsonSchema.composite) {
+        logError('No include or composite property found in JSON schema');
+        exit(1);
+        return null;
+    }
+    return jsonSchema;
+}

package/dist/fs/config/parseFilesConfig.js

@@ -35,7 +35,7 @@ export function resolveFiles(files, locale, cwd) {
     const transformPaths = {};
     // Process GT files
     if (files.gt?.output) {
-        placeholderResult.gt = files.gt.output;
+        placeholderResult.gt = path.resolve(cwd, files.gt.output);
     }
     for (const fileType of SUPPORTED_FILE_EXTENSIONS) {
         // ==== TRANSFORMS ==== //

package/dist/fs/config/setupConfig.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { displayCreatedConfigFile } from '../../console/logging.js';
 import { logError } from '../../console/logging.js';
+import { GT_CONFIG_SCHEMA_URL } from '../../utils/constants.js';
 /**
  * Checks if the config file exists.
  * If yes, make sure make sure projectId is correct
@@ -25,6 +26,7 @@ export async function createOrUpdateConfig(configFilepath, options) {
         }
         // merge old and new content
         const mergedContent = {
+            $schema: GT_CONFIG_SCHEMA_URL,
             ...oldContent,
             ...newContent,
         };

package/dist/types/data/json.d.ts

@@ -0,0 +1,6 @@
+type JSONValue = string | number | boolean | null | JSONObject | JSONArray;
+export type JSONObject = {
+    [key: string]: JSONValue;
+};
+export type JSONArray = JSONValue[];
+export {};

package/dist/types/data/json.js

@@ -0,0 +1 @@
+export {};

package/dist/types/data.d.ts

@@ -17,7 +17,7 @@ export type JSONDictionary = {
 export type FlattenedJSONDictionary = {
     [key: string]: string;
 };
-export type { FileFormat, DataFormat } from 'generaltranslation/types';
+export type { FileFormat, DataFormat, FileToTranslate, } from 'generaltranslation/types';
 export type JsxChildren = string | string[] | any;
 export type Translations = {
     [key: string]: JsxChildren;

package/dist/types/index.d.ts

@@ -92,4 +92,29 @@ export type Settings = {
     description?: string;
     src: string[];
     framework?: SupportedFrameworks;
+    options?: AdditionalOptions;
+};
+export type AdditionalOptions = {
+    jsonSchema?: {
+        [fileGlob: string]: JsonSchema;
+    };
+};
+export type JsonSchema = {
+    preset?: 'mintlify';
+    include?: string[];
+    composite?: {
+        [sourceObjectPath: string]: SourceObjectOptions;
+    };
+};
+export type SourceObjectOptions = {
+    type: 'array' | 'object';
+    include: string[];
+    key?: string;
+    localeProperty?: string;
+    transform?: {
+        [transformPath: string]: {
+            match?: string;
+            replace: string;
+        };
+    };
 };

package/dist/utils/constants.d.ts

@@ -1 +1,2 @@
 export declare const GT_DASHBOARD_URL = "https://dash.generaltranslation.com";
+export declare const GT_CONFIG_SCHEMA_URL = "https://assets.gtx.dev/config-schema.json";

package/dist/utils/constants.js

@@ -1 +1,2 @@
 export const GT_DASHBOARD_URL = 'https://dash.generaltranslation.com';
+export const GT_CONFIG_SCHEMA_URL = 'https://assets.gtx.dev/config-schema.json';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gtx-cli",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "main": "dist/index.js",
   "bin": "dist/main.js",
   "files": [
@@ -87,7 +87,10 @@
     "esbuild": "^0.25.4",
     "fast-glob": "^3.3.3",
     "form-data": "^4.0.2",
-    "generaltranslation": "^7.1.2",
+    "generaltranslation": "^7.1.4",
+    "jsonpath-plus": "^10.3.0",
+    "jsonpointer": "^5.0.1",
+    "micromatch": "^4.0.8",
     "open": "^10.1.1",
     "ora": "^8.2.0",
     "resolve": "^1.22.10",