/**
 * Service for translating strings into different languages.
 *
 * The Translator provides internationalization (i18n) support for web components,
 * allowing you to display user-facing text in the user's preferred language.
 * Translation strings are identified by unique IDs and can include dynamic
 * parameters for values that change at runtime.
 *
 * Translations are managed by the platform and grouped by a two-letter language
 * code (e.g., en, sv). A locale such as `sv_SE` is reduced to its language part,
 * so regional variants share one set of translations. The Translator picks the
 * language from the user's settings.
 *
 * @example Basic usage
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const translator = platform.get(PlatformServiceName.Translate);
 *
 * // Simple translation
 * const greeting = translator.get('my-addon.greeting.hello');
 *
 * // Translation with parameters
 * const message = translator.get('my-addon.user.welcome', {
 *     name: 'Alice',
 *     count: 5,
 * });
 * ```
 *
 * @public
 * @group Localization
 */
export interface Translator {
    /**
     * Retrieves a translated string by its unique identifier.
     *
     * This method looks up a translation using the provided ID and returns the
     * localized string for the current user's language. If the translation contains
     * placeholders (e.g., `{name}`, `{count}`), you can provide parameter values
     * to replace them dynamically.
     *
     * A missing translation falls back in two steps. If the ID has no entry in the
     * user's language, the English text is used. If English has no entry either,
     * the ID itself is returned, which makes missing translations easy to spot
     * during development.
     *
     * Translation strings are ICU MessageFormat patterns, so a placeholder can do
     * more than name a value. Constructs such as `plural` and `select` let one
     * string cover several cases. If the pattern cannot be formatted, for example
     * when a placeholder has no matching key in `params`, the raw string is
     * returned unchanged.
     *
     * @param id - Unique identifier for the translation string. Organized
     * hierarchically using dot notation, starting with the name of the package
     * that owns the string (e.g., 'webclient.object-explorer.load-objects-error').
     * @param params - Optional key-value pairs for dynamic parameter substitution.
     * Keys must match placeholder names in the translation string. Values can be
     * strings, numbers, or undefined. Undefined values are treated as empty strings.
     * @returns The translated and parameterized string in the user's language.
     *
     * @example Translation with parameters
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const translator = platform.get(PlatformServiceName.Translate);
     *
     * // Translation: "{user} updated {recordType} #{recordId}"
     * translator.get('my-addon.activity.update', {
     *     user: 'John Smith',
     *     recordType: 'deal',
     *     recordId: 1234,
     * });
     * // Returns: "John Smith updated deal #1234"
     * ```
     *
     * @example Plural and select
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const translator = platform.get(PlatformServiceName.Translate);
     *
     * // Translation: "{count, plural, one {# deal} other {# deals}}"
     * translator.get('my-addon.deal.count', { count: 1 });
     * // Returns: "1 deal"
     * translator.get('my-addon.deal.count', { count: 5 });
     * // Returns: "5 deals"
     *
     * // Translation: "{status, select, won {Closed} lost {Lost} other {Open}}"
     * translator.get('my-addon.deal.status', { status: 'won' });
     * // Returns: "Closed"
     * ```
     *
     * @example Handling optional parameters
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const translator = platform.get(PlatformServiceName.Translate);
     *
     * // Translation: "Created by {author}"
     * translator.get('my-addon.document.author', { author: undefined });
     * // Returns: "Created by "
     * ```
     */
    get(id: string, params?: Record<string, string | number | undefined>): string;
}