Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/danguilherme/docpad-plugin-polyglot

🌐 DocPad plugin for multilingual websites
https://github.com/danguilherme/docpad-plugin-polyglot

docpad docpad-plugin i18n multi-language

Last synced: 10 days ago
JSON representation

🌐 DocPad plugin for multilingual websites

Host: GitHub
URL: https://github.com/danguilherme/docpad-plugin-polyglot
Owner: danguilherme
License: other
Created: 2017-04-14T21:12:35.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2017-04-21T08:20:34.000Z (over 7 years ago)
Last Synced: 2024-10-10T23:10:52.507Z (about 1 month ago)
Topics: docpad, docpad-plugin, i18n, multi-language
Language: CoffeeScript
Homepage:
Size: 46.9 KB
Stars: 2
Watchers: 4
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md

Awesome Lists containing this project

README

# Polyglot Plugin for [DocPad](http://docpad.org)

Add multilanguage support for your site.

Heavily inspired and mostly based on [multilang](https://www.npmjs.com/package/docpad-plugin-multilang) and ~~the abandoned~~ [multilanguage](https://www.npmjs.com/package/docpad-plugin-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](https://www.w3.org/International/questions/qa-html-language-declarations), [ISO](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) or [IETF](https://en.wikipedia.org/wiki/IETF_language_tag).|
|**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:

```javascript
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:

```bash
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:

```bash
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](https://momentjs.com/) (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 `{ "": "" }`
- `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_` 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`.