generaltranslation 9.4.2 → 9.5.0

package/dist/runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.cjs","names":["invalidLocaleError","invalidLocalesError","LocaleConfig","translateWithConfig","translateManyWithConfig","noTargetLocaleProvidedError","noSourceLocaleProvidedError"],"sources":["../src/runtime.ts"],"sourcesContent":["// `generaltranslation` language toolkit\n// © 2026, General Translation, Inc.\n\n// ----- IMPORTS ----- //\n\nimport {\n  LocaleConfig,\n  getRegionProperties as _getRegionProperties,\n  isValidLocale as _isValidLocale,\n  requiresTranslation as _requiresTranslation,\n  resolveAliasLocale as _resolveAliasLocale,\n  resolveCanonicalLocale as _resolveCanonicalLocale,\n  standardizeLocale as _standardizeLocale,\n} from '@generaltranslation/format';\nimport type {\n  CustomMapping,\n  CustomRegionMapping,\n  CutoffFormatOptions,\n  FormatVariables,\n  LocaleProperties,\n  StringFormat,\n} from '@generaltranslation/format/types';\nimport type { UserTokenProvider } from '@generaltranslation/api';\nimport {\n  TranslateManyResult,\n  TranslationError,\n  TranslationRequestConfig,\n  TranslationResult,\n  TranslateManyEntry,\n} from './types';\nimport {\n  noSourceLocaleProvidedError,\n  noTargetLocaleProvidedError,\n  invalidLocaleError,\n  invalidLocalesError,\n} from './logging/errors';\nimport {\n  translate as translateWithConfig,\n  translateMany as translateManyWithConfig,\n} from './translate/runtimeTranslate';\nimport { TranslateOptions } from './types-dir/api/entry';\n\n// ============================================================ //\n//                       Runtime Class                          //\n// ============================================================ //\n/**\n * Type representing the constructor parameters for the GT and GTRuntime classes.\n * @typedef {Object} GTConstructorParams\n * @property {string} [apiKey] - The API key for accessing the translation service\n * @property {string} [devApiKey] - Deprecated alias for apiKey\n * @property {string} [sourceLocale] - The default source locale for translations\n * @property {string} [targetLocale] - The default target locale for translations\n * @property {string[]} [locales] - Array of supported locales\n * @property {string} [projectId] - The project ID for the translation service\n * @property {string} [baseUrl] - The base URL for the translation service\n * @property {CustomMapping} [customMapping] - Custom mapping of locale codes to their names\n */\nexport type GTConstructorParams = {\n  apiKey?: string;\n  /** @deprecated Pass the key as `apiKey`; there is one kind of API key. */\n  devApiKey?: string;\n  sourceLocale?: string;\n  targetLocale?: string;\n  locales?: string[];\n  projectId?: string;\n  baseUrl?: string;\n  customMapping?: CustomMapping;\n  userTokenProvider?: UserTokenProvider;\n};\n\n/**\n * GTRuntime is the runtime core of the GT driver: locale management,\n * formatting, and runtime translation requests.\n *\n * Browser-facing SDK code constructs this class (via `generaltranslation/runtime`)\n * so production bundles do not ship the project/file management API client\n * that lives on the GT class exported from the main entry.\n *\n * @example\n * const gt = new GTRuntime({\n *   sourceLocale: 'en-US',\n *   targetLocale: 'es-ES',\n *   locales: ['en-US', 'es-ES', 'fr-FR']\n * });\n */\nexport class GTRuntime {\n  /** Base URL for the translation service API */\n  baseUrl?: string;\n\n  /** Project ID for the translation service */\n  projectId?: string;\n\n  /** API key for accessing the translation service */\n  apiKey?: string;\n\n  /** @deprecated Pass the key as `apiKey`; there is one kind of API key. */\n  devApiKey?: string;\n\n  /** User-token provider used when no API key is configured */\n  userTokenProvider?: UserTokenProvider;\n\n  /** Source locale for translations */\n  sourceLocale?: string;\n\n  /** Target locale for translations */\n  targetLocale?: string;\n\n  /** Array of supported locales */\n  locales?: string[];\n\n  /** Custom mapping for locale codes to their names */\n  customMapping?: CustomMapping;\n\n  /** Lazily derived reverse custom mapping for alias locales */\n  reverseCustomMapping?: Record<string, string>;\n\n  /** Lazily derived custom mapping for regions */\n  customRegionMapping?: CustomRegionMapping;\n\n  /** Runtime-safe locale and formatting helpers (backing field) */\n  private _localeConfig!: LocaleConfig;\n\n  /** Runtime-safe locale and formatting helpers */\n  get localeConfig() {\n    return this._localeConfig;\n  }\n\n  /**\n   * Constructs an instance of the GTRuntime class.\n   *\n   * @param {GTConstructorParams} [params] - The parameters for initializing the GTRuntime instance\n   * @throws {Error} If an invalid locale is provided\n   * @throws {Error} If any of the provided locales are invalid\n   *\n   * @example\n   * const gt = new GTRuntime({\n   *   apiKey: 'your-api-key',\n   *   sourceLocale: 'en-US',\n   *   targetLocale: 'es-ES',\n   *   locales: ['en-US', 'es-ES', 'fr-FR']\n   * });\n   */\n  constructor(params: GTConstructorParams = {}) {\n    // Read environment\n    if (typeof process !== 'undefined') {\n      this.apiKey ||= process.env?.GT_API_KEY;\n      // Deprecated with devApiKey; frameworks resolve the hot-reload key themselves.\n      this.devApiKey ||= process.env?.GT_DEV_API_KEY;\n      this.projectId ||= process.env?.GT_PROJECT_ID;\n    }\n    // Set up config\n    this.setConfig(params);\n  }\n\n  setConfig({\n    apiKey,\n    devApiKey,\n    sourceLocale,\n    targetLocale,\n    locales,\n    projectId,\n    customMapping,\n    baseUrl,\n    userTokenProvider,\n  }: GTConstructorParams) {\n    const effectiveCustomMapping = customMapping ?? this.customMapping;\n\n    // ----- Environment properties ----- //\n    if (apiKey) this.apiKey = apiKey;\n    if (devApiKey) this.devApiKey = devApiKey;\n    if (projectId) this.projectId = projectId;\n    if (userTokenProvider) this.userTokenProvider = userTokenProvider;\n\n    // ----- Validate configured locale identities ----- //\n\n    // source locale\n    if (sourceLocale) {\n      this.sourceLocale = sourceLocale;\n      if (!_isValidLocale(this.sourceLocale, effectiveCustomMapping))\n        throw new Error(invalidLocaleError(this.sourceLocale));\n    }\n\n    // target locale\n    if (targetLocale) {\n      this.targetLocale = targetLocale;\n      if (!_isValidLocale(this.targetLocale, effectiveCustomMapping))\n        throw new Error(invalidLocaleError(this.targetLocale));\n    }\n\n    // locales\n    if (locales) {\n      const result: string[] = [];\n      const invalidLocales: string[] = [];\n      locales.forEach((locale) => {\n        if (_isValidLocale(locale, effectiveCustomMapping)) {\n          result.push(locale);\n        } else {\n          invalidLocales.push(locale);\n        }\n      });\n      if (invalidLocales.length > 0) {\n        throw new Error(invalidLocalesError(invalidLocales));\n      }\n      this.locales = result;\n    }\n\n    // ----- Other properties ----- //\n    if (baseUrl) this.baseUrl = baseUrl;\n    if (customMapping) {\n      this.customMapping = customMapping;\n      this.reverseCustomMapping = Object.fromEntries(\n        Object.entries(customMapping)\n          .filter(\n            ([, value]) => value && typeof value === 'object' && 'code' in value\n          )\n          .map(([key, value]) => [(value as { code: string }).code, key])\n      );\n    }\n    this._localeConfig = new LocaleConfig({\n      defaultLocale: this.sourceLocale,\n      locales: this.locales ?? [],\n      customMapping: this.customMapping,\n    });\n  }\n\n  // -------------- Private Methods -------------- //\n\n  /** Convert app identity only where a GT service expects a language code. */\n  protected resolveServiceLocale(locale: string): string {\n    return this.standardizeLocale(this.resolveCanonicalLocale(locale));\n  }\n\n  /**\n   * Recover configured spelling without negotiating an unrelated dialect.\n   * When several identities use the same service code and there is no request\n   * context to disambiguate them, the first configured identity wins.\n   */\n  protected resolveServiceResponseLocale(locale: string): string {\n    const canonical = this.standardizeLocale(locale);\n    const configured = [\n      ...(this.locales ?? []),\n      this.sourceLocale,\n      this.targetLocale,\n      ...Object.keys(this.customMapping ?? {}),\n    ];\n    return (\n      configured.find(\n        (candidate) =>\n          candidate && this.resolveServiceLocale(candidate) === canonical\n      ) ?? locale\n    );\n  }\n\n  protected _getTranslationConfig(): TranslationRequestConfig {\n    return {\n      baseUrl: this.baseUrl,\n      apiKey: this.apiKey || this.devApiKey,\n      projectId: this.projectId || '',\n      userTokenProvider: this.userTokenProvider,\n    };\n  }\n\n  /**\n   * Translates a single source string to the target locale.\n   * Routes through {@link translateMany} under the hood.\n   *\n   * @param {string} source - The source string to translate.\n   * @param {object} options - Translation options including targetLocale and optional entry metadata.\n   * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.\n   * @returns {Promise<TranslationResult | TranslationError>} The translated content.\n   *\n   * @example\n   * const result = await gt.translate('Hello, world!', { targetLocale: 'es' });\n   *\n   * @example\n   * const result = await gt.translate('Hello, world!', {\n   *   targetLocale: 'es',\n   *   dataFormat: 'ICU',\n   *   context: 'A formal greeting',\n   * });\n   */\n  async translate(\n    source: TranslateManyEntry,\n    options: string | TranslateOptions,\n    timeout?: number\n  ): Promise<TranslationResult | TranslationError> {\n    return translateWithConfig(\n      source,\n      options,\n      {\n        ...this._getTranslationConfig(),\n        customMapping: this.customMapping,\n        timeoutMs: timeout || undefined,\n      },\n      this\n    );\n  }\n\n  /**\n   * Translates multiple source strings to the target locale.\n   * Each entry can be a plain string or an object with source and metadata fields.\n   *\n   * @param {TranslateManyEntry[] | Record<string, TranslateManyEntry>} sources - The source entries to translate. Can be an array or a record keyed by hash.\n   * @param {object} options - Translation options including targetLocale.\n   * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.\n   * @returns {Promise<TranslateManyResult | Record<string, TranslationResult>>} The translated contents. An array if sources was an array, a record if sources was a record.\n   *\n   * @example\n   * const result = await gt.translateMany(\n   *   ['Hello, world!', 'Goodbye, world!'],\n   *   { targetLocale: 'es' }\n   * );\n   *\n   * @example\n   * const result = await gt.translateMany(\n   *   [{ source: 'Hello, world!', dataFormat: 'ICU' }],\n   *   { targetLocale: 'es' }\n   * );\n   *\n   * @example\n   * const result = await gt.translateMany(\n   *   { 'my-hash': 'Hello, world!' },\n   *   { targetLocale: 'es' }\n   * );\n   */\n  async translateMany(\n    sources: TranslateManyEntry[],\n    options: string | TranslateOptions,\n    timeout?: number\n  ): Promise<TranslateManyResult>;\n  async translateMany(\n    sources: Record<string, TranslateManyEntry>,\n    options: string | TranslateOptions,\n    timeout?: number\n  ): Promise<Record<string, TranslationResult>>;\n  async translateMany(\n    sources: TranslateManyEntry[] | Record<string, TranslateManyEntry>,\n    options: string | TranslateOptions,\n    timeout?: number\n  ): Promise<TranslateManyResult | Record<string, TranslationResult>> {\n    return translateManyWithConfig(\n      sources,\n      options,\n      {\n        ...this._getTranslationConfig(),\n        customMapping: this.customMapping,\n        timeoutMs: timeout || undefined,\n      },\n      this\n    );\n  }\n\n  // -------------- Formatting -------------- //\n\n  /**\n   * Formats a string with cutoff behavior, applying a terminator when the string exceeds the maximum character limit.\n   *\n   * This method uses the GT instance's rendering locales by default for locale-specific terminator selection,\n   * but can be overridden with custom locales in the options.\n   *\n   * @param {string} value - The string value to format with cutoff behavior.\n   * @param {Object} [options] - Configuration options for cutoff formatting.\n   * @param {string | string[]} [options.locales] - The locales to use for terminator selection. Defaults to instance's rendering locales.\n   * @param {number} [options.maxChars] - The maximum number of characters to display.\n   * - Undefined values are treated as no cutoff.\n   * - Negative values follow .slice() behavior and terminator will be added before the value.\n   * - 0 will result in an empty string.\n   * - If cutoff results in an empty string, no terminator is added.\n   * @param {CutoffFormatStyle} [options.style='ellipsis'] - The style of the terminator.\n   * @param {string} [options.terminator] - Optional override the terminator to use.\n   * @param {string} [options.separator] - Optional override the separator to use between the terminator and the value.\n   * - If no terminator is provided, then separator is ignored.\n   * @returns {string} The formatted string with terminator applied if cutoff occurs.\n   *\n   * @example\n   * const gt = new GTRuntime({ targetLocale: 'en-US' });\n   * gt.formatCutoff('Hello, world!', { maxChars: 8 });\n   * // Returns: 'Hello, w...'\n   *\n   * @example\n   * gt.formatCutoff('Hello, world!', { maxChars: -3 });\n   * // Returns: '...ld!'\n   */\n  formatCutoff(\n    value: string,\n    options?: {\n      locales?: string | string[];\n    } & CutoffFormatOptions\n  ): string {\n    return this.localeConfig.formatCutoff(value, this.targetLocale, options);\n  }\n\n  /**\n   * Formats a message according to the specified locales and options.\n   *\n   * @param {string} message - The message to format.\n   * @param {string | string[]} [locales=libraryDefaultLocale] - The locales to use for formatting.\n   * @param {FormatVariables} [variables={}] - The variables to use for formatting.\n   * @param {StringFormat} [dataFormat='ICU'] - The format of the message.\n   * @returns {string} The formatted message.\n   *\n   * @example\n   * gt.formatMessage('Hello {name}', { name: 'John' });\n   * // Returns: \"Hello John\"\n   *\n   * gt.formatMessage('Hello {name}', { name: 'John' }, { locales: ['fr'] });\n   * // Returns: \"Bonjour John\"\n   */\n  formatMessage(\n    message: string,\n    options?: {\n      locales?: string | string[];\n      variables?: FormatVariables;\n      dataFormat?: StringFormat;\n    }\n  ): string {\n    return this.localeConfig.formatMessage(message, this.targetLocale, options);\n  }\n  /**\n   * Formats a number according to the specified locales and options.\n   *\n   * @param {number} number - The number to format.\n   * @param {Object} [options] - Additional options for number formatting.\n   * @param {string | string[]} [options.locales] - The locales to use for formatting.\n   * @param {Intl.NumberFormatOptions} [options] - Additional Intl.NumberFormat options.\n   * @returns {string} The formatted number.\n   *\n   * @example\n   * gt.formatNum(1234.56, { style: 'currency', currency: 'USD' });\n   * // Returns: \"$1,234.56\"\n   */\n  formatNum(\n    number: number,\n    options?: {\n      locales?: string | string[];\n    } & Intl.NumberFormatOptions\n  ): string {\n    return this.localeConfig.formatNum(number, this.targetLocale, options);\n  }\n\n  /**\n   * Formats a date according to the specified locales and options.\n   *\n   * @param {Date} date - The date to format.\n   * @param {Object} [options] - Additional options for date formatting.\n   * @param {string | string[]} [options.locales] - The locales to use for formatting.\n   * @param {Intl.DateTimeFormatOptions} [options] - Additional Intl.DateTimeFormat options.\n   * @returns {string} The formatted date.\n   *\n   * @example\n   * gt.formatDateTime(new Date(), { dateStyle: 'full', timeStyle: 'long' });\n   * // Returns: \"Thursday, March 14, 2024 at 2:30:45 PM GMT-7\"\n   */\n  formatDateTime(\n    date: Date,\n    options?: {\n      locales?: string | string[];\n    } & Intl.DateTimeFormatOptions\n  ): string {\n    return this.localeConfig.formatDateTime(date, this.targetLocale, options);\n  }\n\n  /**\n   * Formats a currency value according to the specified locales and options.\n   *\n   * @param {number} value - The currency value to format.\n   * @param {string} currency - The currency code (e.g., 'USD', 'EUR')\n   * @param {Object} [options] - Additional options for currency formatting.\n   * @param {string | string[]} [options.locales] - The locales to use for formatting.\n   * @param {Intl.NumberFormatOptions} [options] - Additional Intl.NumberFormat options.\n   * @returns {string} The formatted currency value.\n   *\n   * @example\n   * gt.formatCurrency(1234.56, 'USD', { style: 'currency' });\n   * // Returns: \"$1,234.56\"\n   */\n  formatCurrency(\n    value: number,\n    currency: string,\n    options?: {\n      locales?: string | string[];\n    } & Intl.NumberFormatOptions\n  ): string {\n    return this.localeConfig.formatCurrency(\n      value,\n      currency,\n      this.targetLocale,\n      options\n    );\n  }\n\n  /**\n   * Formats a list of items according to the specified locales and options.\n   *\n   * @param {Array<string | number>} array - The list of items to format.\n   * @param {Object} [options] - Additional options for list formatting.\n   * @param {string | string[]} [options.locales] - The locales to use for formatting.\n   * @param {Intl.ListFormatOptions} [options] - Additional Intl.ListFormat options.\n   * @returns {string} The formatted list.\n   *\n   * @example\n   * gt.formatList(['apple', 'banana', 'orange'], { type: 'conjunction' });\n   * // Returns: \"apple, banana, and orange\"\n   */\n  formatList(\n    array: Array<string | number>,\n    options?: {\n      locales?: string | string[];\n    } & Intl.ListFormatOptions\n  ) {\n    return this.localeConfig.formatList(array, this.targetLocale, options);\n  }\n\n  /**\n   * Formats a list of items according to the specified locales and options.\n   * @param {Array<T>} array - The list of items to format.\n   * @param {Object} [options] - Additional options for list formatting.\n   * @param {string | string[]} [options.locales] - The locales to use for formatting.\n   * @param {Intl.ListFormatOptions} [options] - Additional Intl.ListFormat options.\n   * @returns {Array<T | string>} The formatted list parts.\n   *\n   * @example\n   * gt.formatListToParts(['apple', 42, { foo: 'bar' }], { type: 'conjunction', style: 'short', locales: ['en'] });\n   * // Returns: ['apple', ', ', 42, ' and ', '{ foo: \"bar\" }']\n   */\n  formatListToParts<T>(\n    array: Array<T>,\n    options?: {\n      locales?: string | string[];\n    } & Intl.ListFormatOptions\n  ): Array<T | string> {\n    return this.localeConfig.formatListToParts<T>(\n      array,\n      this.targetLocale,\n      options\n    );\n  }\n\n  /**\n   * Formats a relative time value according to the specified locales and options.\n   *\n   * @param {number} value - The relative time value to format.\n   * @param {Intl.RelativeTimeFormatUnit} unit - The unit of time (e.g., 'second', 'minute', 'hour', 'day', 'week', 'month', 'year')\n   * @param {Object} options - Additional options for relative time formatting.\n   * @param {string | string[]} [options.locales] - The locales to use for formatting.\n   * @param {Intl.RelativeTimeFormatOptions} [options] - Additional Intl.RelativeTimeFormat options.\n   * @returns {string} The formatted relative time string.\n   *\n   * @example\n   * gt.formatRelativeTime(-1, 'day', { locales: ['en-US'], numeric: 'auto' });\n   * // Returns: \"yesterday\"\n   */\n  formatRelativeTime(\n    value: number,\n    unit: Intl.RelativeTimeFormatUnit,\n    options?: {\n      locales?: string | string[];\n    } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>\n  ): string {\n    return this.localeConfig.formatRelativeTime(\n      value,\n      unit,\n      this.targetLocale,\n      options\n    );\n  }\n\n  /**\n   * Formats a relative time string from a Date, automatically selecting the best unit.\n   *\n   * @param {Date} date - The date to format relative to now.\n   * @param {Object} [options] - Additional options for relative time formatting.\n   * @param {string | string[]} [options.locales] - The locales to use for formatting.\n   * @returns {string} The formatted relative time string (e.g., \"2 hours ago\", \"in 3 days\")\n   *\n   * @example\n   * gt.formatRelativeTimeFromDate(new Date(Date.now() - 3600000));\n   * // Returns: \"1 hour ago\"\n   */\n  formatRelativeTimeFromDate(\n    date: Date,\n    options?: {\n      locales?: string | string[];\n      baseDate?: Date;\n    } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>\n  ): string {\n    return this.localeConfig.formatRelativeTimeFromDate(\n      date,\n      this.targetLocale,\n      options\n    );\n  }\n\n  // -------------- Locale Properties -------------- //\n\n  /**\n   * Retrieves the display name of a locale code using Intl.DisplayNames, returning an empty string if no name is found.\n   *\n   * @param {string} [locale=this.targetLocale] - A BCP-47 locale code.\n   * @returns {string} The display name corresponding to the code.\n   * @throws {Error} If no target locale is provided.\n   *\n   * @example\n   * gt.getLocaleName('es-ES');\n   * // Returns: \"Spanish (Spain)\"\n   */\n  getLocaleName(locale = this.targetLocale): string {\n    if (!locale) throw new Error(noTargetLocaleProvidedError('getLocaleName'));\n    return this.localeConfig.getLocaleName(locale);\n  }\n\n  /**\n   * Retrieves an emoji based on a given locale code.\n   * Uses the locale's region (if present) to select an emoji or falls back on default emojis.\n   *\n   * @param {string} [locale=this.targetLocale] - A BCP-47 locale code (e.g., 'en-US', 'fr-CA')\n   * @returns {string} The emoji representing the locale or its region.\n   * @throws {Error} If no target locale is provided.\n   *\n   * @example\n   * gt.getLocaleEmoji('es-ES');\n   * // Returns: \"🇪🇸\"\n   */\n  getLocaleEmoji(locale = this.targetLocale): string {\n    if (!locale) throw new Error(noTargetLocaleProvidedError('getLocaleEmoji'));\n    return this.localeConfig.getLocaleEmoji(locale);\n  }\n\n  /**\n   * Generates linguistic details for a given locale code.\n   *\n   * This function returns information about the locale,\n   * script, and region of a given language code both in a standard form and in a maximized form (with likely script and region).\n   * The function provides these names in both your default language and native forms, and an associated emoji.\n   *\n   * @param {string} [locale=this.targetLocale] - The locale code to get properties for (e.g., \"de-AT\").\n   * @returns {LocaleProperties} - An object containing detailed information about the locale.\n   *\n   * @property {string} code - The full locale code, e.g., \"de-AT\".\n   * @property {string} name - Language name in the default display language, e.g., \"Austrian German\".\n   * @property {string} nativeName - Language name in the locale's native language, e.g., \"Österreichisches Deutsch\".\n   * @property {string} languageCode - The base language code, e.g., \"de\".\n   * @property {string} languageName - The language name in the default display language, e.g., \"German\".\n   * @property {string} nativeLanguageName - The language name in the native language, e.g., \"Deutsch\".\n   * @property {string} nameWithRegionCode - Language name with region in the default language, e.g., \"German (AT)\".\n   * @property {string} nativeNameWithRegionCode - Language name with region in the native language, e.g., \"Deutsch (AT)\".\n   * @property {string} regionCode - The region code from maximization, e.g., \"AT\".\n   * @property {string} regionName - The region name in the default display language, e.g., \"Austria\".\n   * @property {string} nativeRegionName - The region name in the native language, e.g., \"Österreich\".\n   * @property {string} scriptCode - The script code from maximization, e.g., \"Latn\".\n   * @property {string} scriptName - The script name in the default display language, e.g., \"Latin\".\n   * @property {string} nativeScriptName - The script name in the native language, e.g., \"Lateinisch\".\n   * @property {string} maximizedCode - The maximized locale code, e.g., \"de-Latn-AT\".\n   * @property {string} maximizedName - Maximized locale name with likely script in the default language, e.g., \"Austrian German (Latin)\".\n   * @property {string} nativeMaximizedName - Maximized locale name in the native language, e.g., \"Österreichisches Deutsch (Lateinisch)\".\n   * @property {string} minimizedCode - Minimized locale code, e.g., \"de-AT\" (or \"de\" for \"de-DE\").\n   * @property {string} minimizedName - Minimized language name in the default language, e.g., \"Austrian German\".\n   * @property {string} nativeMinimizedName - Minimized language name in the native language, e.g., \"Österreichisches Deutsch\".\n   * @property {string} emoji - The emoji associated with the locale's region, if applicable.\n   */\n  getLocaleProperties(locale = this.targetLocale): LocaleProperties {\n    if (!locale)\n      throw new Error(noTargetLocaleProvidedError('getLocaleProperties'));\n    return this.localeConfig.getLocaleProperties(locale);\n  }\n\n  /**\n   * Retrieves multiple properties for a given region code, including:\n   * - `code`: the original region code\n   * - `name`: the localized display name\n   * - `emoji`: the associated flag or symbol\n   *\n   * Behavior:\n   * - Accepts ISO 3166-1 alpha-2 or UN M.49 region codes (e.g., `\"US\"`, `\"FR\"`, `\"419\"`).\n   * - Uses the instance's `targetLocale` to localize the region name for the user.\n   * - If `customMapping` contains a `name` or `emoji` for the region, those override the default values.\n   * - Otherwise, uses `Intl.DisplayNames` to get the localized region name, falling back to `libraryDefaultLocale`.\n   * - Falls back to the region code as `name` if display name resolution fails.\n   * - Falls back to a default emoji if no emoji mapping is found in built-in data or `customMapping`.\n   *\n   * @param {string} [region=this.getLocaleProperties().regionCode] - The region code to look up (e.g., `\"US\"`, `\"GB\"`, `\"DE\"`).\n   * @param {CustomRegionMapping} [customMapping] - Optional mapping of region codes to custom names and/or emojis.\n   * @returns {{ code: string, name: string, emoji: string }} An object containing:\n   *  - `code`: the input region code\n   *  - `name`: the localized or custom region name\n   *  - `emoji`: the matching emoji flag or symbol\n   *\n   * @throws {Error} If no target locale is available to determine region properties.\n   *\n   * @example\n   * const gt = new GTRuntime({ targetLocale: 'en-US' });\n   * gt.getRegionProperties('US');\n   * // => { code: 'US', name: 'United States', emoji: '🇺🇸' }\n   *\n   * @example\n   * const gt = new GTRuntime({ targetLocale: 'fr-FR' });\n   * gt.getRegionProperties('US');\n   * // => { code: 'US', name: 'États-Unis', emoji: '🇺🇸' }\n   *\n   * @example\n   * gt.getRegionProperties('US', { US: { name: 'USA', emoji: '🗽' } });\n   * // => { code: 'US', name: 'USA', emoji: '🗽' }\n   */\n  getRegionProperties(\n    region = this.getLocaleProperties().regionCode,\n    customMapping?: CustomRegionMapping\n  ): { code: string; name: string; emoji: string } {\n    if (!customMapping) {\n      if (this.customMapping && !this.customRegionMapping) {\n        // Lazy derive custom region mapping from customMapping\n        const customRegionMapping: CustomRegionMapping = {};\n        for (const [locale, lp] of Object.entries(this.customMapping)) {\n          if (\n            lp &&\n            typeof lp === 'object' &&\n            lp.regionCode &&\n            !customRegionMapping[lp.regionCode]\n          ) {\n            const { regionName: name, emoji } = lp;\n            customRegionMapping[lp.regionCode] = {\n              locale,\n              ...(name && { name }),\n              ...(emoji && { emoji }),\n            };\n          }\n        }\n        this.customRegionMapping = customRegionMapping;\n      }\n      customMapping = this.customRegionMapping;\n    }\n    return _getRegionProperties(\n      region,\n      this.targetLocale, // this.targetLocale because we want it in the user's language\n      customMapping\n    );\n  }\n\n  /**\n   * Determines whether a translation is required based on the source and target locales.\n   *\n   * @param {string} [sourceLocale=this.sourceLocale] - The locale code for the original content.\n   * @param {string} [targetLocale=this.targetLocale] - The locale code to translate into.\n   * @param {string[]} [approvedLocales=this.locales] - Optional array of approved target locales.\n   * @returns {boolean} True if translation is required, false otherwise\n   * @throws {Error} If no source locale is provided.\n   * @throws {Error} If no target locale is provided.\n   *\n   * @example\n   * gt.requiresTranslation('en-US', 'es-ES');\n   * // Returns: true\n   */\n  requiresTranslation(\n    sourceLocale = this.sourceLocale,\n    targetLocale = this.targetLocale,\n    approvedLocales: string[] | undefined = this.locales,\n    customMapping: CustomMapping | undefined = this.customMapping\n  ): boolean {\n    if (!sourceLocale)\n      throw new Error(noSourceLocaleProvidedError('requiresTranslation'));\n    if (!targetLocale)\n      throw new Error(noTargetLocaleProvidedError('requiresTranslation'));\n    if (customMapping === this.customMapping) {\n      return this.localeConfig.requiresTranslation(\n        targetLocale,\n        sourceLocale,\n        approvedLocales\n      );\n    }\n    return _requiresTranslation(\n      sourceLocale,\n      targetLocale,\n      approvedLocales,\n      customMapping\n    );\n  }\n\n  /**\n   * Determines the best matching locale from the provided approved locales list.\n   *\n   * @param {string | string[]} locales - A single locale or array of locales in preference order.\n   * @param {string[]} [approvedLocales=this.locales] - Array of approved locales in preference order.\n   * @returns {string | undefined} The best matching locale, or undefined if no match is found.\n   *\n   * @example\n   * gt.determineLocale(['fr-CA', 'fr-FR'], ['en-US', 'fr-FR', 'es-ES']);\n   * // Returns: \"fr-FR\"\n   */\n  determineLocale(\n    locales: string | string[],\n    approvedLocales: string[] | undefined = this.locales || [],\n    customMapping: CustomMapping | undefined = this.customMapping\n  ): string | undefined {\n    if (customMapping === this.customMapping) {\n      return this.localeConfig.determineLocale(locales, approvedLocales ?? []);\n    }\n    return new LocaleConfig({ customMapping }).determineLocale(\n      locales,\n      approvedLocales ?? []\n    );\n  }\n\n  /**\n   * Gets the text direction for a given locale code.\n   *\n   * @param {string} [locale=this.targetLocale] - A BCP-47 locale code.\n   * @returns {'ltr' | 'rtl'} 'rtl' if the locale is right-to-left; otherwise 'ltr'.\n   * @throws {Error} If no target locale is provided.\n   *\n   * @example\n   * gt.getLocaleDirection('ar-SA');\n   * // Returns: \"rtl\"\n   */\n  getLocaleDirection(locale = this.targetLocale): 'ltr' | 'rtl' {\n    if (!locale)\n      throw new Error(noTargetLocaleProvidedError('getLocaleDirection'));\n    return this.localeConfig.getLocaleDirection(locale);\n  }\n\n  /**\n   * Checks if a given BCP 47 locale code is valid.\n   *\n   * @param {string} [locale=this.targetLocale] - The BCP 47 locale code to validate.\n   * @param {CustomMapping} [customMapping=this.customMapping] - The custom mapping to use for validation.\n   * @returns {boolean} True if the locale code is valid, false otherwise\n   * @throws {Error} If no target locale is provided.\n   *\n   * @example\n   * gt.isValidLocale('en-US');\n   * // Returns: true\n   */\n  isValidLocale(\n    locale = this.targetLocale,\n    customMapping: CustomMapping | undefined = this.customMapping\n  ): boolean {\n    if (!locale) throw new Error(noTargetLocaleProvidedError('isValidLocale'));\n    if (customMapping === this.customMapping) {\n      return this.localeConfig.isValidLocale(locale);\n    }\n    return _isValidLocale(locale, customMapping);\n  }\n\n  /**\n   * Resolves the canonical locale for a given locale.\n   * @param locale - The locale to resolve the canonical locale for\n   * @param customMapping - The custom mapping to use for resolving the canonical locale\n   * @returns The canonical locale, or the input locale when no canonical mapping exists.\n   */\n  resolveCanonicalLocale(\n    locale: string | undefined = this.targetLocale,\n    customMapping: CustomMapping | undefined = this.customMapping\n  ): string {\n    if (!locale)\n      throw new Error(noTargetLocaleProvidedError('resolveCanonicalLocale'));\n    if (customMapping === this.customMapping) {\n      return this.localeConfig.resolveCanonicalLocale(locale);\n    }\n    return _resolveCanonicalLocale(locale, customMapping);\n  }\n\n  /**\n   * Resolves the alias locale for a given locale.\n   * @param locale - The locale to resolve the alias locale for\n   * @param customMapping - The custom mapping to use for resolving the alias locale\n   * @returns The configured alias for a canonical locale, or the input locale when already an alias or no alias mapping exists.\n   */\n  resolveAliasLocale(\n    locale: string,\n    customMapping: CustomMapping | undefined = this.customMapping\n  ): string {\n    if (!locale)\n      throw new Error(noTargetLocaleProvidedError('resolveAliasLocale'));\n    if (customMapping === this.customMapping) {\n      return this.localeConfig.resolveAliasLocale(locale);\n    }\n    return _resolveAliasLocale(locale, customMapping);\n  }\n\n  /**\n   * Standardizes a BCP 47 locale code to ensure correct formatting.\n   *\n   * @param {string} [locale=this.targetLocale] - The BCP 47 locale code to standardize.\n   * @returns {string} The standardized locale code, or the input string if it cannot be standardized.\n   * @throws {Error} If no target locale is provided.\n   *\n   * @example\n   * gt.standardizeLocale('en_us');\n   * // Returns: \"en-US\"\n   */\n  standardizeLocale(locale = this.targetLocale): string {\n    if (!locale)\n      throw new Error(noTargetLocaleProvidedError('standardizeLocale'));\n    return this.localeConfig.standardizeLocale(locale);\n  }\n\n  /**\n   * Checks if multiple BCP 47 locale codes represent the same dialect.\n   *\n   * @param {...(string | string[])} locales - The BCP 47 locale codes to compare.\n   * @returns {boolean} True if all codes represent the same dialect, false otherwise\n   *\n   * @example\n   * gt.isSameDialect('en-US', 'en-GB');\n   * // Returns: false\n   *\n   * gt.isSameDialect('en', 'en-US');\n   * // Returns: true\n   */\n  isSameDialect(...locales: (string | string[])[]): boolean {\n    return this.localeConfig.isSameDialect(...locales);\n  }\n\n  /**\n   * Checks if multiple BCP 47 locale codes represent the same language.\n   *\n   * @param {...(string | string[])} locales - The BCP 47 locale codes to compare.\n   * @returns {boolean} True if all codes represent the same language, false otherwise\n   *\n   * @example\n   * gt.isSameLanguage('en-US', 'en-GB');\n   * // Returns: true\n   */\n  isSameLanguage(...locales: (string | string[])[]): boolean {\n    return this.localeConfig.isSameLanguage(...locales);\n  }\n\n  /**\n   * Checks if a locale is a superset of another locale.\n   *\n   * @param {string} superLocale - The locale to check if it is a superset\n   * @param {string} subLocale - The locale to check if it is a subset\n   * @returns {boolean} True if superLocale is a superset of subLocale, false otherwise\n   *\n   * @example\n   * gt.isSupersetLocale('en', 'en-US');\n   * // Returns: true\n   *\n   * gt.isSupersetLocale('en-US', 'en');\n   * // Returns: false\n   */\n  isSupersetLocale(superLocale: string, subLocale: string): boolean {\n    return this.localeConfig.isSupersetLocale(superLocale, subLocale);\n  }\n}\n"],"mappings":"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"}

