generaltranslation 8.2.11 → 8.2.13

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { a as standardizeLocale, c as CutoffFormatOptions, i as resolveCanonicalLocale, n as formatMessage, o as LocaleConfig, r as isValidLocale, s as LocaleConfigConstructorParams, t as formatCutoff } from "./core-BYVWty_t.mjs";
-import { $ as FileReference, A as BranchDataResult, B as FileUpload, C as ProcessMovesOptions, D as FileDataQuery, F as DownloadFileOptions, H as UploadFilesResponse, I as PublishFileEntry, J as DownloadFileBatchOptions, L as PublishFilesResult, M as TranslationError, Mt as LocaleProperties, N as TranslationResult, Nt as CustomMapping, O as FileDataResult, Ot as StringFormat, T as GetOrphanedFilesResult, U as CreateTagOptions, V as UploadFilesOptions, W as CreateTagResult, X as DownloadFileBatchResult, Y as DownloadFileBatchRequest, _ as AwaitJobsResult, at as CheckFileTranslationsOptions, et as FileReferenceIds, g as AwaitJobsOptions, h as SubmitUserEditDiffsPayload, ht as TranslateOptions, j as TranslateManyResult, k as BranchQuery, mt as TranslateManyEntry, n as FormatVariables, ot as FileQuery, rt as EnqueueFilesResult, st as FileQueryResult, w as ProcessMovesResponse, x as MoveMapping, y as CheckJobStatusResult } from "./types-Cy8q2XZX.mjs";
+import { a as standardizeLocale, c as CutoffFormatOptions, i as resolveCanonicalLocale, n as formatMessage, o as LocaleConfig, r as isValidLocale, s as LocaleConfigConstructorParams, t as formatCutoff } from "./core-I9pWGafA.mjs";
+import { $ as FileReference, A as BranchDataResult, B as FileUpload, C as ProcessMovesOptions, D as FileDataQuery, F as DownloadFileOptions, Ft as LocaleProperties, H as UploadFilesResponse, I as PublishFileEntry, It as CustomMapping, J as DownloadFileBatchOptions, L as PublishFilesResult, M as TranslationError, N as TranslationResult, O as FileDataResult, T as GetOrphanedFilesResult, U as CreateTagOptions, V as UploadFilesOptions, W as CreateTagResult, X as DownloadFileBatchResult, Y as DownloadFileBatchRequest, _ as AwaitJobsResult, _t as TranslateManyEntry, at as CheckFileTranslationsOptions, et as FileReferenceIds, g as AwaitJobsOptions, h as SubmitUserEditDiffsPayload, j as TranslateManyResult, jt as StringFormat, k as BranchQuery, n as FormatVariables, ot as FileQuery, rt as EnqueueFilesResult, st as FileQueryResult, vt as TranslateOptions, w as ProcessMovesResponse, x as MoveMapping, y as CheckJobStatusResult } from "./types-AHtYZIP-.mjs";
 
 //#region src/translate/setupProject.d.ts
 type SetupProjectResult = {
@@ -148,14 +148,14 @@ declare class GT {
    * 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.
    */
   queryBranchData(query: BranchQuery): Promise<BranchDataResult>;
   /**
    * 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.
    */
   createBranch(query: CreateBranchQuery): Promise<CreateBranchResult>;
   /**
@@ -164,7 +164,7 @@ declare class GT {
    *
    * @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([
@@ -177,10 +177,10 @@ declare class GT {
    * 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']);
@@ -197,7 +197,7 @@ declare class GT {
    * 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
    */
   setupProject(files: FileReference[], options?: SetupProjectOptions): Promise<SetupProjectResult>;
@@ -207,9 +207,9 @@ declare class GT {
    * 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([
@@ -223,9 +223,9 @@ declare class GT {
   /**
    * 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.
    */
   awaitJobs(enqueueResult: EnqueueFilesResult, options?: AwaitJobsOptions): Promise<AwaitJobsResult>;
   /**
@@ -238,8 +238,8 @@ declare class GT {
    * 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.
    */
   enqueueFiles(files: FileReferenceIds[], options: EnqueueOptions): Promise<EnqueueFilesResult>;
   /**
@@ -247,7 +247,7 @@ declare class GT {
    * 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.
    */
   createTag(options: CreateTagOptions): Promise<CreateTagResult>;
   /**
@@ -416,8 +416,8 @@ declare class GT {
    * 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.
    */
   uploadSourceFiles(files: {
     source: FileUpload;
@@ -431,10 +431,10 @@ declare class GT {
    * 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.
    */
   uploadTranslations(files: {
     source: FileUpload;
@@ -496,11 +496,11 @@ declare class GT {
   /**
    * 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' });
@@ -512,11 +512,11 @@ declare class GT {
   /**
    * 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' });
@@ -528,12 +528,12 @@ declare class GT {
   /**
    * 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' });
@@ -545,11 +545,11 @@ declare class GT {
   /**
    * 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' });
@@ -560,11 +560,11 @@ declare class GT {
   } & Intl.ListFormatOptions): string;
   /**
    * 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'] });
@@ -576,12 +576,12 @@ declare class GT {
   /**
    * 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' });
@@ -593,9 +593,9 @@ declare class GT {
   /**
    * 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
@@ -609,9 +609,9 @@ declare class GT {
   /**
    * 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');
@@ -623,8 +623,8 @@ declare class GT {
    * 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');
@@ -709,12 +709,12 @@ declare class GT {
   /**
    * 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');
@@ -724,9 +724,9 @@ declare class GT {
   /**
    * 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']);
@@ -736,9 +736,9 @@ declare class GT {
   /**
    * 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');
@@ -748,10 +748,10 @@ declare class GT {
   /**
    * 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');
@@ -762,22 +762,22 @@ declare class GT {
    * 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?: string | undefined, customMapping?: CustomMapping | undefined): string;
   /**
    * 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: string, customMapping?: CustomMapping | undefined): string;
   /**
    * 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');
@@ -787,7 +787,7 @@ declare class GT {
   /**
    * 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
@@ -801,7 +801,7 @@ declare class GT {
   /**
    * 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
@@ -872,11 +872,11 @@ declare function formatList(array: Array<string | number>, options: {
 } & Intl.ListFormatOptions): string;
 /**
  * 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.
  */
 declare function formatListToParts<T>(array: Array<T>, options?: {
   locales?: string | string[];
@@ -1024,7 +1024,7 @@ declare function determineLocale(locales: string | string[], approvedLocales?: s
  * 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'.
  */
 declare function getLocaleDirection(locale: string): 'ltr' | 'rtl';
 /**