Older version

You're reading the docs for v3 (3.0.x). The latest version is v4.

Read the v4 guide · Migrate from v3 to v4 · Versions & upgrading

Internationalization (i18n)

Send locale-specific email templates based on user language preferences.

Configuration

Add i18n options to your module configuration:

MailerModule.forRoot({
  transport: { host: 'smtp.example.com', port: 587 },
  template: {
    dir: join(__dirname, 'templates'),
    adapter: new HandlebarsAdapter(),
  },
  i18n: {
    defaultLocale: 'en',
    templateDirPattern: '{{locale}}/',
    fallback: true,
  },
})

Directory Structure

Organize your templates by locale:

templates/
  en/
    welcome.hbs
    reset-password.hbs
  es/
    welcome.hbs
    reset-password.hbs
  fr/
    welcome.hbs

Sending Localized Emails

Pass the locale option in sendMail():

// Sends using templates/es/welcome.hbs
await this.mailerService.sendMail({
  to: 'user@example.com',
  subject: 'Bienvenido',
  template: 'welcome',
  locale: 'es',
  context: { name: 'Juan' },
});

Fallback Behavior

When fallback: true (default), if a template doesn't exist for the requested locale, the system falls back to defaultLocale:

// templates/fr/reset-password.hbs doesn't exist
// Falls back to templates/en/reset-password.hbs
await this.mailerService.sendMail({
  to: 'user@example.com',
  template: 'reset-password',
  locale: 'fr',
  context: { resetLink: 'https://...' },
});

Custom Pattern

The templateDirPattern controls how locale maps to the directory structure:

// Default: '{{locale}}/' → templates/es/welcome.hbs
// Custom:  '{{locale}}-templates/' → templates/es-templates/welcome.hbs
i18n: {
  defaultLocale: 'en',
  templateDirPattern: '{{locale}}-templates/',
}

TIP

• Works with all template adapters (Handlebars, Pug, EJS, Nunjucks, Liquid, MJML)
• If no locale is provided, the template is resolved normally (no i18n prefix)
• Set fallback: false to throw an error when a locale template is missing