package/dist/runtime.d.cts

@@ -1,4 +1,5 @@
-import { Ft as TranslateOptions, J as TranslationResult, K as TranslateManyResult, Pt as TranslateManyEntry, S as TranslationRequestConfig, q as TranslationError } from "./types-bCr8pV1Z.cjs";
+import { D as TranslationRequestConfig, Ft as TranslateManyEntry, It as TranslateOptions, X as TranslationError, Y as TranslateManyResult, Z as TranslationResult } from "./types-yByDbKnV.cjs";
+import { UserTokenProvider } from "@generaltranslation/api";
 import { CustomMapping, CustomRegionMapping, CutoffFormatOptions, FormatVariables, LocaleProperties, StringFormat } from "@generaltranslation/format/types";
 import { LocaleConfig } from "@generaltranslation/format";
 
@@ -7,7 +8,7 @@ import { LocaleConfig } from "@generaltranslation/format";
  * Type representing the constructor parameters for the GT and GTRuntime classes.
  * @typedef {Object} GTConstructorParams
  * @property {string} [apiKey] - The API key for accessing the translation service
- * @property {string} [devApiKey] - The development API key for accessing the translation service
+ * @property {string} [devApiKey] - Deprecated alias for apiKey
  * @property {string} [sourceLocale] - The default source locale for translations
  * @property {string} [targetLocale] - The default target locale for translations
  * @property {string[]} [locales] - Array of supported locales
