generaltranslation 8.0.6 → 8.1.1

package/dist/index.d.ts

@@ -95,11 +95,13 @@ type ActionType = 'standard' | 'fast' | string;
  *
  * @param context - The context of the request.
  * @param id - The id of the request.
+ * @param maxChars - The maxChars of the request.
  * @param hash - The hash of the request.
  */
 type EntryMetadata = {
     context?: string;
     id?: string;
+    maxChars?: number;
     hash?: string;
     dataFormat?: DataFormat;
     sourceLocale?: string;
@@ -329,7 +331,7 @@ type SubmitUserEditDiff = {
     branchId: string;
     versionId: string;
     fileId: string;
-    localContent?: string;
+    localContent: string;
 };
 type SubmitUserEditDiffsPayload = {
     diffs: SubmitUserEditDiff[];
@@ -409,6 +411,23 @@ type CreateBranchResult = {
     };
 };
 
+/** Type of terminator */
+type CutoffFormatStyle = 'none' | 'ellipsis';
+/** Terminator options */
+interface TerminatorOptions {
+    /** The terminator to use */
+    terminator?: string;
+    /** An optional separator between the terminator and the value */
+    separator?: string;
+}
+/** Input formatting options (for constructor) */
+interface CutoffFormatOptions extends TerminatorOptions {
+    /** Cutoff length */
+    maxChars?: number;
+    /** Type of terminator */
+    style?: CutoffFormatStyle;
+}
+
 /**
  * Type representing the constructor parameters for the GT class.
  * @typedef {Object} GTConstructorParams
@@ -761,6 +780,38 @@ declare class GT {
         source: FileUpload;
         translations: FileUpload[];
     }[], options: UploadFilesOptions): Promise<UploadFilesResponse>;
+    /**
+     * Formats a string with cutoff behavior, applying a terminator when the string exceeds the maximum character limit.
+     *
+     * This method uses the GT instance's rendering locales by default for locale-specific terminator selection,
+     * but can be overridden with custom locales in the options.
+     *
+     * @param {string} value - The string value to format with cutoff behavior.
+     * @param {Object} [options] - Configuration options for cutoff formatting.
+     * @param {string | string[]} [options.locales] - The locales to use for terminator selection. Defaults to instance's rendering locales.
+     * @param {number} [options.maxChars] - The maximum number of characters to display.
+     * - Undefined values are treated as no cutoff.
+     * - Negative values follow .slice() behavior and terminator will be added before the value.
+     * - 0 will result in an empty string.
+     * - If cutoff results in an empty string, no terminator is added.
+     * @param {CutoffFormatStyle} [options.style='ellipsis'] - The style of the terminator.
+     * @param {string} [options.terminator] - Optional override the terminator to use.
+     * @param {string} [options.separator] - Optional override the separator to use between the terminator and the value.
+     * - If no terminator is provided, then separator is ignored.
+     * @returns {string} The formatted string with terminator applied if cutoff occurs.
+     *
+     * @example
+     * const gt = new GT({ targetLocale: 'en-US' });
+     * gt.formatCutoff('Hello, world!', { maxChars: 8 });
+     * // Returns: 'Hello, w...'
+     *
+     * @example
+     * gt.formatCutoff('Hello, world!', { maxChars: -3 });
+     * // Returns: '...ld!'
+     */
+    formatCutoff(value: string, options?: {
+        locales?: string | string[];
+    } & CutoffFormatOptions): string;
     /**
      * Formats a message according to the specified locales and options.
      *
@@ -1096,6 +1147,46 @@ declare class GT {
      */
     isSupersetLocale(superLocale: string, subLocale: string): boolean;
 }
+/**
+ * Formats a string with cutoff behavior, applying a terminator when the string exceeds the maximum character limit.
+ *
+ * This standalone function provides cutoff formatting functionality without requiring a GT instance.
+ * The locales parameter is required for proper terminator selection based on the target language.
+ *
+ * @param {string} value - The string value to format with cutoff behavior.
+ * @param {Object} [options] - Configuration options for cutoff formatting.
+ * @param {string | string[]} [options.locales] - The locales to use for terminator selection.
+ * @param {number} [options.maxChars] - The maximum number of characters to display.
+ * - Undefined values are treated as no cutoff.
+ * - Negative values follow .slice() behavior and terminator will be added before the value.
+ * - 0 will result in an empty string.
+ * - If cutoff results in an empty string, no terminator is added.
+ * @param {CutoffFormatStyle} [options.style='ellipsis'] - The style of the terminator.
+ * @param {string} [options.terminator] - Optional override the terminator to use.
+ * @param {string} [options.separator] - Optional override the separator to use between the terminator and the value.
+ * - If no terminator is provided, then separator is ignored.
+ * @returns {string} The formatted string with terminator applied if cutoff occurs.
+ *
+ * @example
+ * formatCutoff('Hello, world!', { locales: 'en-US', maxChars: 8 });
+ * // Returns: 'Hello, w...'
+ *
+ * @example
+ * formatCutoff('Hello, world!', { locales: 'en-US', maxChars: -3 });
+ * // Returns: '...ld!'
+ *
+ * @example
+ * formatCutoff('Very long text that needs cutting', {
+ *   locales: 'en-US',
+ *   maxChars: 15,
+ *   style: 'ellipsis',
+ *   separator: ' '
+ * });
+ * // Returns: 'Very long text ...'
+ */
+declare function formatCutoff(value: string, options?: {
+    locales?: string | string[];
+} & CutoffFormatOptions): string;
 /**
  * Formats a message according to the specified locales and options.
  *
@@ -1347,4 +1438,4 @@ declare function isSameLanguage(...locales: (string | string[])[]): boolean;
  */
 declare function isSupersetLocale(superLocale: string, subLocale: string): boolean;
 
-export { GT, determineLocale, formatCurrency, formatDateTime, formatList, formatListToParts, formatMessage, formatNum, formatRelativeTime, getLocaleDirection, getLocaleEmoji, getLocaleName, getLocaleProperties, getRegionProperties, isSameDialect, isSameLanguage, isSupersetLocale, isValidLocale, requiresTranslation, resolveAliasLocale, standardizeLocale };
+export { GT, determineLocale, formatCurrency, formatCutoff, formatDateTime, formatList, formatListToParts, formatMessage, formatNum, formatRelativeTime, getLocaleDirection, getLocaleEmoji, getLocaleName, getLocaleProperties, getRegionProperties, isSameDialect, isSameLanguage, isSupersetLocale, isValidLocale, requiresTranslation, resolveAliasLocale, standardizeLocale };