Polyglot Plugin for DocPad

Add multilanguage support for your site.

Heavily inspired and mostly based on multilang and the abandoned multilanguage plugins.

Install

Install this DocPad plugin by entering docpad install polyglot into your terminal.

Configuration

Config	Default	Description
mainLanguage	(required)	The main language of the website. There is no specific format, but it is recommended to use some language code pattern, like IANA, ISO or IETF.
languages	(required)	The languages the website will be translated into.
omitMainFolder	true	Whether the main language files should be in the root of the website or have its own folder.

Usage

Configuration

Add the necessary configuration into docpad.js:

plugins: {
  polyglot: {
    mainLanguage: "pt-br",
    languages: ["pt-br", "en"]
  }
}

Directory Structure

As omitMainFolder is true by default, only languages different from mainLanguage need to be inside its own folder:

project-folder
└─src/
  └─documents/
    ├─index.html # home in brazilian portuguese
    ├─sobre.html # brazilian portuguese
    └─en/ # all in english
      ├─index.html
      └─about.html

The generated URLs would be:

/index.html
/sobre.html
/en/index.html
/en/about.html

However, if omitMainFolder is false, each file must be inside its language folder, even for the main language:

project-folder
└─src/
  └─documents/
    ├─en/ # all in english
    │ ├─index.html
    │ └─about.html
    └─pt-br/ # all in brazilian portuguese
      ├─index.html
      └─sobre.html

The generated URLs would be:

/pt-br/index.html
/pt-br/sobre.html
/en/index.html
/en/about.html

How translations for a page are determined

At first the metadata of the page is searched for a dictionary named translations. In this dictionary if there are entries with the language keys then it is assumed that these pages are the translation of the current page. For instance for the page /postagem-poliglota.html, if there is a header

---
title: "Sobre"
layout: "default"
translations:
  en: about.html
---

then /en/about.html is assumed to be the translation to en of this page.

Note that the dictionary value (about.html) doesn't have any additional extension (eg. .html.md). It's only necessary to put the final extension in it.

For languages that are not specified with the translations dictionary, it is assumed that the name (including the path without the language directory) of the translated page is the same. In the above example, the file /en/sobre.html would be assumed as the en translation. If no such page is found in the database then it is assumed that there is no translation of the current page to that language.

Injected template data

The plugin injects some properties and functions into the template data so that they can be used in the template.

The functions are:

• date({ date, format, lang }): Print the date of the article in a localized form. Takes several optional parameter: date and lang to use different values than the ones of the document. format to use a different date format as specified by Moment.js (defaults to LL).
• hasLang(lang): Whether there is a translation of the current page to that language.
• toLang(lang): Receives a language code as parameter and returns the URL of the translation of the current page. If there is no translation, it returns undefined.
• otherLangs(): Dictionary with the other languages and their URLs that are available for this document. The object structure is { "<language>": "<translation URL>" }
• langFromUrl(url): Allow to obtain current language from URL if @document.lang isn't available. Using @document.lang is prefered for performance.

The properties are:

• mainLanguage: The main language, set on config
• languages: List of the languages, set on config

Template data in use

Using the example defined above, if we wrote the following code into /en/about.html.eco:

- Lang: <%= @document.lang %>
- Lang from URL: <%= @langFromUrl(@document.url) %>
- Translation: <%= @toLang('pt-br') %>
- Has Portuguese: <%= @hasLang('pt-br') %>
- Has English: <%= @hasLang('en') %>
- Other languages: <%= JSON.stringify(@otherLangs()) %>

We would see the following output:

- Lang: en
- Lang from URL: en
- Translation: /sobre.html
- Has Portuguese: true
- Has English: true
- Other languages: { "pt-br": "/sobre.html" }

Injected document data

Properties are also injected into each document. They are:

• lang: The language of the document.
• translationURLs: Dictionary with all translations to the current page (including itself). Probably unnecessary with the functions in the template data.

Generated collections

For every language, a collection whose name is composed from lang_<language> is automatically created containing all files that have this language. For instance for the language pt-br there is a collection named lang_pt-br.

History

Discover the release history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

• Guilherme Ventura — view contributions

Sponsors

No sponsors yet! Will you be the first?

Contributors

These amazing people have contributed code to this project:

• Guilherme Ventura — view contributions
• Benjamin Lupton — view contributions
• Michael Duane Mooring — view contributions
• Rob Loach — view contributions
• vsopvsop — view contributions

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

License

Unless stated otherwise all works are:

• Copyright © Guilherme Ventura

and licensed under:

• MIT License