Nothing Particularly Magnificent


    1.0.3 • Public • Published


    npm npm version

    Handlebars helper that lets you translate with i18next inside your templates.

    New! Need to automatically collect the {{i18n}} tags from your Handlebars templates for your translation JSON? Look no further than our sister package handlebars-i18next-parser.



    $ npm i handlebars-i18next

    Glue code

    import Handlebars from 'handlebars';  // runtime also possible
    import i18next from 'i18next';
    import registerI18nHelper from 'handlebars-i18next';
    // Prepare your i18next instance (can be a custom instance)
        resources: {
            en: {
                translation: {
                    greeting: 'Hello, {{name}}!',
            fr: {...},
    }, function(error, t) {
        // Once this callback is called, you can start rendering templates
        // that depend on the helper (if `error` is undefined).
    registerI18nHelper(Handlebars, i18next);


    {{i18n 'greeting'}}

    Template call

    template({name: 'Alice'});


    Hello, Alice!

    Properties in the context of the helper are automatically available as interpolation values to i18next. It just works!

    Advanced usage

    Block helper: templated default value

    You can use the helper as a section. The nested template block will be rendered as usual with the same context and passed to i18next.t as the defaultValue option.

    {{#i18n 'greeting'}}Please be welcome, {{name}}!{{/i18n}}

    So if the greeting key is not found in any of the selected languages in the current namespace, this will be rendered:

    Please be welcome, Alice!

    Otherwise, the following or one of its translations.

    Hello, Alice!

    Providing explicit interpolation values

    You can pass an i18next.replace property in the root context of the template call in order to provide interpolation values for all helpers in the template.

        name: Alice,
        i18next: {
            replace: {
                name: 'Bob',

    will result in

    Hello, Bob!

    You can also pass arbitrary keyword arguments to the helper. These will be passed as options to i18next.t and be available as interpolation values.

    {{i18n 'greeting' name='Cynthia'}}

    will result in

    Hello, Cynthia!

    Keyword arguments take precedence over root.i18next.replace, which in turn takes precedence over the current context of the helper.

    Passing other options to i18next.t

    See the i18next documentation for available options.

    In order to provide default options for all occurrences of the helper in your template, pass the options hash as the i18next property of the root context to the template call.

    template({name: 'Alice', i18next: {
        lng: 'fr',
        interpolate: {...},

    In order to override options for a single occurrence of the helper, pass them directly as keyword arguments to the helper.

    {{i18n 'greeting' lng='fr' interpolate='{...}'}}

    Some notes:

    • The options lngs, fallbackLng, ns, postProcess and interpolation must be JSON-encoded strings when passed as keyword arguments.
    • The returnObjects option is forced to be false, since Handlebars helpers must return a string. You can pass another value, but it will be ignored.
    • The replace option is not supported as keyword argument. Pass the interpolation values individually as keyword arguments instead, as described in the previous section.

    Changing the name of the helper

    You can override the helper name by passing the name of your choice as the optional third argument to the exported helper registering function.

    import registerI18nHelper from 'handlebars-i18next';
    // ...
    registerI18nHelper(Handlebars, i18next, 't');
    {{t 'greeting'}}

    Made by

    Digital Humanities Lab


    npm i handlebars-i18next

    DownloadsWeekly Downloads






    Unpacked Size

    12.1 kB

    Total Files


    Last publish


    • jgonggrijp
    • dhl-uu-bis