generaltranslation 8.2.11 → 8.2.13

package/dist/index.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_IntlCache = require("./IntlCache-k2qfrDqB.cjs");
-const require_core = require("./core-3SOQ5ND6.cjs");
-const require_base64 = require("./base64-CUcEPEC5.cjs");
+const require_IntlCache = require("./IntlCache-CAW8tKhd.cjs");
+const require_core = require("./core-7RP541eY.cjs");
+const require_base64 = require("./base64-2fu94Klt.cjs");
 const require_ApiError = require("./ApiError-CZ45tkW6.cjs");
-const require_id = require("./id-COlX5v3V.cjs");
+const require_id = require("./id-CyiXsQrY.cjs");
 //#region src/logging/errors.ts
 const GT_ERROR_PREFIX = "GT Error:";
 const translationTimeoutError = (timeout) => `${GT_ERROR_PREFIX} Translation request timed out after ${timeout}ms.`;
@@ -110,10 +110,10 @@ function getRetryDelay(policy, attempt) {
 * Encapsulates URL construction, fetch with timeout, error handling,
 * response validation, and JSON parsing.
 *
-* @param config - The configuration for the API call
+* @param config - The configuration for the API call.
 * @param endpoint - The API endpoint path (e.g. '/v2/project/jobs/info')
-* @param options - Optional request options
-* @returns The parsed JSON response
+* @param options - Optional request options.
+* @returns The parsed JSON response.
 */
 async function apiRequest(config, endpoint, options) {
 	const timeout = options?.timeout ?? 6e4;
@@ -158,7 +158,7 @@ async function _translateMany(requests, globalMetadata, config, timeout) {
 		const hash = key ?? metadata?.hash ?? require_id.hashSource({
 			source,
 			dataFormat: metadata?.dataFormat ?? "STRING",
-			...metadata ?? {}
+			...metadata
 		});
 		hashOrder?.push(hash);
 		requestsObject[hash] = {
@@ -192,9 +192,9 @@ async function _translateMany(requests, globalMetadata, config, timeout) {
 * @internal
 * Enqueues files for project setup the General Translation API.
 * @param files - References of files to translate (file content already uploaded)
-* @param config - The configuration for the API call
+* @param config - The configuration for the API call.
 * @param timeoutMS - The timeout in milliseconds
-* @returns The result of the API call
+* @returns The result of the API call.
 */
 async function _setupProject(files, config, options) {
 	return apiRequest(config, "/v2/project/setup/generate", {
@@ -214,9 +214,9 @@ async function _setupProject(files, config, options) {
 //#region src/translate/utils/batch.ts
 /**
 * Splits an array into batches of a specified size.
-* @param items - The array to split into batches
-* @param batchSize - The maximum size of each batch
-* @returns An array of batches
+* @param items - The array to split into batches.
+* @param batchSize - The maximum size of each batch.
+* @returns An array of batches.
 */
 function createBatches(items, batchSize) {
 	const batches = [];
@@ -226,10 +226,10 @@ function createBatches(items, batchSize) {
 /**
 * Processes items in batches using a provided processor function.
 *
-* @param items - The items to process
-* @param processor - Async function that processes a single batch and returns items
-* @param options - Optional configuration for batch processing
-* @returns Promise that resolves to a BatchList containing all processed items
+* @param items - The items to process.
+* @param processor - Async function that processes a single batch and returns items.
+* @param options - Optional configuration for batch processing.
+* @returns Promise that resolves to a BatchList containing all processed items.
 *
 * @example
 * ```typescript
@@ -275,9 +275,9 @@ async function processBatches(items, processor, options = {}) {
 * @internal
 * Enqueues files for translation in the General Translation API.
 * @param files - References of files to translate (file content already uploaded)
-* @param options - The options for the API call
-* @param config - The configuration for the API call
-* @returns The result of the API call
+* @param options - The options for the API call.
+* @param config - The configuration for the API call.
+* @returns The result of the API call.
 */
 async function _enqueueFiles(files, options, config) {
 	require_base64.validateFileFormatTransforms(files);
@@ -312,9 +312,9 @@ async function _enqueueFiles(files, options, config) {
 /**
 * @internal
 * Creates or upserts a file tag in the General Translation API.
-* @param options - The tag creation options
-* @param config - The configuration for the API call
-* @returns The created or updated tag
+* @param options - The tag creation options.
+* @param config - The configuration for the API call.
+* @returns The created or updated tag.
 */
 async function _createTag(options, config) {
 	return await apiRequest(config, "/v2/project/tags/create", { body: {
@@ -329,8 +329,8 @@ async function _createTag(options, config) {
 * @internal
 * Downloads multiple translation files in batches.
 * @param files - Array of files to download
-* @param options - The options for the API call
-* @param config - The configuration for the request
+* @param options - The options for the API call.
+* @param config - The configuration for the request.
 * @returns Promise resolving to a BatchList with all downloaded files
 */
 async function _downloadFileBatch(requests, options, config) {
@@ -420,9 +420,9 @@ function _getRegionProperties(region, defaultLocale = "en", customMapping) {
 /**
 * @internal
 * Uploads source files to the General Translation API in batches.
-* @param files - The files to upload
-* @param options - The options for the API call
-* @param config - The configuration for the API call
+* @param files - The files to upload.
+* @param options - The options for the API call.
+* @param config - The configuration for the API call.
 * @returns Promise resolving to a BatchList with all uploaded files
 */
 async function _uploadSourceFiles(files, options, config) {
@@ -454,8 +454,8 @@ async function _uploadSourceFiles(files, options, config) {
 * @internal
 * Uploads multiple translations to the General Translation API in batches.
 * @param files - Translations to upload with their source
-* @param options - The options for the API call
-* @param config - The configuration for the API call
+* @param options - The options for the API call.
+* @param config - The configuration for the API call.
 * @returns Promise resolving to a BatchList with all uploaded files
 */
 async function _uploadTranslations(files, options, config) {
@@ -499,8 +499,8 @@ async function _uploadTranslations(files, options, config) {
 * @internal
 * Gets the source file and translation information for a given file ID and version ID.
 * @param query - The file ID and version ID to get the source file and translation information for
-* @param options - The options for the API call
-* @param config - The configuration for the request
+* @param options - The options for the API call.
+* @param config - The configuration for the request.
 * @returns The source file and translation information for the given file ID and version ID
 */
 async function _querySourceFile(query, options, config) {
@@ -521,9 +521,9 @@ async function _querySourceFile(query, options, config) {
 * @internal
 * Gets the project data for a given project ID.
 * @param projectId - The project ID to get the project data for
-* @param options - The options for the API call
-* @param config - The configuration for the request
-* @returns The project data for the given project ID
+* @param options - The options for the API call.
+* @param config - The configuration for the request.
+* @returns The project data for the given project ID.
 */
 async function _getProjectData(projectId, options, config) {
 	const { baseUrl } = config;
@@ -545,11 +545,11 @@ async function _getProjectData(projectId, options, config) {
 //#region src/translate/checkJobStatus.ts
 /**
 * @internal
-* Queries job statuses for a project
-* @param jobIds - Job IDs
-* @param config - The configuration for the API call
-* @param timeoutMS - The timeout in milliseconds
-* @returns The result of the API call
+* Queries job statuses for a project.
+* @param jobIds - Job IDs.
+* @param config - The configuration for the API call.
+* @param timeoutMs - The timeout in milliseconds.
+* @returns The result of the API call.
 */
 async function _checkJobStatus(jobIds, config, timeoutMs) {
 	return apiRequest(config, "/v2/project/jobs/info", {
@@ -562,10 +562,10 @@ async function _checkJobStatus(jobIds, config, timeoutMs) {
 /**
 * @internal
 * Polls job statuses until all jobs are finished or the timeout is reached.
-* @param enqueueResult - The result from enqueueFiles
-* @param options - Polling configuration
-* @param config - API credentials and configuration
-* @returns The final status of all jobs
+* @param enqueueResult - The result from enqueueFiles.
+* @param options - Polling configuration.
+* @param config - API credentials and configuration.
+* @returns The final status of all jobs.
 */
 async function _awaitJobs(enqueueResult, options, config) {
 	const pollingInterval = (options?.pollingIntervalSeconds ?? 5) * 1e3;
@@ -609,9 +609,9 @@ async function _awaitJobs(enqueueResult, options, config) {
 * @internal
 * Queries data about one or more source or translation files.
 * @param data - Object mapping source or translation file information
-* @param options - The options for the API call
-* @param config - The configuration for the API call
-* @returns The file data
+* @param options - The options for the API call.
+* @param config - The configuration for the API call.
+* @returns The file data.
 */
 async function _queryFileData(data, options = {}, config) {
 	return apiRequest(config, "/v2/project/files/info", {
@@ -637,8 +637,8 @@ async function _queryFileData(data, options = {}, config) {
 * @internal
 * Queries branch information from the API.
 * @param query - Object mapping the current branch and incoming branches
-* @param config - The configuration for the API call
-* @returns The branch information
+* @param config - The configuration for the API call.
+* @returns The branch information.
 */
 async function _queryBranchData(query, config) {
 	return apiRequest(config, "/v2/project/branches/info", { body: query });
@@ -649,8 +649,8 @@ async function _queryBranchData(query, config) {
 * @internal
 * Creates a new branch in the API.
 * @param query - Object mapping the branch name and default branch flag
-* @param config - The configuration for the API call
-* @returns The created branch information
+* @param config - The configuration for the API call.
+* @returns The created branch information.
 */
 async function _createBranch(query, config) {
 	return apiRequest(config, "/v2/project/branches/create", { body: query });
@@ -663,7 +663,7 @@ async function _createBranch(query, config) {
 * Called when the CLI detects that files have been moved/renamed.
 * @param moves - Array of move mappings (old fileId to new fileId)
 * @param options - Options including branchId and timeout
-* @param config - The configuration for the API call
+* @param config - The configuration for the API call.
 * @returns Promise resolving to the move results
 */
 async function _processFileMoves(moves, options, config) {
@@ -736,8 +736,8 @@ async function _getOrphanedFiles(branchId, fileIds, options = {}, config) {
 * @internal
 * Publishes or unpublishes files on the CDN.
 * @param files - Array of file entries with publish flags
-* @param config - The configuration for the API call
-* @returns The result of the API call
+* @param config - The configuration for the API call.
+* @returns The result of the API call.
 */
 async function _publishFiles(files, config) {
 	return await apiRequest(config, "/v2/project/files/publish", { body: { files } });
@@ -843,7 +843,7 @@ var GT = class {
 	* Queries branch information from the API.
 	*
 	* @param {BranchQuery} query - Object mapping the current branch and incoming branches
-	* @returns {Promise<BranchDataResult>} The branch information
+	* @returns {Promise<BranchDataResult>} The branch information.
 	*/
 	async queryBranchData(query) {
 		this._validateAuth("queryBranchData");
@@ -853,7 +853,7 @@ var GT = class {
 	* Creates a new branch in the API. If the branch already exists, it will be returned.
 	*
 	* @param {CreateBranchQuery} query - Object mapping the branch name and default branch flag
-	* @returns {Promise<CreateBranchResult>} The created branch information
+	* @returns {Promise<CreateBranchResult>} The created branch information.
 	*/
 	async createBranch(query) {
 		this._validateAuth("createBranch");
@@ -865,7 +865,7 @@ var GT = class {
 	*
 	* @param {MoveMapping[]} moves - Array of move mappings (old fileId to new fileId)
 	* @param {ProcessMovesOptions} options - Options including branchId and timeout
-	* @returns {Promise<ProcessMovesResponse>} The move processing results
+	* @returns {Promise<ProcessMovesResponse>} The move processing results.
 	*
 	* @example
 	* const result = await gt.processFileMoves([
@@ -881,10 +881,10 @@ var GT = class {
 	* but whose fileIds are not in the provided list.
 	* Used for move detection.
 	*
-	* @param {string} branchId - The branch to check for orphaned files
+	* @param {string} branchId - The branch to check for orphaned files.
 	* @param {string[]} fileIds - List of current file IDs (files that are NOT orphaned)
-	* @param {Object} options - Options including timeout
-	* @returns {Promise<GetOrphanedFilesResult>} The orphaned files
+	* @param {Object} options - Options including timeout.
+	* @returns {Promise<GetOrphanedFilesResult>} The orphaned files.
 	*
 	* @example
 	* const result = await gt.getOrphanedFiles('branch-id', ['file-1', 'file-2']);
@@ -902,7 +902,7 @@ var GT = class {
 	* for processing and will generate a project setup based on the source files.
 	*
 	* @param {FileReference[]} files - Array of file references containing IDs of previously uploaded source files
-	* @param {SetupProjectOptions} [options] - Optional settings for target locales and timeout
+	* @param {SetupProjectOptions} [options] - Optional settings for target locales and timeout.
 	* @returns {Promise<SetupProjectResult>} Object containing the jobId and status
 	*/
 	async setupProject(files, options) {
@@ -919,9 +919,9 @@ var GT = class {
 	* This method polls the API to determine whether one or more jobs are still running,
 	* have completed successfully, or have failed. Jobs are created after calling either enqueueFiles or setupProject.
 	*
-	* @param {string[]} jobIds - The unique identifiers of the jobs to check
-	* @param {number} [timeoutMs] - Optional timeout in milliseconds for the API request
-	* @returns {Promise<CheckJobStatusResult>} Object containing the job status
+	* @param {string[]} jobIds - The unique identifiers of the jobs to check.
+	* @param {number} [timeoutMs] - Optional timeout in milliseconds for the API request.
+	* @returns {Promise<CheckJobStatusResult>} Object containing the job status.
 	*
 	* @example
 	* const result = await gt.checkJobStatus([
@@ -938,9 +938,9 @@ var GT = class {
 	/**
 	* Polls job statuses until all jobs from enqueueFiles are finished or the timeout is reached.
 	*
-	* @param {EnqueueFilesResult} enqueueResult - The result returned from enqueueFiles
-	* @param {AwaitJobsOptions} [options] - Polling configuration (interval, timeout)
-	* @returns {Promise<AwaitJobsResult>} The final status of all jobs and whether they all completed
+	* @param {EnqueueFilesResult} enqueueResult - The result returned from enqueueFiles.
+	* @param {AwaitJobsOptions} [options] - Polling configuration (interval, timeout).
+	* @returns {Promise<AwaitJobsResult>} The final status of all jobs and whether they all completed.
 	*/
 	async awaitJobs(enqueueResult, options) {
 		this._validateAuth("awaitJobs");
@@ -956,8 +956,8 @@ var GT = class {
 	* generate translated content based on the source files and target locales provided.
 	*
 	* @param {FileReferenceIds[]} files - Array of file references containing IDs of previously uploaded source files
-	* @param {EnqueueOptions} options - Configuration options including source locale, target locales, and job settings
-	* @returns {Promise<EnqueueFilesResult>} Result containing job IDs, queue status, and processing information
+	* @param {EnqueueOptions} options - Configuration options including source locale, target locales, and job settings.
+	* @returns {Promise<EnqueueFilesResult>} Result containing job IDs, queue status, and processing information.
 	*/
 	async enqueueFiles(files, options) {
 		this._validateAuth("enqueueFiles");
@@ -987,7 +987,7 @@ var GT = class {
 	* with a user-defined tag ID and optional message.
 	*
 	* @param {CreateTagOptions} options - Tag creation options including tagId, sourceFileIds, and optional message
-	* @returns {Promise<CreateTagResult>} The created or updated tag
+	* @returns {Promise<CreateTagResult>} The created or updated tag.
 	*/
 	async createTag(options) {
 		this._validateAuth("createTag");
@@ -1224,8 +1224,8 @@ var GT = class {
 	* translations through the translation workflow.
 	*
 	* @param {Array<{source: FileUpload}>} files - Array of objects containing source file data to upload
-	* @param {UploadFilesOptions} options - Configuration options including source locale and other upload settings
-	* @returns {Promise<UploadFilesResponse>} Upload result containing file IDs, version information, and upload status
+	* @param {UploadFilesOptions} options - Configuration options including source locale and other upload settings.
+	* @returns {Promise<UploadFilesResponse>} Upload result containing file IDs, version information, and upload status.
 	*/
 	async uploadSourceFiles(files, options) {
 		this._validateAuth("uploadSourceFiles");
@@ -1256,10 +1256,10 @@ var GT = class {
 	* that you want to upload directly rather than generating them through the translation service.
 	*
 	* @param {Array<{source: FileUpload, translations: FileUpload[]}>} files - Array of file objects where:
-	*   - `source`: Reference to the existing source file (contains IDs but no content)
+	*   - `source`: Reference to the existing source file (contains IDs but no content).
 	*   - `translations`: Array of translated files, each containing content, locale, and reference IDs
-	* @param {UploadFilesOptions} options - Configuration options including source locale and upload settings
-	* @returns {Promise<UploadFilesResponse>} Upload result containing translation IDs, status, and processing information
+	* @param {UploadFilesOptions} options - Configuration options including source locale and upload settings.
+	* @returns {Promise<UploadFilesResponse>} Upload result containing translation IDs, status, and processing information.
 	*/
 	async uploadTranslations(files, options) {
 		this._validateAuth("uploadTranslations");
@@ -1339,11 +1339,11 @@ var GT = class {
 	/**
 	* Formats a number according to the specified locales and options.
 	*
-	* @param {number} number - The number to format
-	* @param {Object} [options] - Additional options for number formatting
-	* @param {string | string[]} [options.locales] - The locales to use for formatting
-	* @param {Intl.NumberFormatOptions} [options] - Additional Intl.NumberFormat options
-	* @returns {string} The formatted number
+	* @param {number} number - The number to format.
+	* @param {Object} [options] - Additional options for number formatting.
+	* @param {string | string[]} [options.locales] - The locales to use for formatting.
+	* @param {Intl.NumberFormatOptions} [options] - Additional Intl.NumberFormat options.
+	* @returns {string} The formatted number.
 	*
 	* @example
 	* gt.formatNum(1234.56, { style: 'currency', currency: 'USD' });
@@ -1355,11 +1355,11 @@ var GT = class {
 	/**
 	* Formats a date according to the specified locales and options.
 	*
-	* @param {Date} date - The date to format
-	* @param {Object} [options] - Additional options for date formatting
-	* @param {string | string[]} [options.locales] - The locales to use for formatting
-	* @param {Intl.DateTimeFormatOptions} [options] - Additional Intl.DateTimeFormat options
-	* @returns {string} The formatted date
+	* @param {Date} date - The date to format.
+	* @param {Object} [options] - Additional options for date formatting.
+	* @param {string | string[]} [options.locales] - The locales to use for formatting.
+	* @param {Intl.DateTimeFormatOptions} [options] - Additional Intl.DateTimeFormat options.
+	* @returns {string} The formatted date.
 	*
 	* @example
 	* gt.formatDateTime(new Date(), { dateStyle: 'full', timeStyle: 'long' });
@@ -1371,12 +1371,12 @@ var GT = class {
 	/**
 	* Formats a currency value according to the specified locales and options.
 	*
-	* @param {number} value - The currency value to format
+	* @param {number} value - The currency value to format.
 	* @param {string} currency - The currency code (e.g., 'USD', 'EUR')
-	* @param {Object} [options] - Additional options for currency formatting
-	* @param {string | string[]} [options.locales] - The locales to use for formatting
-	* @param {Intl.NumberFormatOptions} [options] - Additional Intl.NumberFormat options
-	* @returns {string} The formatted currency value
+	* @param {Object} [options] - Additional options for currency formatting.
+	* @param {string | string[]} [options.locales] - The locales to use for formatting.
+	* @param {Intl.NumberFormatOptions} [options] - Additional Intl.NumberFormat options.
+	* @returns {string} The formatted currency value.
 	*
 	* @example
 	* gt.formatCurrency(1234.56, 'USD', { style: 'currency' });
@@ -1388,11 +1388,11 @@ var GT = class {
 	/**
 	* Formats a list of items according to the specified locales and options.
 	*
-	* @param {Array<string | number>} array - The list of items to format
-	* @param {Object} [options] - Additional options for list formatting
-	* @param {string | string[]} [options.locales] - The locales to use for formatting
-	* @param {Intl.ListFormatOptions} [options] - Additional Intl.ListFormat options
-	* @returns {string} The formatted list
+	* @param {Array<string | number>} array - The list of items to format.
+	* @param {Object} [options] - Additional options for list formatting.
+	* @param {string | string[]} [options.locales] - The locales to use for formatting.
+	* @param {Intl.ListFormatOptions} [options] - Additional Intl.ListFormat options.
+	* @returns {string} The formatted list.
 	*
 	* @example
 	* gt.formatList(['apple', 'banana', 'orange'], { type: 'conjunction' });
@@ -1403,11 +1403,11 @@ var GT = class {
 	}
 	/**
 	* Formats a list of items according to the specified locales and options.
-	* @param {Array<T>} array - The list of items to format
-	* @param {Object} [options] - Additional options for list formatting
-	* @param {string | string[]} [options.locales] - The locales to use for formatting
-	* @param {Intl.ListFormatOptions} [options] - Additional Intl.ListFormat options
-	* @returns {Array<T | string>} The formatted list parts
+	* @param {Array<T>} array - The list of items to format.
+	* @param {Object} [options] - Additional options for list formatting.
+	* @param {string | string[]} [options.locales] - The locales to use for formatting.
+	* @param {Intl.ListFormatOptions} [options] - Additional Intl.ListFormat options.
+	* @returns {Array<T | string>} The formatted list parts.
 	*
 	* @example
 	* gt.formatListToParts(['apple', 42, { foo: 'bar' }], { type: 'conjunction', style: 'short', locales: ['en'] });
@@ -1419,12 +1419,12 @@ var GT = class {
 	/**
 	* Formats a relative time value according to the specified locales and options.
 	*
-	* @param {number} value - The relative time value to format
+	* @param {number} value - The relative time value to format.
 	* @param {Intl.RelativeTimeFormatUnit} unit - The unit of time (e.g., 'second', 'minute', 'hour', 'day', 'week', 'month', 'year')
-	* @param {Object} options - Additional options for relative time formatting
-	* @param {string | string[]} [options.locales] - The locales to use for formatting
-	* @param {Intl.RelativeTimeFormatOptions} [options] - Additional Intl.RelativeTimeFormat options
-	* @returns {string} The formatted relative time string
+	* @param {Object} options - Additional options for relative time formatting.
+	* @param {string | string[]} [options.locales] - The locales to use for formatting.
+	* @param {Intl.RelativeTimeFormatOptions} [options] - Additional Intl.RelativeTimeFormat options.
+	* @returns {string} The formatted relative time string.
 	*
 	* @example
 	* gt.formatRelativeTime(-1, 'day', { locales: ['en-US'], numeric: 'auto' });
@@ -1436,9 +1436,9 @@ var GT = class {
 	/**
 	* Formats a relative time string from a Date, automatically selecting the best unit.
 	*
-	* @param {Date} date - The date to format relative to now
-	* @param {Object} [options] - Additional options for relative time formatting
-	* @param {string | string[]} [options.locales] - The locales to use for formatting
+	* @param {Date} date - The date to format relative to now.
+	* @param {Object} [options] - Additional options for relative time formatting.
+	* @param {string | string[]} [options.locales] - The locales to use for formatting.
 	* @returns {string} The formatted relative time string (e.g., "2 hours ago", "in 3 days")
 	*
 	* @example
@@ -1451,9 +1451,9 @@ var GT = class {
 	/**
 	* Retrieves the display name of a locale code using Intl.DisplayNames, returning an empty string if no name is found.
 	*
-	* @param {string} [locale=this.targetLocale] - A BCP-47 locale code
-	* @returns {string} The display name corresponding to the code
-	* @throws {Error} If no target locale is provided
+	* @param {string} [locale=this.targetLocale] - A BCP-47 locale code.
+	* @returns {string} The display name corresponding to the code.
+	* @throws {Error} If no target locale is provided.
 	*
 	* @example
 	* gt.getLocaleName('es-ES');
@@ -1468,8 +1468,8 @@ var GT = class {
 	* Uses the locale's region (if present) to select an emoji or falls back on default emojis.
 	*
 	* @param {string} [locale=this.targetLocale] - A BCP-47 locale code (e.g., 'en-US', 'fr-CA')
-	* @returns {string} The emoji representing the locale or its region
-	* @throws {Error} If no target locale is provided
+	* @returns {string} The emoji representing the locale or its region.
+	* @throws {Error} If no target locale is provided.
 	*
 	* @example
 	* gt.getLocaleEmoji('es-ES');
@@ -1573,12 +1573,12 @@ var GT = class {
 	/**
 	* Determines whether a translation is required based on the source and target locales.
 	*
-	* @param {string} [sourceLocale=this.sourceLocale] - The locale code for the original content
-	* @param {string} [targetLocale=this.targetLocale] - The locale code to translate into
-	* @param {string[]} [approvedLocales=this.locales] - Optional array of approved target locales
+	* @param {string} [sourceLocale=this.sourceLocale] - The locale code for the original content.
+	* @param {string} [targetLocale=this.targetLocale] - The locale code to translate into.
+	* @param {string[]} [approvedLocales=this.locales] - Optional array of approved target locales.
 	* @returns {boolean} True if translation is required, false otherwise
-	* @throws {Error} If no source locale is provided
-	* @throws {Error} If no target locale is provided
+	* @throws {Error} If no source locale is provided.
+	* @throws {Error} If no target locale is provided.
 	*
 	* @example
 	* gt.requiresTranslation('en-US', 'es-ES');
@@ -1593,9 +1593,9 @@ var GT = class {
 	/**
 	* Determines the best matching locale from the provided approved locales list.
 	*
-	* @param {string | string[]} locales - A single locale or array of locales in preference order
-	* @param {string[]} [approvedLocales=this.locales] - Array of approved locales in preference order
-	* @returns {string | undefined} The best matching locale or undefined if no match is found
+	* @param {string | string[]} locales - A single locale or array of locales in preference order.
+	* @param {string[]} [approvedLocales=this.locales] - Array of approved locales in preference order.
+	* @returns {string | undefined} The best matching locale, or undefined if no match is found.
 	*
 	* @example
 	* gt.determineLocale(['fr-CA', 'fr-FR'], ['en-US', 'fr-FR', 'es-ES']);
@@ -1608,9 +1608,9 @@ var GT = class {
 	/**
 	* Gets the text direction for a given locale code.
 	*
-	* @param {string} [locale=this.targetLocale] - A BCP-47 locale code
-	* @returns {'ltr' | 'rtl'} 'rtl' if the locale is right-to-left, otherwise 'ltr'
-	* @throws {Error} If no target locale is provided
+	* @param {string} [locale=this.targetLocale] - A BCP-47 locale code.
+	* @returns {'ltr' | 'rtl'} 'rtl' if the locale is right-to-left; otherwise 'ltr'.
+	* @throws {Error} If no target locale is provided.
 	*
 	* @example
 	* gt.getLocaleDirection('ar-SA');
@@ -1623,10 +1623,10 @@ var GT = class {
 	/**
 	* Checks if a given BCP 47 locale code is valid.
 	*
-	* @param {string} [locale=this.targetLocale] - The BCP 47 locale code to validate
-	* @param {customMapping} [customMapping=this.customMapping] - The custom mapping to use for validation
+	* @param {string} [locale=this.targetLocale] - The BCP 47 locale code to validate.
+	* @param {CustomMapping} [customMapping=this.customMapping] - The custom mapping to use for validation.
 	* @returns {boolean} True if the locale code is valid, false otherwise
-	* @throws {Error} If no target locale is provided
+	* @throws {Error} If no target locale is provided.
 	*
 	* @example
 	* gt.isValidLocale('en-US');
@@ -1641,7 +1641,7 @@ var GT = class {
 	* Resolves the canonical locale for a given locale.
 	* @param locale - The locale to resolve the canonical locale for
 	* @param customMapping - The custom mapping to use for resolving the canonical locale
-	* @returns The canonical locale
+	* @returns The canonical locale, or the input locale when no canonical mapping exists.
 	*/
 	resolveCanonicalLocale(locale = this.targetLocale, customMapping = this.customMapping) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("resolveCanonicalLocale"));
@@ -1652,7 +1652,7 @@ var GT = class {
 	* Resolves the alias locale for a given locale.
 	* @param locale - The locale to resolve the alias locale for
 	* @param customMapping - The custom mapping to use for resolving the alias locale
-	* @returns The alias locale
+	* @returns The configured alias for a canonical locale, or the input locale when already an alias or no alias mapping exists.
 	*/
 	resolveAliasLocale(locale, customMapping = this.customMapping) {
 		if (!locale) throw new Error(noTargetLocaleProvidedError("resolveAliasLocale"));
@@ -1662,9 +1662,9 @@ var GT = class {
 	/**
 	* Standardizes a BCP 47 locale code to ensure correct formatting.
 	*
-	* @param {string} [locale=this.targetLocale] - The BCP 47 locale code to standardize
-	* @returns {string} The standardized locale code or empty string if invalid
-	* @throws {Error} If no target locale is provided
+	* @param {string} [locale=this.targetLocale] - The BCP 47 locale code to standardize.
+	* @returns {string} The standardized locale code, or the input string if it cannot be standardized.
+	* @throws {Error} If no target locale is provided.
 	*
 	* @example
 	* gt.standardizeLocale('en_us');
@@ -1677,7 +1677,7 @@ var GT = class {
 	/**
 	* Checks if multiple BCP 47 locale codes represent the same dialect.
 	*
-	* @param {...(string | string[])} locales - The BCP 47 locale codes to compare
+	* @param {...(string | string[])} locales - The BCP 47 locale codes to compare.
 	* @returns {boolean} True if all codes represent the same dialect, false otherwise
 	*
 	* @example
@@ -1693,7 +1693,7 @@ var GT = class {
 	/**
 	* Checks if multiple BCP 47 locale codes represent the same language.
 	*
-	* @param {...(string | string[])} locales - The BCP 47 locale codes to compare
+	* @param {...(string | string[])} locales - The BCP 47 locale codes to compare.
 	* @returns {boolean} True if all codes represent the same language, false otherwise
 	*
 	* @example
@@ -1785,11 +1785,11 @@ function formatList(array, options) {
 }
 /**
 * Formats a list of items according to the specified locales and options.
-* @param {Array<T>} array - The list of items to format
-* @param {Object} [options] - Additional options for list formatting
-* @param {string | string[]} [options.locales] - The locales to use for formatting
-* @param {Intl.ListFormatOptions} [options] - Additional Intl.ListFormat options
-* @returns {Array<T | string>} The formatted list parts
+* @param {Array<T>} array - The list of items to format.
+* @param {Object} [options] - Additional options for list formatting.
+* @param {string | string[]} [options.locales] - The locales to use for formatting.
+* @param {Intl.ListFormatOptions} [options] - Additional Intl.ListFormat options.
+* @returns {Array<T | string>} The formatted list parts.
 */
 function formatListToParts(array, options) {
 	return require_core._formatListToParts({
@@ -1959,7 +1959,7 @@ function determineLocale(locales, approvedLocales = [], customMapping = void 0)
 * Get the text direction for a given locale code using the Intl.Locale API.
 *
 * @param {string} locale - A BCP-47 locale code.
-* @returns {string} - 'rtl' if the locale is right-to-left, otherwise 'ltr'.
+* @returns {string} 'rtl' if the locale is right-to-left; otherwise 'ltr'.
 */
 function getLocaleDirection(locale) {
 	return require_core._getLocaleDirection(locale);