@@ -16,7 +17,7 @@ import { LocaleConfig } from "@generaltranslation/format";
  * @property {CustomMapping} [customMapping] - Custom mapping of locale codes to their names
  */
 type GTConstructorParams = {
-  apiKey?: string;
+  apiKey?: string; /** @deprecated Pass the key as `apiKey`; there is one kind of API key. */
   devApiKey?: string;
   sourceLocale?: string;
   targetLocale?: string;
@@ -24,6 +25,7 @@ type GTConstructorParams = {
   projectId?: string;
   baseUrl?: string;
   customMapping?: CustomMapping;
+  userTokenProvider?: UserTokenProvider;
 };
 /**
  * GTRuntime is the runtime core of the GT driver: locale management,
@@ -47,8 +49,10 @@ declare class GTRuntime {
   projectId?: string;
   /** API key for accessing the translation service */
   apiKey?: string;
-  /** Development API key for accessing the translation service */
+  /** @deprecated Pass the key as `apiKey`; there is one kind of API key. */
   devApiKey?: string;
+  /** User-token provider used when no API key is configured */
+  userTokenProvider?: UserTokenProvider;
   /** Source locale for translations */
   sourceLocale?: string;
   /** Target locale for translations */
@@ -89,7 +93,8 @@ declare class GTRuntime {
     locales,
     projectId,
     customMapping,
-    baseUrl
+    baseUrl,
+    userTokenProvider
   }: GTConstructorParams): void;
   /** Convert app identity only where a GT service expects a language code. */
   protected resolveServiceLocale(locale: string): string;
