Instance Management

/**
 * Creates a new Polyglot instance
 * @param {Object} options - Configuration options
 * @param {Object} options.phrases - Initial phrases object
 * @param {string} options.locale - Initial locale (default: 'en')
 * @param {boolean} options.allowMissing - Enable missing key handling
 * @param {Function} options.onMissingKey - Custom missing key handler function
 * @param {Function} options.warn - Custom warning function for missing keys
 * @param {Function} options.replace - Custom string replace implementation
 * @param {Object} options.interpolation - Token configuration object
 * @param {string} options.interpolation.prefix - Token prefix (default: '%{')
 * @param {string} options.interpolation.suffix - Token suffix (default: '}')
 * @param {Object} options.pluralRules - Custom pluralization rules object
 * @returns {Polyglot} New Polyglot instance
 */
function Polyglot(options);

const Polyglot = require('node-polyglot');

// Basic instance with phrases
const polyglot = new Polyglot({
  phrases: {
    'hello': 'Hello',
    'goodbye': 'Goodbye'
  },
  locale: 'en'
});

// Instance with custom interpolation tokens
const customPolyglot = new Polyglot({
  phrases: {
    'welcome': 'Welcome {{name}} to {{place}}!'
  },
  interpolation: {
    prefix: '{{',
    suffix: '}}'
  }
});

// Instance with custom missing key handler
const polyglotWithHandler = new Polyglot({
  onMissingKey: function(key, options, locale) {
    console.warn(`Missing translation for key: ${key}`);
    return `[${key}]`; // Return bracketed key as fallback
  }
});

// Instance with allowMissing enabled
const lenientPolyglot = new Polyglot({
  allowMissing: true, // Uses transformPhrase as onMissingKey handler
  locale: 'es'
});

/**
 * Internal phrases storage (flattened key-value pairs)
 * @type {Object}
 */
phrases;

/**
 * Current locale setting
 * @type {string}
 */
currentLocale;

/**
 * Missing key handler function or null
 * @type {Function|null}
 */
onMissingKey;

/**
 * Warning function for missing keys
 * @type {Function}
 */
warn;

/**
 * String replace implementation function
 * @type {Function}
 */
replaceImplementation;

/**
 * Token matching regular expression
 * @type {RegExp}
 */
tokenRegex;

/**
 * Pluralization rules object
 * @type {Object}
 */
pluralRules;

const polyglot = new Polyglot({
  phrases: { 'hello': 'Hello' },
  locale: 'en'
});

// Access instance properties
console.log(polyglot.phrases);        // { 'hello': 'Hello' }
console.log(polyglot.currentLocale);  // 'en'
console.log(polyglot.tokenRegex);     // /%\{(.*?)\}/g

// Properties are writable but modifying them directly is not recommended
// Use the provided methods instead

interface InterpolationConfig {
  /** Token prefix (default: '%{') */
  prefix?: string;
  /** Token suffix (default: '}') */
  suffix?: string;
}

/**
 * Custom handler for missing translation keys
 * @param {string} key - The requested translation key
 * @param {Object} options - Interpolation options passed to t()
 * @param {string} currentLocale - Current locale setting
 * @param {RegExp} tokenRegex - Token matching regex
 * @param {Object} pluralRules - Pluralization rules
 * @param {Function} replaceImplementation - String replace function
 * @returns {string} Fallback translation or transformed phrase
 */
function onMissingKey(key, options, currentLocale, tokenRegex, pluralRules, replaceImplementation);

interface PluralRules {
  /** Mapping from plural type names to pluralization functions */
  pluralTypes: {
    [typeName: string]: (count: number) => number;
  };
  /** Mapping from plural type names to language code arrays */
  pluralTypeToLanguages: {
    [typeName: string]: string[];
  };
}