Interpolation

Interpolation is one of the most used functionalities in I18N. It allows integrating dynamic values into your translations.

Per default, interpolation values get escaped to mitigate XSS attacks.

🎓 Check out this topic in the i18next crash course video.

If the interpolation functionality provided doesn't suit you, you can use i18next-sprintf-postProcessor for sprintf supported interpolation.

Basic

Interpolation is one of the most used functionalities in I18N.

Keys

Keys, by default, are strings surrounded by curly brackets:

{
    "key": "{{what}} is {{how}}"
}

Sample

i18next.t('key', { what: 'i18next', how: 'great' });
// -> "i18next is great"

Working with data models

You can also pass entire data models as a value for interpolation.

Keys

{
    "key": "I am {{author.name}}"
}

Sample

const author = { 
    name: 'Jan',
    github: 'jamuhl'
};
i18next.t('key', { author });
// -> "I am Jan"

Unescape

By default, the values get escaped to mitigate XSS attacks. You can toggle escaping off, by either putting - before the key, or set the escapeValue option to false when requesting a translation.

Keys

{
    "keyEscaped": "no danger {{myVar}}",
    "keyUnescaped": "dangerous {{- myVar}}"
}

Sample

i18next.t('keyEscaped', { myVar: '<img />' });
// -> "no danger &lt;img &#x2F;&gt;"

i18next.t('keyUnescaped', { myVar: '<img />' });
// -> "dangerous <img />"

i18next.t('keyEscaped', { myVar: '<img />', interpolation: { escapeValue: false } });
// -> "no danger <img />" (obviously could be dangerous)

Warning: If you toggle escaping off, escape any user input yourself!

Additional options

Prefix/Suffix for interpolation and other options can be overridden in the init options or by passing additional options to the t function:

i18next.init({
    interpolation: { ... }
});

i18next.t('key', {
    interpolation: { ... }
});
optiondefaultdescription

escape

function

escape function function escape(str) { return str; }

escapeValue

true

escapes passed in values to avoid XSS injection

useRawValueToEscape

false

If true, then value passed into escape function is not casted to string, use with custom escape function that does its own type-checking

prefix

"{{"

prefix for interpolation

suffix

"}}"

suffix for interpolation

While there are a lot of options going with the defaults should get you covered.

All interpolation options

optiondefaultdescription

format

noop function

format function, read formatting for details

formatSeparator

","

used to separate format from interpolation value

escape

function

escape function function escape(str) { return str; }

escapeValue

true

escape passed in values to avoid XSS injection

useRawValueToEscape

false

If true, then value passed into escape function is not casted to string, use with custom escape function that does its own type-checking

prefix

"{{"

prefix for interpolation

suffix

"}}"

suffix for interpolation

prefixEscaped

undefined

escaped prefix for interpolation (regexSafe)

suffixEscaped

undefined

escaped suffix for interpolation (regexSafe)

unescapeSuffix

undefined

suffix to unescaped mode

unescapePrefix

"-"

prefix to unescaped mode

nestingPrefix

"$t("

prefix for nesting

nestingSuffix

")"

suffix for nesting

nestingPrefixEscaped

undefined

escaped prefix for nesting (regexSafe)

nestingSuffixEscaped

undefined

escaped suffix for nesting (regexSafe)

nestingOptionsSeparator

","

separates the options from nesting key

defaultVariables

undefined

global variables to use in interpolation replacements defaultVariables: { key: "value" }

maxReplaces

1000

after how many interpolation runs to break out before throwing a stack overflow

skipOnVariables

true

(was false for <v21.0.0)

Will skip to interpolate the variables, example:

t('key', { a: '$t(nested)' })

this will not resolve the nested key and will use$t(nested) as the variable value. Another example:

t('key', { a: '{{otherVar}}': otherVar: 'another value' })

this will not resolve the otherVar variable and will use{{otherVar}}as the variable value.

If your interpolation variables are user provided or loaded from an external source, we strongly suggest to keep this option to true.

If you know what you're doing, you can also set this to false.

Implications for localization

Checkout the best practices on this topic.

Last updated