generaltranslation 8.2.7 → 8.2.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # generaltranslation
 
+## 8.2.8
+
+### 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.
+
 ## 8.2.7
 
 ### Patch Changes

package/dist/id.d.cts

@@ -1,4 +1,4 @@
-import { ut as HashMetadata, wt as JsxChildren } from "./types-D2fTTTvZ.cjs";
+import { ut as HashMetadata, wt as JsxChildren } from "./types-BJdoI1d1.cjs";
 
 //#region src/id/hashSource.d.ts
 /**

package/dist/id.d.mts

@@ -1,4 +1,4 @@
-import { ut as HashMetadata, wt as JsxChildren } from "./types-fUW4_Ole.mjs";
+import { ut as HashMetadata, wt as JsxChildren } from "./types-DazaDJbs.mjs";
 
 //#region src/id/hashSource.d.ts
 /**

package/dist/index.cjs

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_internal = require("./internal-PCKq4YMW.cjs");
+const require_internal = require("./internal-DIHQF9gs.cjs");
 const require_ApiError = require("./ApiError-4zIP-twr.cjs");
 const require_id = require("./id-VXBgyXu2.cjs");
 let intl_messageformat = require("intl-messageformat");
@@ -1469,6 +1469,7 @@ async function processBatches(items, processor, options = {}) {
 * @returns The result of the API call
 */
 async function _enqueueFiles(files, options, config) {
+	require_internal.validateFileFormatTransforms(files);
 	const result = await processBatches(files, async (batch) => {
 		const apiResult = await apiRequest(config, "/v2/project/translations/enqueue", {
 			body: {
@@ -1476,7 +1477,8 @@ async function _enqueueFiles(files, options, config) {
 					branchId: f.branchId,
 					fileId: f.fileId,
 					versionId: f.versionId,
-					fileName: f.fileName
+					fileName: f.fileName,
+					transformFormat: f.transformFormat
 				})),
 				targetLocales: options.targetLocales,
 				sourceLocale: options.sourceLocale,
@@ -1671,6 +1673,7 @@ async function _uploadSourceFiles(files, options, config) {
 * @returns Promise resolving to a BatchList with all uploaded files
 */
 async function _uploadTranslations(files, options, config) {
+	require_internal.validateFileFormatTransforms(files.map(({ source }) => source));
 	return processBatches(files, async (batch) => {
 		return (await apiRequest(config, "/v2/project/files/upload-translations", {
 			body: {
@@ -1679,6 +1682,7 @@ async function _uploadTranslations(files, options, config) {
 						content: require_internal.encode(source.content),
 						fileName: source.fileName,
 						fileFormat: source.fileFormat,
+						transformFormat: source.transformFormat,
 						locale: source.locale,
 						dataFormat: source.dataFormat,
 						formatMetadata: source.formatMetadata,
@@ -1953,6 +1957,158 @@ async function _publishFiles(files, config) {
 	return await apiRequest(config, "/v2/project/files/publish", { body: { files } });
 }
 //#endregion
+//#region src/LocaleConfig.ts
+/**
+* LocaleConfig is a client-safe locale and formatting helper.
+*
+* It intentionally does not store project IDs, API keys, runtime URLs, or any
+* translation credentials. It only stores locale metadata needed to resolve
+* aliases, choose formatting fallbacks, and format values with Intl.
+*/
+var LocaleConfig = class {
+	constructor({ defaultLocale = "en", locales = [], customMapping } = {}) {
+		this.defaultLocale = defaultLocale;
+		this.locales = locales;
+		this.customMapping = customMapping;
+	}
+	get translationLocales() {
+		return this.locales.length ? this.locales : void 0;
+	}
+	resolveCanonicalLocaleList(locales) {
+		return locales.map((locale) => this.resolveCanonicalLocale(locale));
+	}
+	resolveCanonicalLocaleArgs(locales) {
+		return locales.map((locale) => Array.isArray(locale) ? this.resolveCanonicalLocaleList(locale) : this.resolveCanonicalLocale(locale));
+	}
+	toLocaleList(locales) {
+		return Array.isArray(locales) ? locales : [locales];
+	}
+	getFormattingLocales(targetLocale, locales) {
+		return (locales !== void 0 ? this.toLocaleList(locales) : [
+			targetLocale,
+			this.defaultLocale,
+			"en"
+		]).filter((locale) => !!locale).map((locale) => this.resolveCanonicalLocale(locale));
+	}
+	formatNum(value, targetLocale, options = {}) {
+		const { locales, ...intlOptions } = options;
+		return _formatNum({
+			value,
+			locales: this.getFormattingLocales(targetLocale, locales),
+			options: intlOptions
+		});
+	}
+	formatDateTime(value, targetLocale, options = {}) {
+		const { locales, ...intlOptions } = options;
+		return _formatDateTime({
+			value,
+			locales: this.getFormattingLocales(targetLocale, locales),
+			options: intlOptions
+		});
+	}
+	formatCurrency(value, currency, targetLocale, options = {}) {
+		const { locales, ...intlOptions } = options;
+		return _formatCurrency({
+			value,
+			currency,
+			locales: this.getFormattingLocales(targetLocale, locales),
+			options: intlOptions
+		});
+	}
+	formatRelativeTime(value, unit, targetLocale, options = {}) {
+		const { locales, ...intlOptions } = options;
+		return _formatRelativeTime({
+			value,
+			unit,
+			locales: this.getFormattingLocales(targetLocale, locales),
+			options: intlOptions
+		});
+	}
+	formatRelativeTimeFromDate(date, targetLocale, options = {}) {
+		const { locales, baseDate, ...intlOptions } = options;
+		return _formatRelativeTimeFromDate({
+			date,
+			baseDate: baseDate ?? /* @__PURE__ */ new Date(),
+			locales: this.getFormattingLocales(targetLocale, locales),
+			options: intlOptions
+		});
+	}
+	formatCutoff(value, targetLocale, options = {}) {
+		const { locales, ...formatOptions } = options;
+		return _formatCutoff({
+			value,
+			locales: this.getFormattingLocales(targetLocale, locales),
+			options: formatOptions
+		});
+	}
+	formatMessage(message, targetLocale, options = {}) {
+		const { locales, variables, dataFormat } = options;
+		if (dataFormat === "STRING") return _formatMessageString(message);
+		return _formatMessageICU(message, this.getFormattingLocales(targetLocale, locales), variables);
+	}
+	formatList(array, targetLocale, options = {}) {
+		const { locales, ...intlOptions } = options;
+		return _formatList({
+			value: array,
+			locales: this.getFormattingLocales(targetLocale, locales),
+			options: intlOptions
+		});
+	}
+	formatListToParts(array, targetLocale, options = {}) {
+		const { locales, ...intlOptions } = options;
+		return _formatListToParts({
+			value: array,
+			locales: this.getFormattingLocales(targetLocale, locales),
+			options: intlOptions
+		});
+	}
+	getLocaleName(locale) {
+		return _getLocaleName(locale, this.defaultLocale, this.customMapping);
+	}
+	getLocaleEmoji(locale) {
+		return _getLocaleEmoji(locale, this.customMapping);
+	}
+	getLocaleProperties(locale) {
+		return _getLocaleProperties(locale, this.defaultLocale, this.customMapping);
+	}
+	requiresTranslation(targetLocale, sourceLocale = this.defaultLocale, approvedLocales = this.translationLocales) {
+		return _requiresTranslation(this.resolveCanonicalLocale(sourceLocale), this.resolveCanonicalLocale(targetLocale), approvedLocales ? this.resolveCanonicalLocaleList(approvedLocales) : void 0, this.customMapping);
+	}
+	determineLocale(locales, approvedLocales = this.locales) {
+		const approvedLocalePairs = approvedLocales.map((locale) => ({
+			locale,
+			canonicalLocale: this.resolveCanonicalLocale(locale)
+		}));
+		const resolvedLocale = _determineLocale(Array.isArray(locales) ? this.resolveCanonicalLocaleList(locales) : this.resolveCanonicalLocale(locales), approvedLocalePairs.map(({ canonicalLocale }) => canonicalLocale), this.customMapping);
+		if (!resolvedLocale) return void 0;
+		return approvedLocalePairs.find(({ canonicalLocale }) => canonicalLocale === resolvedLocale)?.locale || this.resolveAliasLocale(resolvedLocale);
+	}
+	getLocaleDirection(locale) {
+		return _getLocaleDirection(this.resolveCanonicalLocale(locale));
+	}
+	isValidLocale(locale) {
+		return _isValidLocale(locale, this.customMapping);
+	}
+	resolveCanonicalLocale(locale) {
+		return _resolveCanonicalLocale(locale, this.customMapping);
+	}
+	resolveAliasLocale(locale) {
+		return _resolveAliasLocale(locale, this.customMapping);
+	}
+	standardizeLocale(locale) {
+		return _standardizeLocale(locale);
+	}
+	isSameDialect(...locales) {
+		return _isSameDialect(...this.resolveCanonicalLocaleArgs(locales));
+	}
+	isSameLanguage(...locales) {
+		return _isSameLanguage(...this.resolveCanonicalLocaleArgs(locales));
+	}
+	isSupersetLocale(superLocale, subLocale) {
+		return _isSupersetLocale(this.resolveCanonicalLocale(superLocale), this.resolveCanonicalLocale(subLocale));
+	}
+};
+//#endregion
 //#region src/index.ts
 /**
 * GT is the core driver for the General Translation library.
@@ -1969,6 +2125,10 @@ async function _publishFiles(files, config) {
 * });
 */
 var GT = class {
+	/** Client-safe locale and formatting helpers */
+	get localeConfig() {
+		return this._localeConfig;
+	}
 	/**
 	* Constructs an instance of the GT class.
 	*
@@ -1985,7 +2145,6 @@ var GT = class {
 	* });
 	*/
 	constructor(params = {}) {
-		this._renderingLocales = [];
 		if (typeof process !== "undefined") {
 			this.apiKey ||= process.env?.GT_API_KEY;
 			this.devApiKey ||= process.env?.GT_DEV_API_KEY;
@@ -2005,10 +2164,6 @@ var GT = class {
 			this.targetLocale = _standardizeLocale(targetLocale);
 			if (!_isValidLocale(this.targetLocale, customMapping)) throw new Error(invalidLocaleError(this.targetLocale));
 		}
-		this._renderingLocales = [];
-		if (this.sourceLocale) this._renderingLocales.push(this.sourceLocale);
-		if (this.targetLocale) this._renderingLocales.push(this.targetLocale);
-		this._renderingLocales.push("en");
 		if (locales) {
 			const result = [];
 			const invalidLocales = [];
@@ -2025,6 +2180,11 @@ var GT = class {
 			this.customMapping = customMapping;
 			this.reverseCustomMapping = Object.fromEntries(Object.entries(customMapping).filter(([, value]) => value && typeof value === "object" && "code" in value).map(([key, value]) => [value.code, key]));
 		}
+		this._localeConfig = new LocaleConfig({
+			defaultLocale: this.sourceLocale,
+			locales: this.locales ?? [],
+			customMapping: this.customMapping
+		});
 	}
 	_getTranslationConfig() {
 		return {
@@ -2521,10 +2681,7 @@ var GT = class {
 	* // Returns: '...ld!'
 	*/
 	formatCutoff(value, options) {
-		return formatCutoff(value, {
-			locales: this._renderingLocales,
-			...options
-		});
+		return this.localeConfig.formatCutoff(value, this.targetLocale, options);
 	}
 	/**
 	* Formats a message according to the specified locales and options.
@@ -2543,10 +2700,7 @@ var GT = class {
 	* // Returns: "Bonjour John"
 	*/
 	formatMessage(message, options) {
-		return formatMessage(message, {
-			locales: this._renderingLocales,
-			...options
-		});
+		return this.localeConfig.formatMessage(message, this.targetLocale, options);
 	}
 	/**
 	* Formats a number according to the specified locales and options.
@@ -2562,10 +2716,7 @@ var GT = class {
 	* // Returns: "$1,234.56"
 	*/
 	formatNum(number, options) {
-		return formatNum(number, {
-			locales: this._renderingLocales,
-			...options
-		});
+		return this.localeConfig.formatNum(number, this.targetLocale, options);
 	}
 	/**
 	* Formats a date according to the specified locales and options.
@@ -2581,10 +2732,7 @@ var GT = class {
 	* // Returns: "Thursday, March 14, 2024 at 2:30:45 PM GMT-7"
 	*/
 	formatDateTime(date, options) {
-		return formatDateTime(date, {
-			locales: this._renderingLocales,
-			...options
-		});
+		return this.localeConfig.formatDateTime(date, this.targetLocale, options);
 	}
 	/**
 	* Formats a currency value according to the specified locales and options.
@@ -2601,10 +2749,7 @@ var GT = class {
 	* // Returns: "$1,234.56"
 	*/
 	formatCurrency(value, currency, options) {
-		return formatCurrency(value, currency, {
-			locales: this._renderingLocales,
-			...options
-		});
+		return this.localeConfig.formatCurrency(value, currency, this.targetLocale, options);
 	}
 	/**
 	* Formats a list of items according to the specified locales and options.
@@ -2620,11 +2765,7 @@ var GT = class {
 	* // Returns: "apple, banana, and orange"
 	*/
 	formatList(array, options) {
-		return _formatList({
-			value: array,
-			locales: options?.locales || this._renderingLocales,
-			options
-		});
+		return this.localeConfig.formatList(array, this.targetLocale, options);
 	}
 	/**
 	* Formats a list of items according to the specified locales and options.
@@ -2639,11 +2780,7 @@ var GT = class {
 	* // Returns: ['apple', ', ', 42, ' and ', '{ foo: "bar" }']
 	*/
 	formatListToParts(array, options) {
-		return _formatListToParts({
-			value: array,
-			locales: options?.locales || this._renderingLocales,
-			options
-		});
+		return this.localeConfig.formatListToParts(array, this.targetLocale, options);
 	}
 	/**
 	* Formats a relative time value according to the specified locales and options.
@@ -2660,10 +2797,7 @@ var GT = class {
 	* // Returns: "yesterday"
 	*/
 	formatRelativeTime(value, unit, options) {
-		return formatRelativeTime(value, unit, {
-			locales: this._renderingLocales,
-			...options
-		});
+		return this.localeConfig.formatRelativeTime(value, unit, this.targetLocale, options);
 	}
 	/**
 	* Formats a relative time string from a Date, automatically selecting the best unit.
@@ -2678,10 +2812,7 @@ var GT = class {
 	* // Returns: "1 hour ago"
 	*/
 	formatRelativeTimeFromDate(date, options) {
-		return formatRelativeTimeFromDate(date, {
-			locales: this._renderingLocales,
-			...options
-		});
+		return this.localeConfig.formatRelativeTimeFromDate(date, this.targetLocale, options);
 	}
 	/**
 	* Retrieves the display name of a locale code using Intl.DisplayNames, returning an empty string if no name is found.
@@ -2696,7 +2827,7 @@ var GT = class {
 	*/
 	getLocaleName(locale = this.targetLocale) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("getLocaleName"));
-		return _getLocaleName(locale, this.sourceLocale, this.customMapping);
+		return this.localeConfig.getLocaleName(locale);
 	}
 	/**
 	* Retrieves an emoji based on a given locale code.
@@ -2712,7 +2843,7 @@ var GT = class {
 	*/
 	getLocaleEmoji(locale = this.targetLocale) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("getLocaleEmoji"));
-		return getLocaleEmoji(locale, this.customMapping);
+		return this.localeConfig.getLocaleEmoji(locale);
 	}
 	/**
 	* Generates linguistic details for a given locale code.
@@ -2748,7 +2879,7 @@ var GT = class {
 	*/
 	getLocaleProperties(locale = this.targetLocale) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("getLocaleProperties"));
-		return getLocaleProperties(locale, this.sourceLocale, this.customMapping);
+		return this.localeConfig.getLocaleProperties(locale);
 	}
 	/**
 	* Retrieves multiple properties for a given region code, including:
@@ -2822,6 +2953,7 @@ var GT = class {
 	requiresTranslation(sourceLocale = this.sourceLocale, targetLocale = this.targetLocale, approvedLocales = this.locales, customMapping = this.customMapping) {
 		if (!sourceLocale) throw new Error(noSourceLocaleProvidedError("requiresTranslation"));
 		if (!targetLocale) throw new Error(noTargetLocaleProvidedError("requiresTranslation"));
+		if (customMapping === this.customMapping) return this.localeConfig.requiresTranslation(targetLocale, sourceLocale, approvedLocales);
 		return _requiresTranslation(sourceLocale, targetLocale, approvedLocales, customMapping);
 	}
 	/**
@@ -2836,6 +2968,7 @@ var GT = class {
 	* // Returns: "fr-FR"
 	*/
 	determineLocale(locales, approvedLocales = this.locales || [], customMapping = this.customMapping) {
+		if (customMapping === this.customMapping) return this.localeConfig.determineLocale(locales, approvedLocales ?? []);
 		return _determineLocale(locales, approvedLocales, customMapping);
 	}
 	/**
@@ -2851,7 +2984,7 @@ var GT = class {
 	*/
 	getLocaleDirection(locale = this.targetLocale) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("getLocaleDirection"));
-		return getLocaleDirection(locale);
+		return this.localeConfig.getLocaleDirection(locale);
 	}
 	/**
 	* Checks if a given BCP 47 locale code is valid.
@@ -2867,7 +3000,8 @@ var GT = class {
 	*/
 	isValidLocale(locale = this.targetLocale, customMapping = this.customMapping) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("isValidLocale"));
-		return isValidLocale(locale, customMapping);
+		if (customMapping === this.customMapping) return this.localeConfig.isValidLocale(locale);
+		return _isValidLocale(locale, customMapping);
 	}
 	/**
 	* Resolves the canonical locale for a given locale.
@@ -2877,6 +3011,7 @@ var GT = class {
 	*/
 	resolveCanonicalLocale(locale = this.targetLocale, customMapping = this.customMapping) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("resolveCanonicalLocale"));
+		if (customMapping === this.customMapping) return this.localeConfig.resolveCanonicalLocale(locale);
 		return _resolveCanonicalLocale(locale, customMapping);
 	}
 	/**
@@ -2887,6 +3022,7 @@ var GT = class {
 	*/
 	resolveAliasLocale(locale, customMapping = this.customMapping) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("resolveAliasLocale"));
+		if (customMapping === this.customMapping) return this.localeConfig.resolveAliasLocale(locale);
 		return _resolveAliasLocale(locale, customMapping);
 	}
 	/**
@@ -2902,7 +3038,7 @@ var GT = class {
 	*/
 	standardizeLocale(locale = this.targetLocale) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("standardizeLocale"));
-		return _standardizeLocale(locale);
+		return this.localeConfig.standardizeLocale(locale);
 	}
 	/**
 	* Checks if multiple BCP 47 locale codes represent the same dialect.
@@ -2918,7 +3054,7 @@ var GT = class {
 	* // Returns: true
 	*/
 	isSameDialect(...locales) {
-		return isSameDialect(...locales);
+		return this.localeConfig.isSameDialect(...locales);
 	}
 	/**
 	* Checks if multiple BCP 47 locale codes represent the same language.
@@ -2931,7 +3067,7 @@ var GT = class {
 	* // Returns: true
 	*/
 	isSameLanguage(...locales) {
-		return _isSameLanguage(...locales);
+		return this.localeConfig.isSameLanguage(...locales);
 	}
 	/**
 	* Checks if a locale is a superset of another locale.
@@ -2948,7 +3084,7 @@ var GT = class {
 	* // Returns: false
 	*/
 	isSupersetLocale(superLocale, subLocale) {
-		return isSupersetLocale(superLocale, subLocale);
+		return this.localeConfig.isSupersetLocale(superLocale, subLocale);
 	}
 };
 /**
@@ -3326,6 +3462,7 @@ const API_VERSION = API_VERSION$1;
 //#endregion
 exports.API_VERSION = API_VERSION;
 exports.GT = GT;
+exports.LocaleConfig = LocaleConfig;
 exports.__toESM = __toESM;
 exports.determineLocale = determineLocale;
 exports.formatCurrency = formatCurrency;