matrix-react-sdk/lib/src/languageHandler.d.ts

SDK for matrix.org using React

import React from "react";
import { TranslationKey as _TranslationKey } from "matrix-web-i18n";
import { TranslationStringsObject } from "@matrix-org/react-sdk-module-api";
import type Translations from "./i18n/strings/en_EN.json";
export { normalizeLanguageKey, getNormalizedLanguageKeys } from "matrix-web-i18n";
export interface ErrorOptions {
    cause: unknown | undefined;
}
/**
 * Used to rethrow an error with a user-friendly translatable message while maintaining
 * access to that original underlying error. Downstream consumers can display the
 * `translatedMessage` property in the UI and inspect the underlying error with the
 * `cause` property.
 *
 * The error message will display as English in the console and logs so Element
 * developers can easily understand the error and find the source in the code. It also
 * helps tools like Sentry deduplicate the error, or just generally searching in
 * rageshakes to find all instances regardless of the users locale.
 *
 * @param message - The untranslated error message text, e.g "Something went wrong with %(foo)s".
 * @param substitutionVariablesAndCause - Variable substitutions for the translation and
 * original cause of the error. If there is no cause, just pass `undefined`, e.g { foo:
 * 'bar', cause: err || undefined }
 */
export declare class UserFriendlyError extends Error {
    readonly translatedMessage: string;
    constructor(message: TranslationKey, substitutionVariablesAndCause?: Omit<IVariables, keyof ErrorOptions> | ErrorOptions);
}
export declare function getUserLanguage(): string;
/**
 * A type representing the union of possible keys into the translation file using `|` delimiter to access nested fields.
 * @example `common|error` to access `error` within the `common` sub-object.
 * {
 *     "common": {
 *         "error": "Error"
 *     }
 * }
 */
export type TranslationKey = _TranslationKey<typeof Translations>;
export declare function _td(s: TranslationKey): TranslationKey;
/**
 * The value a variable or tag can take for a translation interpolation.
 */
type SubstitutionValue = number | string | React.ReactNode | ((sub: string) => React.ReactNode);
export interface IVariables {
    count?: number;
    [key: string]: SubstitutionValue;
}
export type Tags = Record<string, SubstitutionValue>;
export type TranslatedString = string | React.ReactNode;
export declare function _t(text: TranslationKey, variables?: IVariables): string;
export declare function _t(text: TranslationKey, variables: IVariables | undefined, tags: Tags): React.ReactNode;
/**
 * Utility function to look up a string by its translation key without resolving variables & tags
 * @param key - the translation key to return the value for
 */
export declare function lookupString(key: TranslationKey): string;
export declare function _tDom(text: TranslationKey, variables?: IVariables): TranslatedString;
export declare function _tDom(text: TranslationKey, variables: IVariables, tags: Tags): React.ReactNode;
/**
 * Sanitizes unsafe text for the sanitizer, ensuring references to variables will not be considered
 * replaceable by the translation functions.
 * @param {string} text The text to sanitize.
 * @returns {string} The sanitized text.
 */
export declare function sanitizeForTranslation(text: string): string;
export declare function substitute(text: string, variables?: IVariables): string;
export declare function substitute(text: string, variables: IVariables | undefined, tags: Tags | undefined): string;
/**
 * Replace parts of a text using regular expressions
 * @param text - The text on which to perform substitutions
 * @param mapping - A mapping from regular expressions in string form to replacement string or a
 * function which will receive as the argument the capture groups defined in the regexp. E.g.
 * { 'Hello (.?) World': (sub) => sub.toUpperCase() }
 *
 * @return a React <span> component if any non-strings were used in substitutions, otherwise a string
 */
export declare function replaceByRegexes(text: string, mapping: IVariables): string;
export declare function replaceByRegexes(text: string, mapping: Tags): React.ReactNode;
export declare function setMissingEntryGenerator(f: (value: string) => void): void;
export declare function setLanguage(preferredLangs: string | string[]): Promise<void>;
type Language = {
    value: string;
    label: string;
    labelInTargetLanguage: string;
};
export declare function getAllLanguagesFromJson(): Promise<string[]>;
export declare function getAllLanguagesWithLabels(): Promise<Language[]>;
export declare function getLanguagesFromBrowser(): readonly string[];
export declare function getLanguageFromBrowser(): string;
export declare function getCurrentLanguage(): string;
/**
 * Given a list of language codes, pick the most appropriate one
 * given the current language (ie. getCurrentLanguage())
 * English is assumed to be a reasonable default.
 *
 * @param {string[]} langs List of language codes to pick from
 * @returns {string} The most appropriate language code from langs
 */
export declare function pickBestLanguage(langs: string[]): string;
export declare class CustomTranslationOptions {
    static lookupFn?: (url: string) => TranslationStringsObject;
    private constructor();
}
/**
 * Any custom modules with translations to load are parsed first, followed by an
 * optionally defined translations file in the config. If no customization is made,
 * or the file can't be parsed, no action will be taken.
 *
 * This function should be called *after* registering other translations data to
 * ensure it overrides strings properly.
 */
export declare function registerCustomTranslations({ testOnlyIgnoreCustomTranslationsCache, }?: {
    testOnlyIgnoreCustomTranslationsCache?: boolean;
}): Promise<void>;