@@ -100,13 +105,13 @@ declare class GTRuntime {
    */
   protected resolveServiceResponseLocale(locale: string): string;
   protected _getTranslationConfig(): TranslationRequestConfig;
-  protected _validateAuth(functionName: string): void;
   /**
    * Translates a single source string to the target locale.
    * Routes through {@link translateMany} under the hood.
    *
    * @param {string} source - The source string to translate.
    * @param {object} options - Translation options including targetLocale and optional entry metadata.
+   * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.
    * @returns {Promise<TranslationResult | TranslationError>} The translated content.
    *
    * @example
@@ -126,6 +131,7 @@ declare class GTRuntime {
    *
    * @param {TranslateManyEntry[] | Record<string, TranslateManyEntry>} sources - The source entries to translate. Can be an array or a record keyed by hash.
    * @param {object} options - Translation options including targetLocale.
+   * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.
    * @returns {Promise<TranslateManyResult | Record<string, TranslationResult>>} The translated contents. An array if sources was an array, a record if sources was a record.
    *
    * @example

package/dist/runtime.d.mts

@@ -1,4 +1,5 @@
-import { Ft as TranslateOptions, J as TranslationResult, K as TranslateManyResult, Pt as TranslateManyEntry, S as TranslationRequestConfig, q as TranslationError } from "./types-Dp1drjxq.mjs";
+import { D as TranslationRequestConfig, Ft as TranslateManyEntry, It as TranslateOptions, X as TranslationError, Y as TranslateManyResult, Z as TranslationResult } from "./types-Si4UstLL.mjs";
+import { UserTokenProvider } from "@generaltranslation/api";
 import { LocaleConfig } from "@generaltranslation/format";
 import { CustomMapping, CustomRegionMapping, CutoffFormatOptions, FormatVariables, LocaleProperties, StringFormat } from "@generaltranslation/format/types";
 
@@ -7,7 +8,7 @@ import { CustomMapping, CustomRegionMapping, CutoffFormatOptions, FormatVariable
  * Type representing the constructor parameters for the GT and GTRuntime classes.
  * @typedef {Object} GTConstructorParams
  * @property {string} [apiKey] - The API key for accessing the translation service
- * @property {string} [devApiKey] - The development API key for accessing the translation service
+ * @property {string} [devApiKey] - Deprecated alias for apiKey
  * @property {string} [sourceLocale] - The default source locale for translations
  * @property {string} [targetLocale] - The default target locale for translations
  * @property {string[]} [locales] - Array of supported locales
@@ -16,7 +17,7 @@ import { CustomMapping, CustomRegionMapping, CutoffFormatOptions, FormatVariable
  * @property {CustomMapping} [customMapping] - Custom mapping of locale codes to their names
  */
 type GTConstructorParams = {
-  apiKey?: string;
+  apiKey?: string; /** @deprecated Pass the key as `apiKey`; there is one kind of API key. */
   devApiKey?: string;
   sourceLocale?: string;
   targetLocale?: string;
@@ -24,6 +25,7 @@ type GTConstructorParams = {
   projectId?: string;
   baseUrl?: string;
   customMapping?: CustomMapping;
+  userTokenProvider?: UserTokenProvider;
 };
 /**
  * GTRuntime is the runtime core of the GT driver: locale management,
@@ -47,8 +49,10 @@ declare class GTRuntime {
   projectId?: string;
   /** API key for accessing the translation service */
   apiKey?: string;
-  /** Development API key for accessing the translation service */
+  /** @deprecated Pass the key as `apiKey`; there is one kind of API key. */
   devApiKey?: string;
+  /** User-token provider used when no API key is configured */
+  userTokenProvider?: UserTokenProvider;
   /** Source locale for translations */
   sourceLocale?: string;
   /** Target locale for translations */
@@ -89,7 +93,8 @@ declare class GTRuntime {
     locales,
     projectId,
     customMapping,
-    baseUrl
+    baseUrl,
+    userTokenProvider
   }: GTConstructorParams): void;
   /** Convert app identity only where a GT service expects a language code. */
   protected resolveServiceLocale(locale: string): string;
@@ -100,13 +105,13 @@ declare class GTRuntime {
    */
   protected resolveServiceResponseLocale(locale: string): string;
   protected _getTranslationConfig(): TranslationRequestConfig;
-  protected _validateAuth(functionName: string): void;
   /**
    * Translates a single source string to the target locale.
    * Routes through {@link translateMany} under the hood.
    *
    * @param {string} source - The source string to translate.
    * @param {object} options - Translation options including targetLocale and optional entry metadata.
+   * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.
    * @returns {Promise<TranslationResult | TranslationError>} The translated content.
    *
    * @example
@@ -126,6 +131,7 @@ declare class GTRuntime {
    *
    * @param {TranslateManyEntry[] | Record<string, TranslateManyEntry>} sources - The source entries to translate. Can be an array or a record keyed by hash.
    * @param {object} options - Translation options including targetLocale.
+   * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.
    * @returns {Promise<TranslateManyResult | Record<string, TranslationResult>>} The translated contents. An array if sources was an array, a record if sources was a record.
    *
    * @example

package/dist/runtime.d.ts

@@ -1,12 +1,13 @@
 import { LocaleConfig } from '@generaltranslation/format';
 import type { CustomMapping, CustomRegionMapping, CutoffFormatOptions, FormatVariables, LocaleProperties, StringFormat } from '@generaltranslation/format/types';
+import type { UserTokenProvider } from '@generaltranslation/api';
 import { TranslateManyResult, TranslationError, TranslationRequestConfig, TranslationResult, TranslateManyEntry } from './types';
 import { TranslateOptions } from './types-dir/api/entry';
 /**
  * Type representing the constructor parameters for the GT and GTRuntime classes.
  * @typedef {Object} GTConstructorParams
  * @property {string} [apiKey] - The API key for accessing the translation service
- * @property {string} [devApiKey] - The development API key for accessing the translation service
+ * @property {string} [devApiKey] - Deprecated alias for apiKey
  * @property {string} [sourceLocale] - The default source locale for translations
  * @property {string} [targetLocale] - The default target locale for translations
  * @property {string[]} [locales] - Array of supported locales
@@ -16,6 +17,7 @@ import { TranslateOptions } from './types-dir/api/entry';
  */
 export type GTConstructorParams = {
     apiKey?: string;
+    /** @deprecated Pass the key as `apiKey`; there is one kind of API key. */
     devApiKey?: string;
     sourceLocale?: string;
     targetLocale?: string;
@@ -23,6 +25,7 @@ export type GTConstructorParams = {
     projectId?: string;
     baseUrl?: string;
     customMapping?: CustomMapping;
+    userTokenProvider?: UserTokenProvider;
 };
 /**
  * GTRuntime is the runtime core of the GT driver: locale management,
@@ -46,8 +49,10 @@ export declare class GTRuntime {
     projectId?: string;
     /** API key for accessing the translation service */
     apiKey?: string;
-    /** Development API key for accessing the translation service */
+    /** @deprecated Pass the key as `apiKey`; there is one kind of API key. */
     devApiKey?: string;
+    /** User-token provider used when no API key is configured */
+    userTokenProvider?: UserTokenProvider;
     /** Source locale for translations */
     sourceLocale?: string;
     /** Target locale for translations */
@@ -80,7 +85,7 @@ export declare class GTRuntime {
      * });
      */
     constructor(params?: GTConstructorParams);
-    setConfig({ apiKey, devApiKey, sourceLocale, targetLocale, locales, projectId, customMapping, baseUrl, }: GTConstructorParams): void;
+    setConfig({ apiKey, devApiKey, sourceLocale, targetLocale, locales, projectId, customMapping, baseUrl, userTokenProvider, }: GTConstructorParams): void;
     /** Convert app identity only where a GT service expects a language code. */
     protected resolveServiceLocale(locale: string): string;
     /**
@@ -90,13 +95,13 @@ export declare class GTRuntime {
      */
     protected resolveServiceResponseLocale(locale: string): string;
     protected _getTranslationConfig(): TranslationRequestConfig;
-    protected _validateAuth(functionName: string): void;
     /**
      * Translates a single source string to the target locale.
      * Routes through {@link translateMany} under the hood.
      *
      * @param {string} source - The source string to translate.
      * @param {object} options - Translation options including targetLocale and optional entry metadata.
+     * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.
      * @returns {Promise<TranslationResult | TranslationError>} The translated content.
      *
      * @example
@@ -116,6 +121,7 @@ export declare class GTRuntime {
      *
      * @param {TranslateManyEntry[] | Record<string, TranslateManyEntry>} sources - The source entries to translate. Can be an array or a record keyed by hash.
      * @param {object} options - Translation options including targetLocale.
+     * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.
      * @returns {Promise<TranslateManyResult | Record<string, TranslationResult>>} The translated contents. An array if sources was an array, a record if sources was a record.
      *
      * @example

package/dist/runtime.js

@@ -58,10 +58,8 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
 };
 // ----- IMPORTS ----- //
 import { LocaleConfig, getRegionProperties as _getRegionProperties, isValidLocale as _isValidLocale, requiresTranslation as _requiresTranslation, resolveAliasLocale as _resolveAliasLocale, resolveCanonicalLocale as _resolveCanonicalLocale, } from '@generaltranslation/format';
-import { libraryDefaultLocale } from './settings/settings';
-import { noSourceLocaleProvidedError, noTargetLocaleProvidedError, invalidLocaleError, invalidLocalesError, noProjectIdProvidedError, noApiKeyProvidedError, } from './logging/errors';
-import { gtInstanceLogger } from './logging/logger';
-import { _translateMany } from './translate/translateMany';
+import { noSourceLocaleProvidedError, noTargetLocaleProvidedError, invalidLocaleError, invalidLocalesError, } from './logging/errors';
+import { translate as translateWithConfig, translateMany as translateManyWithConfig, } from './translate/runtimeTranslate';
 /**
  * GTRuntime is the runtime core of the GT driver: locale management,
  * formatting, and runtime translation requests.
@@ -99,6 +97,7 @@ var GTRuntime = /** @class */ (function () {
         // Read environment
         if (typeof process !== 'undefined') {
             this.apiKey || (this.apiKey = (_a = process.env) === null || _a === void 0 ? void 0 : _a.GT_API_KEY);
+            // Deprecated with devApiKey; frameworks resolve the hot-reload key themselves.
             this.devApiKey || (this.devApiKey = (_b = process.env) === null || _b === void 0 ? void 0 : _b.GT_DEV_API_KEY);
             this.projectId || (this.projectId = (_c = process.env) === null || _c === void 0 ? void 0 : _c.GT_PROJECT_ID);
         }
@@ -115,7 +114,7 @@ var GTRuntime = /** @class */ (function () {
     });
     GTRuntime.prototype.setConfig = function (_a) {
         var _b;
-        var apiKey = _a.apiKey, devApiKey = _a.devApiKey, sourceLocale = _a.sourceLocale, targetLocale = _a.targetLocale, locales = _a.locales, projectId = _a.projectId, customMapping = _a.customMapping, baseUrl = _a.baseUrl;
+        var apiKey = _a.apiKey, devApiKey = _a.devApiKey, sourceLocale = _a.sourceLocale, targetLocale = _a.targetLocale, locales = _a.locales, projectId = _a.projectId, customMapping = _a.customMapping, baseUrl = _a.baseUrl, userTokenProvider = _a.userTokenProvider;
         var effectiveCustomMapping = customMapping !== null && customMapping !== void 0 ? customMapping : this.customMapping;
         // ----- Environment properties ----- //
         if (apiKey)
@@ -124,6 +123,8 @@ var GTRuntime = /** @class */ (function () {
             this.devApiKey = devApiKey;
         if (projectId)
             this.projectId = projectId;
+        if (userTokenProvider)
+            this.userTokenProvider = userTokenProvider;
         // ----- Validate configured locale identities ----- //
         // source locale
         if (sourceLocale) {
@@ -202,28 +203,16 @@ var GTRuntime = /** @class */ (function () {
             baseUrl: this.baseUrl,
             apiKey: this.apiKey || this.devApiKey,
             projectId: this.projectId || '',
+            userTokenProvider: this.userTokenProvider,
         };
     };
-    GTRuntime.prototype._validateAuth = function (functionName) {
-        var errors = [];
-        if (!this.apiKey && !this.devApiKey) {
-            var error = noApiKeyProvidedError(functionName);
-            errors.push(error);
-        }
-        if (!this.projectId) {
-            var error = noProjectIdProvidedError(functionName);
-            errors.push(error);
-        }
-        if (errors.length) {
-            throw new Error(errors.join('\n'));
-        }
-    };
     /**
      * Translates a single source string to the target locale.
      * Routes through {@link translateMany} under the hood.
      *
      * @param {string} source - The source string to translate.
      * @param {object} options - Translation options including targetLocale and optional entry metadata.
+     * @param {number} [timeout] - Timeout in milliseconds; 0 or omitted selects the runtime default.
      * @returns {Promise<TranslationResult | TranslationError>} The translated content.
      *
      * @example
@@ -238,59 +227,15 @@ var GTRuntime = /** @class */ (function () {
      */
     GTRuntime.prototype.translate = function (source, options, timeout) {
         return __awaiter(this, void 0, void 0, function () {
-            var targetLocale, error, sourceLocale, results;
             return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0:
-                        // Normalize string shorthand to options object
-                        if (typeof options === 'string') {
-                            options = { targetLocale: options };
-                        }
-                        // Validation
-                        this._validateAuth('translate');
-                        targetLocale = (options === null || options === void 0 ? void 0 : options.targetLocale) || this.targetLocale;
-                        if (!targetLocale) {
-                            error = noTargetLocaleProvidedError('translate');
-                            gtInstanceLogger.error(error);
-                            throw new Error(error);
-                        }
-                        // Replace target locale with canonical locale
-                        targetLocale = this.resolveServiceLocale(targetLocale);
-                        sourceLocale = this.resolveServiceLocale((options === null || options === void 0 ? void 0 : options.sourceLocale) || this.sourceLocale || libraryDefaultLocale);
-                        return [4 /*yield*/, _translateMany([source], __assign(__assign({}, options), { targetLocale: targetLocale, sourceLocale: sourceLocale }), this._getTranslationConfig(), timeout)];
-                    case 1:
-                        results = _a.sent();
-                        return [2 /*return*/, results[0]];
-                }
+                return [2 /*return*/, translateWithConfig(source, options, __assign(__assign({}, this._getTranslationConfig()), { customMapping: this.customMapping, timeoutMs: timeout || undefined }), this)];
             });
         });
     };
     GTRuntime.prototype.translateMany = function (sources, options, timeout) {
         return __awaiter(this, void 0, void 0, function () {
-            var targetLocale, error, sourceLocale;
             return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0:
-                        // Normalize string shorthand to options object
-                        if (typeof options === 'string') {
-                            options = { targetLocale: options };
-                        }
-                        // Validation
-                        this._validateAuth('translateMany');
-                        targetLocale = (options === null || options === void 0 ? void 0 : options.targetLocale) || this.targetLocale;
-                        if (!targetLocale) {
-                            error = noTargetLocaleProvidedError('translateMany');
-                            gtInstanceLogger.error(error);
-                            throw new Error(error);
-                        }
-                        // Replace target locale with canonical locale
-                        targetLocale = this.resolveServiceLocale(targetLocale);
-                        sourceLocale = this.resolveServiceLocale((options === null || options === void 0 ? void 0 : options.sourceLocale) || this.sourceLocale || libraryDefaultLocale);
-                        return [4 /*yield*/, _translateMany(sources, __assign(__assign({}, options), { targetLocale: targetLocale, sourceLocale: sourceLocale }), this._getTranslationConfig(), timeout)];
-                    case 1: 
-                    // Request the translation.
-                    return [2 /*return*/, _a.sent()];
-                }
+                return [2 /*return*/, translateManyWithConfig(sources, options, __assign(__assign({}, this._getTranslationConfig()), { customMapping: this.customMapping, timeoutMs: timeout || undefined }), this)];
             });
         });
     };