roots-i18n

A naïve i18n extension for the Roots static site generator ecosystem.

This extension makes many assumptions. It is not (yet) a catch-all solution to i18n in Roots. However, within strict limitations, it can be considered production ready.

Installation

$ npm i --save-dev roots-i18n

Usage

Configuration

roots-i18n requires that your translations are saved as a local file in yaml format. Each language should be in a separate file. Your folder structure might look something like this:

root
 ├─ views
 ├─ assets
 ├─ i18n
 │   ├─ en.yaml
 │   └─ es.yaml
 ├─ app.coffee
 └─ ...

Each language file should be named using the 2-letter language code, as above. The contents of es.yaml might look like this:

dir: es/
lang: es

homepage:
  title: Inicio
  message: empezar aquí y elegir una categoría

login:
  title: iniciar sesión / inscribirse

faq:
  title: Preguntas Frecuentes

dashboard:
  title: Tu cuadro de mandos

  tabs:
    requests: Solicitudes
    quotes: Presupuestos
    jobs: Trabajos
    completed: Terminados

messaging:
  title: Mensajes

Those first 2 lines are not required for roots-i18n to work, but they can be useful in your view templates, explained below. dir is the name of the output subdirectory where the Spanish (for example) version of your website will be located.

The lang property is simply the 2-letter language code, the same as the filename.

Add roots-i18n to your extensions array as follows:

i18n = require 'roots-i18n'

module.exports =
  extensions: [
    # ...

    i18n(
      translations: 'i18n/*'
      viewExtension: 'jade'
      templatesGlob: ['request/**/*.html']
    )

    # ...
  ]

roots-i18n takes a configuration object with the following properties:

• translations: This is a globbing pattern that matches all your translation yaml files, explained above.
• viewExtension: This tells roots-i18n how to identify your view templates.
• templatesGlob: This property exists to play nicely with roots-records. If you're not using that extension, you can omit this property. If you are, this should be a globbing pattern (or an array of patterns) that identifies all your roots-records "single view templates".

roots-i18n assumes that the default language of your site is English, and places translated versions of the site in subdirectories named after the 2-letter language code, i.e. a Spanish homepage would be at example.com/es/, with the English homepage at example.com/. It only handles view templates – assets are untouched. roots-i18n assumes that all assets are non-language-specific, and are accessed at the root directory of your site.

Usage in your templates

roots-i18n exposes a mustache-esque syntax inside your templates. Here are some examples in jade, using the above es.yaml example file:

div.faq
  :marked
    ## {{ faq.title }}

- var tabs = ['requests', 'quotes', 'jobs', 'completed']

nav.dashboard-nav
  ul
    each tab in tabs
      li.check-tabs
        label
          input(
            type="radio",
            name="dashboard-nav",
            value= tab)
          span {{ dashboard.tabs.#{tab} }}

doctype html
html(lang='{{ lang }}')

a(href='/{{ dir }}') {{ homepage.title }}