No release in over a year
A Jekyll theme plugin to generate JSON dictionaries for language learning applications
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

>= 0
~> 2.5
 Project Readme

Jekyll Dictionaries Plugin

Continuous Integration Gem Version

Welcome to the Jekyll Dictionaries Plugin project! This open-source project allows you to create and share JSON dictionaries that can be accessed via a public API for language learning in mobile applications.

Table of Contents

  • Intro
  • Installation
  • Dictionaries Structure
  • Dictionary Types
    • 1. Single Translation Dictionary
    • 2. Multiple Translations Dictionary
  • Object Properties
    • 1. Dictionary Object
    • 2. Collection Object
    • 3. Folder Object
  • Dictionary Types Examples
    • 1. Single Translation Dictionary Example
    • 2. Multiple Translations Dictionary Example
  • Push New Version Commands
  • License

Intro

The plugin will automatically generate dictionary and dictionary api pages for all dictionaries located into folder _data/dictionaries of jekyll project.

Installation

  1. Add this line to your site's Gemfile:
gem 'jekyll-dictionaries'
  1. Include dictionary/head.html into default layout to add custom styles of the plugin (the plugin styles are added as inline css styles and it might be updated if it's needed):
<head>
  ...
   {% include dictionaries/head.html %}
</head>
  1. Include dictionaries/list.html into index page to show a list of available dictionaries:
  {% include dictionaries/list.html %}
  1. (OPTIONAL) Also it's possible to change layout and permalink of dictionary pages on site's _config.yml:
dictionaries:
  pages:
    dictionary:
      layout: dictionary
      permalink: dictionaries/:name
    dictionary_api:
      layout: dictionary_api
      permalink: api/dictionaries/:name.json

Dictionaries Structure

The dictionaries in this project have a specific structure that consists of the following components:

Root Directory

The root directory for dictionaries is _data/dictionaries. It contains JSON files that start with an underscore _ as well as folders that have names similar to the files but without the underscore. These folders act as containers for dictionary collections and can be nested.

Collection Files

  1. Any JSON File: Any JSON file within a folder is detected as a collection file. A collection file is a JSON object that can be used to set translations.

  2. "_metadata.json" (Optional): This file can be added inside nested folders to set folder details for the API. If this file is missing, the folder name will be used as the container name for the dictionaries in the API response. For example, if there is a folder named "greetings," and a developer wants to use a specific name for the folder in the API, they can add the file "_metadata.json" into the folder with data {"name": "Greetings"}. As a result, the plugin will generate an API where the folder name will be "Greetings."

Dictionary Types

This project supports two types of dictionaries:

1. Single Translation Dictionary

A "single translation" dictionary is used to generate a dictionary for a selected learning language, with translations available in any other languages. The JSON structure for a "single translation" dictionary and its collections is as follows:

_data/dictionaries/_single_dictionary.json:

{
    "version": "1.0.0",
    "name": "Simple",
    "translationType": "single",
    "learning": "es"
}

In this example, the learning language is set on the dictionary data with the "learning" field (using ISO 639-1 language codes).

_data/dictionaries/single_dictionary/greetings.json:

{
    "name": "Greetings",
    "type": "collection",
    "data": [
        {"learning":"¡Hola!", "primary":"Hello!"},
        {"learning":"¡Buenos días!", "primary":"Good morning!", "notes": {"learning": "por la mañana", "primary": "at morning"}}
    ]
}

The collection contains an array property "data" with word translations. In this case, the learning language is specified for each translation entry, while the "primary" field represents the translation in the target language. Additionally, you can include "notes" related to learning and translations.

2. Multiple Translations Dictionary

A "multiple translation" dictionary is used to generate a dictionary with multiple translations available simultaneously. The JSON structure for a "multiple translation" dictionary and its collections is as follows:

_data/dictionaries/_multiple_dictionary.json:

{
    "version": "1.0.0",
    "name": "Simple",
    "translationType": "multiple",
    "learning": "es",
    "translations":  ["en", "ru"]
}

In this example, the learning language is set on the dictionary data with the "learning" field (using ISO 639-1 language codes). Multiple translation types are specified in the "translations" property (using ISO 639-1 language codes).

_data/dictionaries/multiple_dictionary/greetings.json:

{
    "name": "Greetings",
    "type": "collection",
    "data": [
        {"learning":"¡Hola!", "en":"Hello!", "ru": "Привет!"},
        {"learning":"¡Buenos días!", "en":"Good morning!", "ru":"Доброе утро!",  "notes": {"learning": "por la mañana", "en": "at morning", "ru": "говорят по утрам"}}
    ]
}

The collection contains an array property "data" with word translations. Each translation entry includes the learning language and multiple translations specified in the "translations" property. Additionally, you can include "notes" related to learning and translations for each entry.

Object Properties

1. Dictionary Object

The dictionary object is a JSON object with the following properties:

Property Type Description
name string The name of the dictionary. (Required)
translationType string The type of translation ("single" or "multiple"). (Required)
learning string The learning language code, related to ISO 639-1 language codes. (Required) ISO 639-1 Language Codes
version string The version of the dictionary. (Optional)
translations array An array of ISO 639-1 language codes (required if translationType is "multiple").

2. Collection Object

The collection object is a JSON object with the following properties based on the translationType of the dictionary:

If translationType is "single":

Property Type Description
type string The type of the collection ("folder"). (Required)
learning string The learning word or phrase. (Required)
primary string The primary translation. (Required)
notes object Additional notes related to learning and translation (Optional). - learning: Additional notes related to the learning word/phrase (string). - primary: Additional notes related to the primary translation (string).

If translationType is "multiple":

Property Type Description
type string The type of the collection ("folder"). (Required)
learning string The learning word or phrase. (Required)
Properties for each translations of related dictionary string Properties for each translations of related dictionary, all of which are required.
notes object Additional notes related to learning and translations (Optional). - learning: Additional notes related to the learning word/phrase (string). - Properties for each translation type: Additional notes related to each translation type (string).

3. Folder Object

The _metadata.json file is used to set the folder name on the API response and contains the following property:

Property Type Description
name string The name to be used as the folder name in the API response. (Optional, if missing, the folder name will be used.)

Dictionary Types Examples

1. Single Translation Dictionary Example

Folder Structure

_data/dictionaries/_single.json
_data/dictionaries/single/greetings.json
_data/dictionaries/single/unit1/numbers.json

_data/dictionaries/_single.json:

{
    "version": "1.0.0",
    "name": "Basic (One Language)",
    "translationType": "single",
    "learning": "es"
}

_data/dictionaries/single/greetings.json:

{
    "name": "Greetings",
    "type": "collection",
    "data": [
        {"learning":"¡Hola!", "primary":"Hello!"}
    ]
}

_data/dictionaries/single/unit1/numbers.json:

{
    "type": "collection",
    "data": [
        {
            "primary": "one",
            "learning": "uno"
        },
        {
            "primary": "two",
            "learning": "dos"
        },
        {
            "primary": "three",
            "learning": "tres"
        },
        {
            "primary": "four",
            "learning": "cuatro"
        },
        {
            "primary": "five",
            "learning": "cinco"
        },
        {
            "primary": "six",
            "elearnings": "seis"
        },
        {
            "primary": "seven",
            "learning": "siete"
        },
        {
            "primary": "eight",
            "learning": "ocho"
        },
        {
            "primary": "nine",
            "learning": "nueve"
        },
        {
            "primary": "ten",
            "learning": "diez"
        }
    ]
}

The plugin will generate JSON API /api/dictionaries/single.json

{"docUrl":"http://example.org/dictionaries/single","version":"1.0.0","name":"Basic (One Language)","translationType":"single","learning":"es","data":[{"name":"Greetings","type":"collection","data":[{"learning":"¡Hola!","primary":"Hello!"}]},{"type":"folder","name":"unit1","data":[{"name":"numbers","type":"collection","data":[{"primary":"one","learning":"uno"},{"primary":"two","learning":"dos"},{"primary":"three","learning":"tres"},{"primary":"four","learning":"cuatro"},{"primary":"five","learning":"cinco"},{"primary":"six","elearnings":"seis"},{"primary":"seven","learning":"siete"},{"primary":"eight","learning":"ocho"},{"primary":"nine","learning":"nueve"},{"primary":"ten","learning":"diez"}]}]}]}

2. Multiple Translations Dictionary Example

Folder Structure

_data/dictionaries/_multiple.json
_data/dictionaries/multiple/greetings.json
_data/dictionaries/multiple/unit1/_metadata.json
_data/dictionaries/multiple/unit1/numbers.json

_data/dictionaries/_multiple.json:

{
    "version": "1.0.0",
    "name": "Basic (Multiple Languages)",
    "translationType": "multiple",
    "learning": "es",
    "translations": [
        "en", "ru", "de", "fr", "pt"
    ]
}

_data/dictionaries/multiple/greetings.json:

{
    "name": "Greetings",
    "type": "collection",
    "data": [
        {"learning":"¡Hola!", "en":"Hello!", "ru":"Привет!", "de":"Hallo!", "fr":"Bonjour!", "pt":"Olá!"}
    ]
}

_data/dictionaries/multiple/un1/_metadata.json:

{
    "name": "Unit 1"
}

_data/dictionaries/multiple/un1/numbers.json:

{
    "type": "collection",
    "data": [
        {
            "learning": "uno",
            "en": "one",
            "ru": "один",
            "de": "eins",
            "fr": "un",
            "pt": "um"
        },
        {
            "learning": "dos",
            "en": "two",
            "ru": "два",
            "de": "zwei",
            "fr": "deux",
            "pt": "dois"
        },
        {
            "learning": "tres",
            "en": "three",
            "ru": "три",
            "de": "drei",
            "fr": "trois",
            "pt": "três"
        },
        {
            "learning": "cuatro",
            "en": "four",
            "ru": "четыре",
            "de": "vier",
            "fr": "quatre",
            "pt": "quatro"
        },
        {
            "learning": "cinco",
            "en": "five",
            "ru": "пять",
            "de": "fünf",
            "fr": "cinq",
            "pt": "cinco"
        },
        {
            "learning": "seis",
            "en": "six",
            "ru": "шесть",
            "de": "sechs",
            "fr": "six",
            "pt": "seis"
        },
        {
            "learning": "siete",
            "en": "seven",
            "ru": "семь",
            "de": "sieben",
            "fr": "sept",
            "pt": "sete"
        },
        {
            "learning": "ocho",
            "en": "eight",
            "ru": "восемь",
            "de": "acht",
            "fr": "huit",
            "pt": "oito"
        },
        {
            "learning": "nueve",
            "en": "nine",
            "ru": "девять",
            "de": "neun",
            "fr": "neuf",
            "pt": "nove"
        },
        {
            "learning": "diez",
            "en": "ten",
            "ru": "десять",
            "de": "zehn",
            "fr": "dix",
            "pt": "dez"
        }
    ]
}

The plugin will generate JSON API /api/dictionaries/multiple.json

{"docUrl":"http://example.org/dictionaries/multiple","version":"1.0.0","name":"Basic (Multiple Languages)","translationType":"multiple","learning":"es","translations":["en","ru","de","fr","pt"],"data":[{"name":"Greetings","type":"collection","data":[{"learning":"¡Hola!","en":"Hello!","ru":"Привет!","de":"Hallo!","fr":"Bonjour!","pt":"Olá!"}]},{"type":"folder","name":"Unit 1","data":[{"name":"numbers","type":"collection","data":[{"learning":"uno","en":"one","ru":"один","de":"eins","fr":"un","pt":"um"},{"learning":"dos","en":"two","ru":"два","de":"zwei","fr":"deux","pt":"dois"},{"learning":"tres","en":"three","ru":"три","de":"drei","fr":"trois","pt":"três"},{"learning":"cuatro","en":"four","ru":"четыре","de":"vier","fr":"quatre","pt":"quatro"},{"learning":"cinco","en":"five","ru":"пять","de":"fünf","fr":"cinq","pt":"cinco"},{"learning":"seis","en":"six","ru":"шесть","de":"sechs","fr":"six","pt":"seis"},{"learning":"siete","en":"seven","ru":"семь","de":"sieben","fr":"sept","pt":"sete"},{"learning":"ocho","en":"eight","ru":"восемь","de":"acht","fr":"huit","pt":"oito"},{"learning":"nueve","en":"nine","ru":"девять","de":"neun","fr":"neuf","pt":"nove"},{"learning":"diez","en":"ten","ru":"десять","de":"zehn","fr":"dix","pt":"dez"}]}]}]}

As you can see collection greetings and folder un1 have names that are defined by property name.

Push New Version Commands

 gem bump
 gem build jekyll-dictionaries.gemspec
 gem push jekyll-dictionaries-*.gem

License

This project is licensed under the MIT License.