Documentation Enhancement Request

[jensenbox]

Hi,

I would be happy to write up docs on how to to internationalization but would prefer to get the "blessed" way to do it. The old-school .po files are great but all the cool kids appear to be using i18next - if there is an official stance on what to use, I can certainly take a stab at writing up how to do it.

Thanks!

[cossssmin]

This would have to be a Guide, so feel free to write one for the method you prefer. i18next does look good and I'd probably go with something like that since it's JavaScript 👍

[rafcontreras]

@jensenbox do you have i18n on your maizzle build?

[drevets]

@jensenbox curious if you were able to solve this! About to embark on i18n with Maizzle myself soon.

[nickdirienzo]

Not sure if I should be reviving an old thread, but this is something I'm starting to think about. I'm a fairly new Maizzle user (and it's quite nice, so thank you!). Has anyone found a pattern that's worked well for their teams for generating multi-lang email templates based on i18next? I'd love to learn from prior art if it exists.

[priithansen]

Turns out getting i18next to play nicely with Maizzle is quite simple thanks to the flexible event system.
See priithansen/maizzle-localize@8de9e0b?diff=unified as example for trivial changes needed to get started.

// config.js

const i18next = require('i18next')

module.exports = {
  lang: 'en', // Use as fallback if nothing specified with env
  t: i18next.t, // Make i18next translate function available in templates as {{ page.t() }}
  build: {
    ....
  },
  events: {
    beforeCreate: async (config) => {
      const fallbackLng = config.lang

      if (process.env.MAIZZLE_TEMPLATE_LANG) {
        config = Object.assign(config, { 
          lang: process.env.MAIZZLE_TEMPLATE_LANG 
        })
      }

      // Await is important here to not let build advance before i18next has had time to finish initialization.
      await i18next.init({
        lng: config.lang,
        fallbackLng,
        debug: false,
        resources: { // Inlined just to simplify example.
          en: {
            translation: {
              "hello": "Hello {{name}}!",
            },
          },
          et: {
            translation: {
              "hello": "Tere {{name}}!",
            },
          },
        },
      })
    },
  },
}

With that hook it's now possible to use env variable to specify which language you want to build the templates in ex:

MAIZZLE_TEMPLATE_LANG=et npm run dev

I used env variable because there doesn't seem to be a way to pass arbitrary configuration parameters to maizzle cli and also I could not figure out a way to make a single call to maizzle buid to generate multiple locales at once. Anyhow between npm script/bin options, custom scripts and CI systems there are probably a gazillion ways to drive the process of calling maizzle with appropriate locales.

--

For my use case I used config.production.js to further customise the build process with changing the config.permalink param in beforeRender hook to separate files by language and build needed meta.json for Postmark template sync.

One catch I struggled with and solution I came up with that might come handy for someone trying to implement i18n was, how to get translated strings back to config.

At first I tried to use front matter to specify for example name & subject for my Postmark sync job and later read them in the beforeRender hook.

---
name: "Example template"
subject: "{{ page.t('hello', { name: 'Jim' })  }}"
---

Problem with this approach is that while you can use these as variables (ex: {{ page.subject }}) in your the templates just fine. They are not interpolated when accessed in the event hooks from the config object.

events: {
  beforeRender: async (html, config) => {
    config.subject // Is still  just a string containing exactly "{{ page.t('hello', { name: 'Jim' }) }}" which is no good for us here.
 
    return html
},

So a hacky solution I came up with was to use a "fake" component that does not render anything in itself but calls out needed function to handle for me permalink renaming and Postmark variables.

// config.production.js

events: {
  beforeRender: async (html, config) => {
    // Define function we can call from template.
    config.postmark = (name, subject) => { // name & subject variables passed from component have now been transpiled same as if we would have used them in the template.
      const path = config.build.current.path
      const alias = `${path.name}--${config.lang}` // Use "lang" defined in beforeCreate event to differentiate results by language.
      const destPath = `${path.dir}/${alias}`

      config.permalink = `${destPath}/content${path.ext}` // Use permalink to override where Maizzle will copy the final build artefacts so it matches the file structure Postmark is expecting.

      // buildMetaFile(name, subject, alias, destPath) Any other custom logic as needed.

      return '' // Make sure to return empty string to avoid "undefined" in rendering in template.
    }

    return html
  },
},

# components/postmark.html

<script props>
  module.exports = {
    name: props.name,
    subject: props.subject,
  }
</script>
{{ page.postmark ? page.postmark(name, subject) : '' }}

So armed with this I can now use the <x-postmark /> component and specify the needed props I need for updating the config at build time.

# templates/example.html

<x-postmark
  name="Example ({{ page.lang }})"
  subject="{{ page.t('hello', { name: 'Jim' })  }}"
/>
<x-main>
  ....
</x-main>

This seems to do the trick of transpiling the subject property in template before assigning it to config value in postmark() function.

Sorry this got so long but wanted to put it out there to maybe help someone in a similar situation or inspire a better less hacky solutions that might grow out of it.