docpad-plugin-multilanguage v2.0.0

Multilanguage Plugin for DocPad

Supports developing websites with multiple languages

Basically an implementation of the methodology described here as a plugin

Install

docpad install multilanguage

Using

The plugin assumes that all documents for a certain language are organized in a directory of that language code.

The plugin will make docpad fail if some basic configuarations (the used languages and the defaultLanguage) are missing.

Global configuration

An example docpad.coffee-file looks like this:

docpadConfig = {
  plugins:
    multilanguage:
      languages: ["de","en"]
      defaultLanguage: "en"
      translation_files:
        de: "src/documents/de/de.json"
        en: "src/documents/en/en.json"
}

Available options are:

• languages: this required parameter is a list of the languages on the website
• defaultLanguage: the default language. Required
• translation_files: dictionary with the location of the translation files for the supported languages. If not set for a language a default location is used. The translation file has to exist (otherwise the plugin will fail)
• plural_types: dictionary of simple functions that determine whether for a number n the plural form is to be used for the language in question

Directory structure

It is assumed that for each directory a corresponding sub-directory of src/documents exists (for instance for language en a directory src/documents/en). All documents in that directory get a property lang added which is set to the language code.

Documents which are not found in a language directory get lang set to an empty string.

How translations for a page are determined

At first the meta-data of the page is searched for a dictionary multilanguage. 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 a page /de/testZwei.html if there is a header

---
title: "Zweite Testseite"
layout: "default"
isPage: true
multilanguage:
  en: testTwo.html
---

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

For languages that are unspecified it is assumed that the name (including the path without the language directory) of the translated page is the same (for instance the translation to fr for /de/testZwei.html is assumed to be /fr/testZwei.html). If no such page is found in the database then is is assumed that there is no translation of the current page to that language.

Injected template data

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

The functions are:

• _: Translation function. Will look up the key in the translation file for the current @document.lang and return result. Also does simple parameter subsititution. If the key is not found in the translation file then the defaultLanguage is used. An example: @_ 'The answer is', num: 42
• plural: Get the plural form depending on a number. Simple example: @plural(3, 'dog|dogs'). Example in context: @_ 'number of posts', num: documents.length, posts: @plural(documents.length, 'post|posts')
• date: Print the date of the article in a localized form. Takes several optional parameter: date to use a different date than the one of the article. 'lang' to use a different language. 'format' to use a different date format as specified by Moment.js
• computerDate: print date in a machine-readable form. Optional parameter date
• toLang: function that gets a language code as a parameter and returns the URL of the equivalent of the current page in that language (the translation of the current page). If there is no translation then a link to that language is returned
• hasLang: whether there actually is a translation of this page to a language
• otherLangs: dictionary with the other languages and their URLs that are available for this document
• langFromPath: Obtain current language from document path if @document.lang is not available. Using @document.lang is prefered for performance reasons. Optional parameter if @document is not the target
• pathWithoutLang: Get a path without current language. Maybe useful in templates to get a file path. Example : <%= @pathWithoutLang(post) %> Optional parameter if @document is not the target

The injected properties are:

• languages: List of the languages
• defaultLanguage: The default language

Injected document data

The data injected to the documents is

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

Generated collections

For every language a collection whose name is composed from lang_ and the language name is automatically created with all files that have this language. For instance for the language ru there is a collection lang_ru.

History

You can find the history in the History.md file

License

Licensed under the incredibly permissive MIT License

Copyright © 2015+ Bernhard F.W. Gschaider