@nextcloud/l10n/dist/index.d.ts

Nextcloud localization and translation helpers for apps and libraries

declare interface AppTranslations {
    translations: Translations;
    pluralFunction: PluralFunction;
}

/**
 * Extracts variables from a translation key
 */
declare type ExtractedVariables<T extends string> = T extends `${string}{${infer Variable}}${infer Rest}` ? Variable | ExtractedVariables<Rest> : never;

export declare interface FormatDateOptions {
    /**
     * If set then instead of showing seconds since the timestamp show the passed message.
     *
     * @default false
     */
    ignoreSeconds?: string | false;
    /**
     * The relative time formatting option to use
     *
     * @default 'long
     */
    relativeTime?: 'long' | 'short' | 'narrow';
    /**
     * Language to use
     *
     * @default 'current language'
     */
    language?: string;
}

/**
 * Format a given time as "relative time" also called "humanizing".
 *
 * @param timestamp Timestamp or Date object
 * @param opts Options for the formatting
 */
export declare function formatRelativeTime(timestamp?: Date | number, opts?: FormatDateOptions): string;

/**
 * Returns user's locale in canonical form
 * E.g. `en-US` instead of `en_US`
 */
export declare function getCanonicalLocale(): string;

/**
 * Get a list of day names (full names)
 */
export declare function getDayNames(): string[];

/**
 * Get a list of day names (minified names)
 */
export declare function getDayNamesMin(): string[];

/**
 * Get a list of day names (short names)
 */
export declare function getDayNamesShort(): string[];

/**
 * Get the first day of the week
 *
 * @return The first day where 0 is Sunday, 1 is Monday etc.
 */
export declare function getFirstDay(): WeekDay;

/**
 * Returns the user's language
 */
export declare function getLanguage(): string;

/**
 * Returns the user's locale
 */
export declare function getLocale(): string;

/**
 * Get a list of month names (full names)
 */
export declare function getMonthNames(): string[];

/**
 * Get a list of month names (short names)
 */
export declare function getMonthNamesShort(): string[];

/**
 * Get array index of translations for a plural form
 *
 * @param number - The number of elements
 * @param language - The language to use (or autodetect if not set)
 * @return 0 for the singular form(, 1 for the first plural form, ...)
 */
export declare function getPlural(number: number, language?: string): 0 | 1 | 2 | 3 | 4 | 5;

/**
 * Check whether the current, or a given, language is read right-to-left
 *
 * @param language Language code to check, defaults to current language
 */
export declare function isRTL(language?: string): boolean;

/**
 * Load an app's translation bundle if not loaded already.
 *
 * @param appName - Name of the app to load
 */
export declare function loadTranslations(appName: string): Promise<AppTranslations>;

/**
 * Load an app's translation bundle if not loaded already.
 *
 * @param appName - Name of the app to load
 * @param callback - Callback to be called when the translations are loaded
 * @deprecated Use the returned promise instead
 */
export declare function loadTranslations(appName: string, callback: (...args: []) => unknown): Promise<AppTranslations>;

/**
 * Function for getting plural form index from translated number
 *
 * @param number Input number to translate
 * @return Index of translation plural form
 * @example For most languages, like English or German
 * ```js
 (number:number) => number === 1 ? 0 : 1
 ```
 */
declare type PluralFunction = (number: number) => number;

/**
 * Register an app's translation bundle.
 *
 * @param appName name of the app
 * @param bundle translation bundle
 */
export declare function register(appName: string, bundle: Translations): void;

/**
 * Set the current user's language (locally).
 * This is to be used only for e.g. usage within web workers etc.
 *
 * @param lang - The new language code
 * @since 3.4.0
 */
export declare function setLanguage(lang: string): void;

/**
 * Set the current user's language (locally).
 * This is to be used only for e.g. usage within web workers etc.
 *
 * @param locale - The new language code
 * @since 3.4.0
 */
export declare function setLocale(locale: string): void;

declare function translate<T extends string>(app: string, text: T, placeholders?: TranslationVariables<T>, options?: TranslationOptions): string;

declare function translate<T extends string>(app: string, text: T, number?: number, options?: TranslationOptions): string;

/**
 * @inheritdoc
 * @deprecated This overload is deprecated either use placeholders or a number but not both
 */
declare function translate<T extends string>(app: string, text: T, placeholders?: TranslationVariables<T>, number?: number, options?: TranslationOptions): string;
export { translate as t }
export { translate }

/**
 * Translate a string containing an object which possibly requires a plural form
 *
 * @param app - The id of the app for which to translate the string
 * @param textSingular - The string to translate for exactly one object
 * @param textPlural - The string to translate for n objects
 * @param number - Number to determine whether to use singular or plural
 * @param vars - Mapping of placeholder key to value
 * @param options - Options object
 */
declare function translatePlural<T extends string, K extends string>(app: string, textSingular: T, textPlural: K, number: number, vars?: TranslationVariables<T> & TranslationVariables<K>, options?: TranslationOptions): string;
export { translatePlural as n }
export { translatePlural }

declare interface TranslationOptions {
    /** enable/disable auto escape of placeholders (by default enabled) */
    escape?: boolean;
    /** enable/disable sanitization (by default enabled) */
    sanitize?: boolean;
    /**
     * This is only intended for internal usage.
     *
     */
    bundle?: AppTranslations;
}

/**
 * Translation bundle
 *
 * @example For German translation
 * ```json
 {
 "some": "einige",
 "_%n tree_::_%n trees_": [
 "%n Baum",
 "%n Bäume"
 ]
 }
 ```
 */
export declare type Translations = Record<string, string | string[] | undefined>;

declare interface TranslationVariableReplacementObject<T> {
    /** The value to use for the replacement */
    value: T;
    /** Overwrite the `escape` option just for this replacement */
    escape: boolean;
}

declare type TranslationVariables<K extends string> = Record<ExtractedVariables<K>, string | number | TranslationVariableReplacementObject<string | number>>;

/**
 * Unregister all translations of an app
 *
 * @param appName name of the app
 * @since 2.1.0
 */
export declare function unregister(appName: string): void;

export declare type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6;

export { }