export interface FallbackLngObjList {
[language: string]: string[];
}
export type FallbackLng = string | string[] | FallbackLngObjList | ((code:string) => string | string[] | FallbackLngObjList);
export type FormatFunction = (value: any, format?: string, lng?: string, options?: InterpolationOptions & { [key: string]: any }) => string;
export interface InterpolationOptions {
/**
* Format function see formatting for details
* @default noop
*/
format?: FormatFunction;
/**
* Used to separate format from interpolation value
* @default ','
*/
formatSeparator?: string;
/**
* Escape function
* @default str => str
*/
escape?(str: string): string;
/**
* Escape passed in values to avoid xss injection
* @default true
*/
escapeValue?: boolean;
/**
* If true, then value passed into escape function is not casted to string, use with custom escape function that does its own type check
* @default false
*/
useRawValueToEscape?: boolean;
/**
* Prefix for interpolation
* @default '{{'
*/
prefix?: string;
/**
* Suffix for interpolation
* @default '}}'
*/
suffix?: string;
/**
* Escaped prefix for interpolation (regexSafe)
* @default undefined
*/
prefixEscaped?: string;
/**
* Escaped suffix for interpolation (regexSafe)
* @default undefined
*/
suffixEscaped?: string;
/**
* Suffix to unescaped mode
* @default undefined
*/
unescapeSuffix?: string;
/**
* Prefix to unescaped mode
* @default '-'
*/
unescapePrefix?: string;
/**
* Prefix for nesting
* @default '$t('
*/
nestingPrefix?: string;
/**
* Suffix for nesting
* @default ')'
*/
nestingSuffix?: string;
/**
* Escaped prefix for nesting (regexSafe)
* @default undefined
*/
nestingPrefixEscaped?: string;
/**
* Escaped suffix for nesting (regexSafe)
* @default undefined
*/
nestingSuffixEscaped?: string;
/**
* Separates options from key
* @default ','
*/
nestingOptionsSeparator?: string;
/**
* Global variables to use in interpolation replacements
* @default undefined
*/
defaultVariables?: { [index: string]: any };
/**
* After how many interpolation runs to break out before throwing a stack overflow
* @default 1000
*/
maxReplaces?: number;
/**
* If true, it will skip to interpolate the variables
* @default false
*/
skipOnVariables?: boolean;
}
export interface ReactOptions {
/**
* Set to true if you like to wait for loaded in every translated hoc
* @default false
*/
wait?: boolean;
/**
* Set it to fallback to let passed namespaces to translated hoc act as fallbacks
* @default 'default'
*/
nsMode?: 'default' | 'fallback';
/**
* Set it to the default parent element created by the Trans component.
* @default 'div'
*/
defaultTransParent?: string;
/**
* Set which events trigger a re-render, can be set to false or string of events
* @default 'languageChanged'
*/
bindI18n?: string | false;
/**
* Set which events on store trigger a re-render, can be set to false or string of events
* @default ''
*/
bindI18nStore?: string | false;
/**
* Set fallback value for Trans components without children
* @default undefined
*/
transEmptyNodeValue?: string;
/**
* Set it to false if you do not want to use Suspense
* @default true
*/
useSuspense?: boolean;
/**
* Function to generate an i18nKey from the defaultValue (or Trans children)
* when no key is provided.
* By default, the defaultValue (Trans text) itself is used as the key.
* If you want to require keys for all translations, supply a function
* that always throws an error.
* @default undefined
*/
hashTransKey?(defaultValue: TOptionsBase['defaultValue']): TOptionsBase['defaultValue'];
/**
* Convert eg.
found in translations to a react component of type br
* @default true
*/
transSupportBasicHtmlNodes?: boolean;
/**
* Which nodes not to convert in defaultValue generation in the Trans component.
* @default ['br', 'strong', 'i', 'p']
*/
transKeepBasicHtmlNodesFor?: string[];
}
export interface InitOptions {
/**
* Logs info level to console output. Helps finding issues with loading not working.
* @default false
*/
debug?: boolean;
/**
* Resources to initialize with (if not using loading or not appending using addResourceBundle)
* @default undefined
*/
resources?: Resource;
/**
* Allow initializing with bundled resources while using a backend to load non bundled ones.
* @default false
*/
partialBundledLanguages?: boolean;
/**
* Language to use (overrides language detection)
* @default undefined
*/
lng?: string;
/**
* Language to use if translations in user language are not available.
* @default 'dev'
*/
fallbackLng?: false | FallbackLng;
/**
* DEPRECATED use supportedLngs
* @default false
*/
whitelist?: false | string[];
/**
* DEPRECTADED use nonExplicitSupportedLngs
* @default false
*/
nonExplicitWhitelist?: boolean;
/**
* Array of allowed languages
* @default false
*/
supportedLngs?: false | string[];
/**
* If true will pass eg. en-US if finding en in supportedLngs
* @default false
*/
nonExplicitSupportedLngs?: boolean;
/**
* Language codes to lookup, given set language is
* 'en-US': 'all' --> ['en-US', 'en', 'dev'],
* 'currentOnly' --> 'en-US',
* 'languageOnly' --> 'en'
* @default 'all'
*/
load?: 'all' | 'currentOnly' | 'languageOnly';
/**
* Array of languages to preload. Important on server-side to assert translations are loaded before rendering views.
* @default false
*/
preload?: false | string[];
/**
* Language will be lowercased eg. en-US --> en-us
* @default false
*/
lowerCaseLng?: boolean;
/**
* Language will be lowercased EN --> en while leaving full locales like en-US
* @default false
*/
cleanCode?: boolean;
/**
* String or array of namespaces to load
* @default 'translation'
*/
ns?: string | string[];
/**
* Default namespace used if not passed to translation function
* @default 'translation'
*/
defaultNS?: string;
/**
* String or array of namespaces to lookup key if not found in given namespace.
* @default false
*/
fallbackNS?: false | string | string[];
/**
* Calls save missing key function on backend if key not found
* @default false
*/
saveMissing?: boolean;
/**
* Experimental: enable to update default values using the saveMissing
* (Works only if defaultValue different from translated value.
* Only useful on initial development or when keeping code as source of truth not changing values outside of code.
* Only supported if backend supports it already)
* @default false
*/
updateMissing?: boolean;
/**
* @default 'fallback'
*/
saveMissingTo?: 'current' | 'all' | 'fallback';
/**
* Used for custom missing key handling (needs saveMissing set to true!)
* @default false
*/
missingKeyHandler?:
| false
| ((lngs: string[], ns: string, key: string, fallbackValue: string) => void);
/**
* Receives a key that was not found in `t()` and returns a value, that will be returned by `t()`
* @default noop
*/
parseMissingKeyHandler?(key: string): any;
/**
* Appends namespace to missing key
* @default false
*/
appendNamespaceToMissingKey?: boolean;
/**
* Gets called in case a interpolation value is undefined. This method will not be called if the value is empty string or null
* @default noop
*/
missingInterpolationHandler?: (text: string, value: any, options: InitOptions) => any;
/**
* Will use 'plural' as suffix for languages only having 1 plural form, setting it to false will suffix all with numbers
* @default true
*/
simplifyPluralSuffix?: boolean;
/**
* String or array of postProcessors to apply per default
* @default false
*/
postProcess?: false | string | string[];
/**
* passthrough the resolved object including 'usedNS', 'usedLang' etc into options object of postprocessors as 'i18nResolved' property
* @default false
*/
postProcessPassResolved?: boolean;
/**
* Allows null values as valid translation
* @default true
*/
returnNull?: boolean;
/**
* Allows empty string as valid translation
* @default true
*/
returnEmptyString?: boolean;
/**
* Allows objects as valid translation result
* @default false
*/
returnObjects?: boolean;
/**
* Gets called if object was passed in as key but returnObjects was set to false
* @default noop
*/
returnedObjectHandler?(key: string, value: string, options: any): void;
/**
* Char, eg. '\n' that arrays will be joined by
* @default false
*/
joinArrays?: false | string;
/**
* Sets defaultValue
* @default args => ({ defaultValue: args[1] })
*/
overloadTranslationOptionHandler?(args: string[]): TOptions;
/**
* @see https://www.i18next.com/interpolation.html
*/
interpolation?: InterpolationOptions;
/**
* Options for language detection - check documentation of plugin
* @default undefined
*/
detection?: object;
/**
* Options for backend - check documentation of plugin
* @default undefined
*/
backend?: object;
/**
* Options for cache layer - check documentation of plugin
* @default undefined
*/
cache?: object;
/**
* Options for i18n message format - check documentation of plugin
* @default undefined
*/
i18nFormat?: object;
/**
* Options for react - check documentation of plugin
* @default undefined
*/
react?: ReactOptions;
/**
* Triggers resource loading in init function inside a setTimeout (default async behaviour).
* Set it to false if your backend loads resources sync - that way calling i18next.t after
* init is possible without relaying on the init callback.
* @default true
*/
initImmediate?: boolean;
/**
* Char to separate keys
* @default '.'
*/
keySeparator?: false | string;
/**
* Char to split namespace from key
* @default ':'
*/
nsSeparator?: false | string;
/**
* Char to split plural from key
* @default '_'
*/
pluralSeparator?: string;
/**
* Char to split context from key
* @default '_'
*/
contextSeparator?: string;
/**
* Prefixes the namespace to the returned key when using `cimode`
* @default false
*/
appendNamespaceToCIMode?: boolean;
/**
* Compatibility JSON version
* @default 'v3'
*/
compatibilityJSON?: 'v1' | 'v2' | 'v3';
/**
* Options for https://github.com/locize/locize-editor
* @default undefined
*/
editor?: {
/**
* Enable on init without the need of adding querystring locize=true
* @default false
*/
enabled?: boolean;
/**
* If set to false you will need to open the editor via API
* @default true
*/
autoOpen?: boolean;
/**
* Enable by adding querystring locize=true; can be set to another value or turned off by setting to false
* @default 'locize'
*/
enableByQS?: string | false;
/**
* Turn on/off by pressing key combination. Combine this with `toggleKeyCode`
* @default 'ctrlKey'
*/
toggleKeyModifier?: 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey';
/**
* Turn on/off by pressing key combination. Combine this with `toggleKeyModifier`
* @default 24 (x)
*/
toggleKeyCode?: number;
/**
* Use lng in editor taken from query string, eg. if running with lng=cimode (i18next, locize)
* @default 'useLng'
*/
lngOverrideQS?: string;
/**
* Use lng in editor, eg. if running with lng=cimode (i18next, locize)
* @default null
*/
lngOverride?: string | null;
/**
* How the editor will open.
* Setting to window will open a new window/tab instead
* @default 'iframe'
*/
mode?: 'iframe' | 'window';
/**
* Styles to adapt layout in iframe mode to your website layout.
* This will add a style to the `