gt 2.14.21 → 2.14.22

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # gtx-cli
 
+## 2.14.22
+
+### Patch Changes
+
+- [#1248](https://github.com/generaltranslation/gt/pull/1248) [`b12d57d`](https://github.com/generaltranslation/gt/commit/b12d57dab1d5cb1f602c5ac24a702b48cda7f11e) Thanks [@ErnestM1234](https://github.com/ErnestM1234)! - Add PO/POT file format support and transformFormat plumbing for API uploads and CLI file downloads.
+
+- Updated dependencies [[`b12d57d`](https://github.com/generaltranslation/gt/commit/b12d57dab1d5cb1f602c5ac24a702b48cda7f11e)]:
+  - generaltranslation@8.2.8
+  - @generaltranslation/python-extractor@0.2.13
+
 ## 2.14.21
 
 ### Patch Changes

package/dist/api/collectUserEditDiffs.js

@@ -27,8 +27,8 @@ const findLatestDownloadedVersion = (entryMap, fileId, locale) => {
 export async function collectAndSendUserEditDiffs(files, settings) {
     if (!settings.files)
         return false;
-    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
-    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+    const { resolvedPaths, placeholderPaths, transformPaths, transformFormats } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, transformFormats, settings.locales, settings.defaultLocale);
     const { entryMap } = readLockfile(settings);
     const tempDir = path.join(os.tmpdir(), randomUUID());
     if (!fs.existsSync(tempDir))

package/dist/api/downloadFileBatch.js

@@ -13,10 +13,16 @@ import { readLockfile, writeLockfile, findOrCreateEntry, } from '../fs/config/do
 import { recordDownloaded, recordRemerged } from '../state/recentDownloads.js';
 import { recordWarning } from '../state/translateWarnings.js';
 import stringify from 'fast-json-stable-stringify';
+import { SUPPORTED_FILE_EXTENSIONS } from '../formats/files/supportedFiles.js';
+import { hasNonIdentityFileFormatTransformForType } from '../formats/files/transformFormat.js';
+import { getRelative } from '../fs/findFilepath.js';
 /**
  * Merges translated content with the current source file for schema-based formats.
  */
 function mergeWithSource(translatedContent, locale, inputPath, options) {
+    if (shouldSkipSourceFormatMerge(inputPath, options)) {
+        return translatedContent;
+    }
     if (!options.options)
         return translatedContent;
     const jsonSchema = options.options.jsonSchema
@@ -49,6 +55,23 @@ function mergeWithSource(translatedContent, locale, inputPath, options) {
         return mergeYaml(sourceContent, inputPath, options.options, [{ translatedContent, targetLocale: locale }], options.defaultLocale)[0];
     }
 }
+/**
+ * Determines whether a source file should be skipped for schema re-merging.
+ * @param inputPath - The path of the source file
+ * @param options - The settings for the project
+ * @returns True if the source file should be skipped for schema re-merging, false otherwise
+ */
+function shouldSkipSourceFormatMerge(inputPath, options) {
+    for (const fileType of SUPPORTED_FILE_EXTENSIONS) {
+        if (!hasNonIdentityFileFormatTransformForType(options, fileType))
+            continue;
+        const transformedSourcePaths = options.files.resolvedPaths[fileType] || [];
+        if (transformedSourcePaths.some((sourcePath) => getRelative(sourcePath) === inputPath)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Downloads multiple translation files in a single batch request
  * @param files - Array of files to download with their output paths

package/dist/cli/commands/download.js

@@ -25,8 +25,8 @@ export async function handleDownload(options, settings, library) {
         return logErrorAndExit(noFilesError);
     }
     // Files
-    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
-    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+    const { resolvedPaths, placeholderPaths, transformPaths, transformFormats } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, transformFormats, settings.locales, settings.defaultLocale);
     // Collect the hashes for all files we need to download
     let fileVersionData;
     if (settings.stageTranslations) {

package/dist/cli/commands/translate.js

@@ -10,11 +10,14 @@ import localizeStaticImports from '../../utils/localizeStaticImports.js';
 import { getDownloadedMeta } from '../../state/recentDownloads.js';
 import { persistPostProcessHashes } from '../../utils/persistPostprocessHashes.js';
 import { runPublishWorkflow } from '../../workflows/publish.js';
+import { SUPPORTED_FILE_EXTENSIONS } from '../../formats/files/supportedFiles.js';
+import { hasNonIdentityFileFormatTransformForType } from '../../formats/files/transformFormat.js';
+import { getRelative } from '../../fs/findFilepath.js';
 // Downloads translations that were completed
 export async function handleTranslate(options, settings, fileVersionData, jobData, branchData, publishMap) {
     if (fileVersionData) {
-        const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
-        const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+        const { resolvedPaths, placeholderPaths, transformPaths, transformFormats, } = settings.files;
+        const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, transformFormats, settings.locales, settings.defaultLocale);
         // Check for remaining translations
         await runDownloadWorkflow({
             fileVersionData: fileVersionData,
@@ -39,21 +42,24 @@ export async function handleTranslate(options, settings, fileVersionData, jobDat
     }
 }
 export async function postProcessTranslations(settings, includeFiles) {
+    const postProcessIncludes = filterPostProcessIncludesForFormatTransforms(settings, includeFiles);
+    if (includeFiles && postProcessIncludes?.size === 0)
+        return;
     // Mintlify OpenAPI localization (spec routing + validation)
-    await processOpenApi(settings, includeFiles);
+    await processOpenApi(settings, postProcessIncludes);
     // Localize static urls (/docs -> /[locale]/docs) and preserve anchor IDs for non-default locales
     // Default locale is processed earlier in the flow in base.ts
     if (settings.options?.experimentalLocalizeStaticUrls) {
         const nonDefaultLocales = settings.locales.filter((locale) => locale !== settings.defaultLocale);
         if (nonDefaultLocales.length > 0) {
-            await localizeStaticUrls(settings, nonDefaultLocales, includeFiles);
+            await localizeStaticUrls(settings, nonDefaultLocales, postProcessIncludes);
         }
     }
     // Rewrite relative asset URLs in translated md/mdx files
     if (settings.options?.experimentalLocalizeRelativeAssets) {
         const nonDefaultLocales = settings.locales.filter((locale) => locale !== settings.defaultLocale);
         if (nonDefaultLocales.length > 0) {
-            await localizeRelativeAssets(settings, nonDefaultLocales, includeFiles);
+            await localizeRelativeAssets(settings, nonDefaultLocales, postProcessIncludes);
         }
     }
     const shouldProcessAnchorIds = settings.options?.experimentalLocalizeStaticUrls ||
@@ -61,20 +67,51 @@ export async function postProcessTranslations(settings, includeFiles) {
     // Add explicit anchor IDs to translated MDX/MD files to preserve navigation
     // Uses inline {#id} format by default, or div wrapping if experimentalAddHeaderAnchorIds is 'mintlify'
     if (shouldProcessAnchorIds) {
-        await processAnchorIds(settings, includeFiles);
+        await processAnchorIds(settings, postProcessIncludes);
     }
     // Localize static imports (import Snippet from /snippets/file.mdx -> import Snippet from /snippets/[locale]/file.mdx)
     if (settings.options?.experimentalLocalizeStaticImports) {
-        await localizeStaticImports(settings, includeFiles);
+        await localizeStaticImports(settings, postProcessIncludes);
     }
     // Flatten json files into a single file
     if (settings.options?.experimentalFlattenJsonFiles) {
-        await flattenJsonFiles(settings, includeFiles);
+        await flattenJsonFiles(settings, postProcessIncludes);
     }
     // Copy files to the target locale
     if (settings.options?.copyFiles) {
         await copyFile(settings);
     }
     // Record postprocessed content hashes for newly downloaded files
-    persistPostProcessHashes(settings, includeFiles, getDownloadedMeta());
+    persistPostProcessHashes(settings, postProcessIncludes, getDownloadedMeta());
+}
+/**
+ * Exclude only outputs whose source file was translated into a different format.
+ * @param settings - The settings for the project
+ * @param includeFiles - The files to include in the post-processing
+ * @returns The files to exclude in the post-processing
+ */
+function filterPostProcessIncludesForFormatTransforms(settings, includeFiles) {
+    if (!includeFiles)
+        return includeFiles;
+    const transformedSourcePaths = new Set();
+    for (const fileType of SUPPORTED_FILE_EXTENSIONS) {
+        if (!hasNonIdentityFileFormatTransformForType(settings, fileType))
+            continue;
+        for (const sourcePath of settings.files.resolvedPaths[fileType] || []) {
+            transformedSourcePaths.add(getRelative(sourcePath));
+        }
+    }
+    if (transformedSourcePaths.size === 0)
+        return includeFiles;
+    const { resolvedPaths, placeholderPaths, transformPaths, transformFormats } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, transformFormats, settings.locales, settings.defaultLocale);
+    const transformedOutputPaths = new Set();
+    for (const localeMapping of Object.values(fileMapping)) {
+        for (const [sourcePath, outputPath] of Object.entries(localeMapping)) {
+            if (transformedSourcePaths.has(sourcePath)) {
+                transformedOutputPaths.add(outputPath);
+            }
+        }
+    }
+    return new Set([...includeFiles].filter((filePath) => !transformedOutputPaths.has(filePath)));
 }

package/dist/cli/commands/upload.js

@@ -16,6 +16,7 @@ import { hashStringSync } from '../../utils/hash.js';
 import { hasValidCredentials } from './utils/validation.js';
 import { buildPublishMap } from '../../utils/resolvePublish.js';
 import { runPublishWorkflow } from '../../workflows/publish.js';
+import { getTransformFormatProperty } from '../../formats/files/transformFormat.js';
 const SUPPORTED_DATA_FORMATS = ['JSX', 'ICU', 'I18NEXT'];
 /**
  * Sends multiple files to the API for translation
@@ -60,6 +61,7 @@ export async function upload(filePaths, placeholderPaths, transformPaths, dataFo
                 content: parsedJson,
                 fileName: relativePath,
                 fileFormat: 'JSON',
+                ...getTransformFormatProperty(settings, 'json'),
                 dataFormat,
                 locale: settings.defaultLocale,
                 fileId: hashStringSync(relativePath),
@@ -81,6 +83,7 @@ export async function upload(filePaths, placeholderPaths, transformPaths, dataFo
                 content: parsedYaml,
                 fileName: relativePath,
                 fileFormat,
+                ...getTransformFormatProperty(settings, 'yaml'),
                 dataFormat,
                 locale: settings.defaultLocale,
                 fileId: hashStringSync(relativePath),
@@ -99,6 +102,7 @@ export async function upload(filePaths, placeholderPaths, transformPaths, dataFo
                 content: parsedJson,
                 fileName: relativePath,
                 fileFormat: 'TWILIO_CONTENT_JSON',
+                ...getTransformFormatProperty(settings, 'twilioContentJson'),
                 dataFormat: 'STRING',
                 locale: settings.defaultLocale,
                 fileId: hashStringSync(relativePath),
@@ -121,6 +125,7 @@ export async function upload(filePaths, placeholderPaths, transformPaths, dataFo
                     content: sanitizedContent,
                     fileName: relativePath,
                     fileFormat: fileType.toUpperCase(),
+                    ...getTransformFormatProperty(settings, fileType),
                     dataFormat,
                     locale: settings.defaultLocale,
                     fileId: hashStringSync(relativePath),
@@ -141,13 +146,14 @@ export async function upload(filePaths, placeholderPaths, transformPaths, dataFo
         return exitSync(1);
     const locales = settings.locales || [];
     // Create file mapping for all file types
-    const fileMapping = createFileMapping(filePaths, placeholderPaths, transformPaths, locales, settings.defaultLocale);
+    const fileMapping = createFileMapping(filePaths, placeholderPaths, transformPaths, settings.files?.transformFormats || {}, locales, settings.defaultLocale);
     // construct object
     const uploadData = allFiles.map((file) => {
         const sourceFile = {
             content: file.content,
             fileName: file.fileName,
             fileFormat: file.fileFormat,
+            transformFormat: file.transformFormat,
             dataFormat: file.dataFormat,
             locale: file.locale,
             fileId: file.fileId,
@@ -163,7 +169,7 @@ export async function upload(filePaths, placeholderPaths, transformPaths, dataFo
                     translations.push({
                         content: extracted,
                         fileName: file.fileName,
-                        fileFormat: file.fileFormat,
+                        fileFormat: file.transformFormat ?? file.fileFormat,
                         dataFormat: file.dataFormat,
                         locale,
                         fileId: file.fileId,
@@ -178,8 +184,8 @@ export async function upload(filePaths, placeholderPaths, transformPaths, dataFo
                     const translatedContent = readFileSync(translatedFileName, 'utf8');
                     translations.push({
                         content: translatedContent,
-                        fileName: file.fileName,
-                        fileFormat: file.fileFormat,
+                        fileName: translatedFileName,
+                        fileFormat: file.transformFormat ?? file.fileFormat,
                         dataFormat: file.dataFormat,
                         locale,
                         fileId: file.fileId,

package/dist/config/generateSettings.js

@@ -13,6 +13,7 @@ import { resolveConfig } from './resolveConfig.js';
 import { gt } from '../utils/gt.js';
 import { generatePreset } from './optionPresets.js';
 import { GT_PARSING_FLAGS_DEFAULT } from './defaults.js';
+import { normalizeFilesOptions } from '../formats/files/transformFormat.js';
 export const DEFAULT_SRC_PATTERNS = [
     'src/**/*.{js,jsx,ts,tsx}',
     'app/**/*.{js,jsx,ts,tsx}',
@@ -147,11 +148,12 @@ export async function generateSettings(flags, cwd = process.cwd(), options) {
         .filter(([, schema]) => schema.composite)
         .map(([key]) => key);
     mergedOptions.files = mergedOptions.files
-        ? resolveFiles(mergedOptions.files, mergedOptions.defaultLocale, mergedOptions.locales, cwd, compositePatterns)
+        ? resolveFiles(normalizeFilesOptions(mergedOptions.files), mergedOptions.defaultLocale, mergedOptions.locales, cwd, compositePatterns)
         : {
             resolvedPaths: {},
             placeholderPaths: {},
             transformPaths: {},
+            transformFormats: {},
             publishPaths: new Set(),
             unpublishPaths: new Set(),
             parsingFlags: {},

package/dist/formats/files/aggregateFiles.js

@@ -14,6 +14,7 @@ import { hashStringSync } from '../../utils/hash.js';
 import { preprocessContent } from './preprocessContent.js';
 import { parseKeyedMetadata, } from '../parseKeyedMetadata.js';
 import { buildPublishMap } from '../../utils/resolvePublish.js';
+import { getTransformFormatProperty } from './transformFormat.js';
 /**
  * Checks if a file path is a metadata companion file (e.g. foo.metadata.json)
  * AND its corresponding source file (e.g. foo.json) exists in the file list.
@@ -123,6 +124,7 @@ export async function aggregateFiles(settings) {
                 content: parsedJson,
                 fileName: relativePath,
                 fileFormat: 'JSON',
+                ...getTransformFormatProperty(settings, 'json'),
                 dataFormat,
                 locale: settings.defaultLocale,
                 ...(keyedMetadata && {
@@ -193,6 +195,7 @@ export async function aggregateFiles(settings) {
                 content: parsedYaml,
                 fileName: relativePath,
                 fileFormat,
+                ...getTransformFormatProperty(settings, 'yaml'),
                 fileId: hashStringSync(relativePath),
                 versionId: hashStringSync(parsedYaml),
                 locale: settings.defaultLocale,
@@ -235,6 +238,7 @@ export async function aggregateFiles(settings) {
                 content: parsedJson,
                 fileName: relativePath,
                 fileFormat: 'TWILIO_CONTENT_JSON',
+                ...getTransformFormatProperty(settings, 'twilioContentJson'),
                 dataFormat: 'STRING',
                 locale: settings.defaultLocale,
             };
@@ -271,6 +275,7 @@ export async function aggregateFiles(settings) {
                     content: processed,
                     fileName: relativePath,
                     fileFormat: fileType.toUpperCase(),
+                    ...getTransformFormatProperty(settings, fileType),
                     fileId: hashStringSync(relativePath),
                     versionId: hashStringSync(processed),
                     locale: settings.defaultLocale,

package/dist/formats/files/fileMapping.d.ts

@@ -1,11 +1,12 @@
-import { ResolvedFiles, TransformFiles } from '../../types/index.js';
+import { ResolvedFiles, TransformFiles, TransformFormats } from '../../types/index.js';
 import { FileMapping } from '../../types/files.js';
 /**
  * Creates a mapping between source files and their translated counterparts for each locale
  * @param filePaths - Resolved file paths for different file types
  * @param placeholderPaths - Placeholder paths for translated files
  * @param transformPaths - Transform paths for file naming
+ * @param transformFormats - Output file format transforms for translated files
  * @param locales - List of locales to create a mapping for
  * @returns A mapping between source files and their translated counterparts for each locale, in the form of relative paths
  */
-export declare function createFileMapping(filePaths: ResolvedFiles, placeholderPaths: ResolvedFiles, transformPaths: TransformFiles, targetLocales: string[], defaultLocale: string): FileMapping;
+export declare function createFileMapping(filePaths: ResolvedFiles, placeholderPaths: ResolvedFiles, transformPaths: TransformFiles, transformFormats: TransformFormats, targetLocales: string[], defaultLocale: string): FileMapping;

package/dist/formats/files/fileMapping.js

@@ -5,15 +5,17 @@ import { getRelative } from '../../fs/findFilepath.js';
 import { getLocaleProperties } from 'generaltranslation';
 import { replaceLocalePlaceholders } from '../utils.js';
 import { TEMPLATE_FILE_NAME } from '../../utils/constants.js';
+import { replaceFileExtensionForFormat } from './transformFormat.js';
 /**
  * Creates a mapping between source files and their translated counterparts for each locale
  * @param filePaths - Resolved file paths for different file types
  * @param placeholderPaths - Placeholder paths for translated files
  * @param transformPaths - Transform paths for file naming
+ * @param transformFormats - Output file format transforms for translated files
  * @param locales - List of locales to create a mapping for
  * @returns A mapping between source files and their translated counterparts for each locale, in the form of relative paths
  */
-export function createFileMapping(filePaths, placeholderPaths, transformPaths, targetLocales, defaultLocale) {
+export function createFileMapping(filePaths, placeholderPaths, transformPaths, transformFormats, targetLocales, defaultLocale) {
     const fileMapping = {};
     for (const locale of targetLocales) {
         const translatedPaths = resolveLocaleFiles(placeholderPaths, locale);
@@ -32,6 +34,7 @@ export function createFileMapping(filePaths, placeholderPaths, transformPaths, t
             if (!translatedFiles)
                 continue;
             const transformPath = transformPaths[typeIndex];
+            const transformFormat = transformFormats?.[typeIndex];
             if (transformPath) {
                 if (typeof transformPath === 'string') {
                     translatedFiles = translatedFiles.map((filePath) => {
@@ -105,7 +108,10 @@ export function createFileMapping(filePaths, placeholderPaths, transformPaths, t
             }
             for (let i = 0; i < sourcePaths.length; i++) {
                 const sourceFile = getRelative(sourcePaths[i]);
-                const translatedFile = getRelative(translatedFiles[i]);
+                // Format transforms keep the mapped path but rewrite the output suffix.
+                const translatedFile = getRelative(transformFormat
+                    ? replaceFileExtensionForFormat(translatedFiles[i], transformFormat)
+                    : translatedFiles[i]);
                 localeMapping[sourceFile] = translatedFile;
             }
         }

package/dist/formats/files/supportedFiles.d.ts

@@ -1,6 +1,7 @@
-export declare const SUPPORTED_FILE_EXTENSIONS: readonly ["json", "mdx", "md", "ts", "js", "yaml", "html", "txt", "twilioContentJson"];
+export declare const SUPPORTED_FILE_EXTENSIONS: readonly ["json", "pot", "mdx", "md", "ts", "js", "yaml", "html", "txt", "twilioContentJson"];
 export declare const FILE_EXT_TO_EXT_LABEL: {
     json: string;
+    pot: string;
     mdx: string;
     md: string;
     ts: string;

package/dist/formats/files/supportedFiles.js

@@ -1,5 +1,6 @@
 export const SUPPORTED_FILE_EXTENSIONS = [
     'json',
+    'pot',
     'mdx',
     'md',
     'ts',
@@ -11,6 +12,7 @@ export const SUPPORTED_FILE_EXTENSIONS = [
 ];
 export const FILE_EXT_TO_EXT_LABEL = {
     json: 'JSON',
+    pot: 'POT',
     mdx: 'MDX',
     md: 'Markdown',
     ts: 'TypeScript',

package/dist/formats/files/transformFormat.d.ts

@@ -0,0 +1,68 @@
+import type { FileFormat } from '../../types/data.js';
+import type { FilesOptions, Settings, SupportedFileExtension } from '../../types/index.js';
+/**
+ * Maps CLI config file keys to API file format enum values.
+ */
+export declare const CONFIG_FILE_TYPE_TO_FILE_FORMAT: {
+    readonly json: "JSON";
+    readonly pot: "POT";
+    readonly mdx: "MDX";
+    readonly md: "MD";
+    readonly ts: "TS";
+    readonly js: "JS";
+    readonly yaml: "YAML";
+    readonly html: "HTML";
+    readonly txt: "TXT";
+    readonly twilioContentJson: "TWILIO_CONTENT_JSON";
+};
+/**
+ * Maps uppercase config aliases to the CLI's canonical lowercase file keys.
+ */
+export declare const FILE_FORMAT_TO_CONFIG_FILE_TYPE: {
+    readonly JSON: "json";
+    readonly POT: "pot";
+    readonly MDX: "mdx";
+    readonly MD: "md";
+    readonly TS: "ts";
+    readonly JS: "js";
+    readonly YAML: "yaml";
+    readonly HTML: "html";
+    readonly TXT: "txt";
+    readonly TWILIO_CONTENT_JSON: "twilioContentJson";
+};
+/**
+ * Converts uppercase file format config keys into the CLI's canonical lowercase keys.
+ *
+ * This lets users write either `files.POT` or `files.pot` while keeping the
+ * rest of the CLI on its existing lowercase file-type convention.
+ */
+export declare function normalizeFilesOptions(files: FilesOptions): FilesOptions;
+/**
+ * Validates and resolves a configured output format for a source file type.
+ *
+ * Throws when the requested source -> output format is not supported by
+ * `generaltranslation/internal`.
+ */
+export declare function resolveTransformationFormat(fileType: SupportedFileExtension, transformationFormat: string | undefined): FileFormat | undefined;
+/**
+ * Returns the API upload/enqueue property for a file type when one is configured.
+ */
+export declare function getTransformFormatProperty(settings: Settings, fileType: SupportedFileExtension): {
+    transformFormat?: FileFormat;
+};
+/**
+ * Returns the preferred file extension for a translated file format.
+ */
+export declare function getFileExtensionForFormat(format: FileFormat): string;
+/**
+ * Rewrites a path's extension to match the translated file format.
+ */
+export declare function replaceFileExtensionForFormat(filePath: string, format: FileFormat): string;
+/**
+ * Detects whether any configured format transform changes the output file type.
+ */
+export declare function hasNonIdentityFileFormatTransform(settings: Settings): boolean;
+/**
+ * Returns true when the configured transform for a file type changes its format.
+ */
+export declare function hasNonIdentityFileFormatTransformForType(settings: Settings, fileType: SupportedFileExtension): boolean;

package/dist/formats/files/transformFormat.js

@@ -0,0 +1,122 @@
+import { validateFileFormatTransforms } from 'generaltranslation/internal';
+/**
+ * Maps CLI config file keys to API file format enum values.
+ */
+export const CONFIG_FILE_TYPE_TO_FILE_FORMAT = {
+    json: 'JSON',
+    pot: 'POT',
+    mdx: 'MDX',
+    md: 'MD',
+    ts: 'TS',
+    js: 'JS',
+    yaml: 'YAML',
+    html: 'HTML',
+    txt: 'TXT',
+    twilioContentJson: 'TWILIO_CONTENT_JSON',
+};
+/**
+ * Maps uppercase config aliases to the CLI's canonical lowercase file keys.
+ */
+export const FILE_FORMAT_TO_CONFIG_FILE_TYPE = {
+    JSON: 'json',
+    POT: 'pot',
+    MDX: 'mdx',
+    MD: 'md',
+    TS: 'ts',
+    JS: 'js',
+    YAML: 'yaml',
+    HTML: 'html',
+    TXT: 'txt',
+    TWILIO_CONTENT_JSON: 'twilioContentJson',
+};
+/**
+ * Maps API file format enum values to the extension the CLI should write.
+ */
+const FILE_FORMAT_EXTENSIONS = {
+    GTJSON: 'json',
+    JSON: 'json',
+    PO: 'po',
+    POT: 'pot',
+    YAML: 'yaml',
+    MDX: 'mdx',
+    MD: 'md',
+    TS: 'ts',
+    JS: 'js',
+    HTML: 'html',
+    TXT: 'txt',
+    TWILIO_CONTENT_JSON: 'json',
+};
+/**
+ * Converts uppercase file format config keys into the CLI's canonical lowercase keys.
+ *
+ * This lets users write either `files.POT` or `files.pot` while keeping the
+ * rest of the CLI on its existing lowercase file-type convention.
+ */
+export function normalizeFilesOptions(files) {
+    const normalized = { ...files };
+    for (const [fileFormat, fileType] of Object.entries(FILE_FORMAT_TO_CONFIG_FILE_TYPE)) {
+        const uppercaseConfig = normalized[fileFormat];
+        if (!normalized[fileType] && uppercaseConfig) {
+            normalized[fileType] = uppercaseConfig;
+        }
+        delete normalized[fileFormat];
+    }
+    return normalized;
+}
+/**
+ * Validates and resolves a configured output format for a source file type.
+ *
+ * Throws when the requested source -> output format is not supported by
+ * `generaltranslation/internal`.
+ */
+export function resolveTransformationFormat(fileType, transformationFormat) {
+    if (!transformationFormat)
+        return undefined;
+    const fileFormat = CONFIG_FILE_TYPE_TO_FILE_FORMAT[fileType];
+    validateFileFormatTransforms([
+        {
+            fileFormat,
+            transformFormat: transformationFormat,
+            fileName: `files.${fileType}`,
+        },
+    ]);
+    return transformationFormat;
+}
+/**
+ * Returns the API upload/enqueue property for a file type when one is configured.
+ */
+export function getTransformFormatProperty(settings, fileType) {
+    const transformFormat = settings.files?.transformFormats?.[fileType];
+    return transformFormat ? { transformFormat } : {};
+}
+/**
+ * Returns the preferred file extension for a translated file format.
+ */
+export function getFileExtensionForFormat(format) {
+    return FILE_FORMAT_EXTENSIONS[format];
+}
+/**
+ * Rewrites a path's extension to match the translated file format.
+ */
+export function replaceFileExtensionForFormat(filePath, format) {
+    const extension = getFileExtensionForFormat(format);
+    return /\.[^/.]+$/.test(filePath)
+        ? filePath.replace(/\.[^/.]+$/, `.${extension}`)
+        : `${filePath}.${extension}`;
+}
+/**
+ * Detects whether any configured format transform changes the output file type.
+ */
+export function hasNonIdentityFileFormatTransform(settings) {
+    return Object.entries(settings.files?.transformFormats || {}).some(([fileType, transformFormat]) => transformFormat &&
+        CONFIG_FILE_TYPE_TO_FILE_FORMAT[fileType] !==
+            transformFormat);
+}
+/**
+ * Returns true when the configured transform for a file type changes its format.
+ */
+export function hasNonIdentityFileFormatTransformForType(settings, fileType) {
+    const transformFormat = settings.files?.transformFormats?.[fileType];
+    return !!(transformFormat &&
+        CONFIG_FILE_TYPE_TO_FILE_FORMAT[fileType] !== transformFormat);
+}

package/dist/fs/config/parseFilesConfig.js

@@ -5,6 +5,7 @@ import { logger } from '../../console/logger.js';
 import chalk from 'chalk';
 import micromatch from 'micromatch';
 import { BASE_PARSING_FLAGS_DEFAULT, GT_PARSING_FLAGS_DEFAULT, } from '../../config/defaults.js';
+import { resolveTransformationFormat } from '../../formats/files/transformFormat.js';
 /**
  * Resolves the files from the files object
  * Replaces [locale] with the actual locale in the files
@@ -59,6 +60,8 @@ export function resolveFiles(files, locale, locales, cwd, compositePatterns) {
     const resolvedPaths = {};
     const placeholderResult = {};
     const transformPaths = {};
+    // Output format transforms are tracked separately from path transforms.
+    const transformFormats = {};
     const publishPaths = new Set();
     const unpublishPaths = new Set();
     const parsingFlags = {};
@@ -75,6 +78,11 @@ export function resolveFiles(files, locale, locales, cwd, compositePatterns) {
                 Array.isArray(transform))) {
             transformPaths[fileType] = transform;
         }
+        // Validate source -> output format transforms during settings generation.
+        const transformFormat = resolveTransformationFormat(fileType, files[fileType]?.transformationFormat);
+        if (transformFormat) {
+            transformFormats[fileType] = transformFormat;
+        }
         // ==== PLACEHOLDERS ==== //
         if (files[fileType]?.include) {
             const { paths, publishPatterns, unpublishPatterns } = normalizeIncludePatterns(files[fileType].include);
@@ -96,6 +104,7 @@ export function resolveFiles(files, locale, locales, cwd, compositePatterns) {
         resolvedPaths,
         placeholderPaths: placeholderResult,
         transformPaths: transformPaths,
+        transformFormats,
         publishPaths,
         unpublishPaths,
         parsingFlags,

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const PACKAGE_VERSION = "2.14.21";
+export declare const PACKAGE_VERSION = "2.14.22";

package/dist/generated/version.js

@@ -1,2 +1,2 @@
 // This file is auto-generated. Do not edit manually.
-export const PACKAGE_VERSION = '2.14.21';
+export const PACKAGE_VERSION = '2.14.22';

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-import { CustomMapping } from 'generaltranslation/types';
+import { CustomMapping, FileFormat } from 'generaltranslation/types';
 import { SUPPORTED_FILE_EXTENSIONS } from '../formats/files/supportedFiles.js';
 import { ParsingConfigOptions, GTParsingFlags, BaseParsingFlags, ParseFlagsByFileType } from './parsing.js';
 import { Libraries, InlineLibrary } from './libraries.js';
@@ -135,6 +135,9 @@ export type TransformOption = {
 export type TransformFiles = {
     [K in SupportedFileExtension]?: TransformOption | string | TransformOption[];
 };
+export type TransformFormats = {
+    [K in SupportedFileExtension]?: FileFormat;
+};
 export type IncludePattern = string | {
     pattern: string;
     publish?: boolean;
@@ -144,6 +147,7 @@ export type FilesOptions = {
         include: IncludePattern[];
         exclude?: string[];
         transform?: string | TransformOption | TransformOption[];
+        transformationFormat?: FileFormat;
         parsingFlags?: BaseParsingFlags;
     };
 } & {
@@ -172,6 +176,7 @@ export type Settings = {
         resolvedPaths: ResolvedFiles;
         placeholderPaths: ResolvedFiles;
         transformPaths: TransformFiles;
+        transformFormats: TransformFormats;
         publishPaths: Set<string>;
         unpublishPaths: Set<string>;
         parsingFlags: ParseFlagsByFileType;

package/dist/utils/flattenJsonFiles.js

@@ -7,7 +7,7 @@ export default async function flattenJsonFiles(settings, includeFiles) {
         return;
     }
     const { resolvedPaths: sourceFiles } = settings.files;
-    const fileMapping = createFileMapping(sourceFiles, settings.files.placeholderPaths, settings.files.transformPaths, settings.locales, settings.defaultLocale);
+    const fileMapping = createFileMapping(sourceFiles, settings.files.placeholderPaths, settings.files.transformPaths, settings.files.transformFormats, settings.locales, settings.defaultLocale);
     await Promise.all(Object.values(fileMapping).map(async (filesMap) => {
         const targetFiles = Object.values(filesMap).filter((p) => p.endsWith('.json') && (!includeFiles || includeFiles.has(p)));
         await Promise.all(targetFiles.map(async (file) => {

package/dist/utils/localizeRelativeAssets.js

@@ -136,7 +136,7 @@ export default async function localizeRelativeAssets(settings, targetLocales, in
     }
     const { resolvedPaths: sourceFiles } = settings.files;
     const locales = targetLocales || settings.locales;
-    const fileMapping = createFileMapping(sourceFiles, settings.files.placeholderPaths, settings.files.transformPaths, settings.locales, settings.defaultLocale);
+    const fileMapping = createFileMapping(sourceFiles, settings.files.placeholderPaths, settings.files.transformPaths, settings.files.transformFormats, settings.locales, settings.defaultLocale);
     const cwd = process.cwd();
     const processPromises = Object.entries(fileMapping)
         .filter(([locale]) => locales.includes(locale))

package/dist/utils/localizeStaticImports.js

@@ -28,7 +28,7 @@ export default async function localizeStaticImports(settings, includeFiles) {
         return;
     }
     const { resolvedPaths: sourceFiles } = settings.files;
-    const fileMapping = createFileMapping(sourceFiles, settings.files.placeholderPaths, settings.files.transformPaths, settings.locales, settings.defaultLocale);
+    const fileMapping = createFileMapping(sourceFiles, settings.files.placeholderPaths, settings.files.transformPaths, settings.files.transformFormats, settings.locales, settings.defaultLocale);
     // Process all file types at once with a single call
     const processPromises = [];
     // First, process default locale files (from source files)

package/dist/utils/localizeStaticUrls.js

@@ -31,7 +31,7 @@ export default async function localizeStaticUrls(settings, targetLocales, includ
     const { resolvedPaths: sourceFiles } = settings.files;
     // Use filtered locales if provided, otherwise use all locales
     const locales = targetLocales || settings.locales;
-    const fileMapping = createFileMapping(sourceFiles, settings.files.placeholderPaths, settings.files.transformPaths, settings.locales, // Always use all locales for mapping, filter later
+    const fileMapping = createFileMapping(sourceFiles, settings.files.placeholderPaths, settings.files.transformPaths, settings.files.transformFormats, settings.locales, // Always use all locales for mapping, filter later
     settings.defaultLocale);
     // Process all file types at once with a single call
     const processPromises = [];

package/dist/utils/processAnchorIds.js

@@ -9,8 +9,8 @@ import * as fs from 'fs';
 export default async function processAnchorIds(settings, includeFiles) {
     if (!settings.files)
         return;
-    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
-    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+    const { resolvedPaths, placeholderPaths, transformPaths, transformFormats } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, transformFormats, settings.locales, settings.defaultLocale);
     const sourceTypeByPath = new Map();
     if (resolvedPaths.md) {
         for (const filePath of resolvedPaths.md) {

package/dist/utils/processOpenApi.js

@@ -34,8 +34,8 @@ export default async function processOpenApi(settings, includeFiles) {
     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 { resolvedPaths, placeholderPaths, transformPaths, transformFormats } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, transformFormats, settings.locales, settings.defaultLocale);
     const fileMappingAbs = {};
     for (const [locale, mapping] of Object.entries(fileMapping)) {
         fileMappingAbs[locale] = {};

package/dist/utils/sharedStaticAssets.js

@@ -226,11 +226,11 @@ export async function mirrorAssetsToLocales(settings) {
     const assetPaths = resolveAssetPaths(include, cwd);
     if (assetPaths.size === 0)
         return;
-    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
+    const { resolvedPaths, placeholderPaths, transformPaths, transformFormats } = settings.files;
     const targetLocales = settings.locales.filter((l) => l !== settings.defaultLocale);
     if (targetLocales.length === 0)
         return;
-    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, targetLocales, settings.defaultLocale);
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, transformFormats, targetLocales, settings.defaultLocale);
     for (const locale of targetLocales) {
         const filesMap = fileMapping[locale];
         if (!filesMap)

package/dist/workflows/steps/UploadSourcesStep.js

@@ -110,7 +110,15 @@ export class UploadSourcesStep extends WorkflowStep {
             sourceLocale: this.settings.defaultLocale,
             modelProvider: this.settings.modelProvider,
         });
-        this.result = response.uploadedFiles;
+        // The API may not echo transformFormat, so preserve it from local inputs.
+        const localFileMap = new Map(files.map((f) => [`${f.fileId}:${f.versionId}`, f]));
+        this.result = response.uploadedFiles.map((uploadedFile) => {
+            const localFile = localFileMap.get(`${uploadedFile.fileId}:${uploadedFile.versionId}`);
+            return {
+                ...uploadedFile,
+                transformFormat: localFile?.transformFormat ?? uploadedFile.transformFormat,
+            };
+        });
         // Merge files that were already uploaded into the result
         this.result.push(...filesToSkipUpload.map((f) => ({
             fileId: f.fileId,
@@ -118,6 +126,7 @@ export class UploadSourcesStep extends WorkflowStep {
             branchId: f.branchId ?? currentBranchId,
             fileName: f.fileName,
             fileFormat: f.fileFormat,
+            transformFormat: f.transformFormat,
             dataFormat: f.dataFormat,
             locale: f.locale,
         })));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gt",
-  "version": "2.14.21",
+  "version": "2.14.22",
   "main": "dist/index.js",
   "bin": "dist/main.js",
   "files": [
@@ -110,8 +110,8 @@
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "yaml": "^2.8.0",
-    "@generaltranslation/python-extractor": "0.2.12",
-    "generaltranslation": "8.2.7",
+    "@generaltranslation/python-extractor": "0.2.13",
+    "generaltranslation": "8.2.8",
     "gt-remark": "1.0.7"
   },
   "devDependencies": {