generaltranslation 7.1.6 → 7.2.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { LocaleProperties } from './locales/getLocaleProperties';
 import { JsxChildren } from './internal';
 import { FileTranslationQuery } from './types-dir/checkFileTranslations';
 import { CheckTranslationStatusOptions, TranslationStatusResult } from './types-dir/translationStatus';
+import { CustomRegionMapping } from './locales/getRegionProperties';
 /**
  * Type representing the constructor parameters for the GT class.
  * @typedef {Object} GTConstructorParams
@@ -58,6 +59,8 @@ export declare class GT {
     _renderingLocales: string[];
     /** Custom mapping for locale codes to their names */
     customMapping?: CustomMapping;
+    /** Lazily derived custom mapping for regions */
+    customRegionMapping?: CustomRegionMapping;
     /**
      * Constructs an instance of the GT class.
      *
@@ -406,7 +409,7 @@ export declare class GT {
         locales?: string | string[];
     } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>): string;
     /**
-     * Retrieves the display name of a locale code using Intl.DisplayNames.
+     * 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
@@ -463,6 +466,48 @@ export declare class GT {
      * @property {string} emoji - The emoji associated with the locale's region, if applicable.
      */
     getLocaleProperties(locale?: string | undefined): LocaleProperties;
+    /**
+     * Retrieves multiple properties for a given region code, including:
+     * - `code`: the original region code
+     * - `name`: the localized display name
+     * - `emoji`: the associated flag or symbol
+     *
+     * Behavior:
+     * - Accepts ISO 3166-1 alpha-2 or UN M.49 region codes (e.g., `"US"`, `"FR"`, `"419"`).
+     * - Uses the instance's `targetLocale` to localize the region name for the user.
+     * - If `customMapping` contains a `name` or `emoji` for the region, those override the default values.
+     * - Otherwise, uses `Intl.DisplayNames` to get the localized region name, falling back to `libraryDefaultLocale`.
+     * - Falls back to the region code as `name` if display name resolution fails.
+     * - Falls back to a default emoji if no emoji mapping is found in built-in data or `customMapping`.
+     *
+     * @param {string} [region=this.getLocaleProperties().regionCode] - The region code to look up (e.g., `"US"`, `"GB"`, `"DE"`).
+     * @param {CustomRegionMapping} [customMapping] - Optional mapping of region codes to custom names and/or emojis.
+     * @returns {{ code: string, name: string, emoji: string }} An object containing:
+     *  - `code`: the input region code
+     *  - `name`: the localized or custom region name
+     *  - `emoji`: the matching emoji flag or symbol
+     *
+     * @throws {Error} If no target locale is available to determine region properties.
+     *
+     * @example
+     * const gt = new GT({ targetLocale: 'en-US' });
+     * gt.getRegionProperties('US');
+     * // => { code: 'US', name: 'United States', emoji: '🇺🇸' }
+     *
+     * @example
+     * const gt = new GT({ targetLocale: 'fr-FR' });
+     * gt.getRegionProperties('US');
+     * // => { code: 'US', name: 'États-Unis', emoji: '🇺🇸' }
+     *
+     * @example
+     * gt.getRegionProperties('US', { US: { name: 'USA', emoji: '🗽' } });
+     * // => { code: 'US', name: 'USA', emoji: '🗽' }
+     */
+    getRegionProperties(region?: string, customMapping?: CustomRegionMapping): {
+        code: string;
+        name: string;
+        emoji: string;
+    };
     /**
      * Determines whether a translation is required based on the source and target locales.
      *