jekyll-language-plugin 1.0.0 → 1.0.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +157 -2
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 1f7f81d9c518d3a746e3d3e2df8f113bbf32ecb0
|
|
4
|
+
data.tar.gz: babaab48e38c83dd620960f2756234e55c372e59
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: a315f32074df59365490a7a529b22a31c4cf129d1f5c3366d520459def13ef5c4e8be35ca3d74ca47a7683383913a1e3aa1122f859156a521c26d71b564ecb81
|
|
7
|
+
data.tar.gz: 6a68495e25db78915703815362da6aae5981868d6b91255cae165c2a25ccfc23f509e1b3342c9660ab056457e8c8485be08cb49e840d8beff0dacbec71a1c544
|
data/README.md
CHANGED
|
@@ -1,2 +1,157 @@
|
|
|
1
|
-
# jekyll-language-plugin
|
|
2
|
-
|
|
1
|
+
# Jekyll Language Plugin [](http://badge.fury.io/rb/jekyll-language-plugin)
|
|
2
|
+
|
|
3
|
+
> Jekyll 3.0-compatible multi-language plugin for posts, pages and includes
|
|
4
|
+
|
|
5
|
+
Jekyll Language Plugin is an internationalization plugin for [Jekyll][jekyll]. It diversifies pages, posts and includes that have been optimized for the use with this plugin into different languages which are organized into subdirectories named after the language name.
|
|
6
|
+
|
|
7
|
+
This plugin has been developed with user-simplicity in mind. It does not require a complex setup process unlike some other internationalization plugins.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
* Translates pages and posts into multiple languages
|
|
12
|
+
* Supports all template languages that your Liquid pipeline supports.
|
|
13
|
+
* Uses liquid tags in your HTML for including translated strings and language-specific includes.
|
|
14
|
+
* Works with `jekyll serve --watch`
|
|
15
|
+
* Supports includes translated into multiple languages
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
This plugin is available as a [RubyGem][ruby-gem].
|
|
20
|
+
|
|
21
|
+
Add this line to your application's `Gemfile`:
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
gem 'jekyll-language-plugin'
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
And then execute the `bundle` command to install the gem.
|
|
28
|
+
|
|
29
|
+
Alternatively, you can also manually install the gem using the following command:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
$ gem install jekyll-language-plugin`
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
After the plugin has been installed successfully, add the following lines to your `_config.yml` in order to tell Jekyll to use the plugin:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
gems:
|
|
39
|
+
- jekyll-language-plugin
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Configuration
|
|
43
|
+
|
|
44
|
+
Two additional configuration keys must be present in your `_config.yml` in order for the plugin to work properly:
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
language_data: data.lang.%%
|
|
48
|
+
language_includes_dir: _i18n
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The first key, `language_data`, tells the plugin where it can find the translation data used by the liquid tag. `%%` is a placeholder for the language name. So, if the language is `en`, the plugin will look into `data.lang.en`. It is entirely up to you how you are structuring your Jekyll data. You can have a file `lang.yml` inside your `_data` directory or you can have a `lang` subdirectory inside your `_data` directory containing `en.yml` or `en.json`.
|
|
52
|
+
|
|
53
|
+
## Usage
|
|
54
|
+
|
|
55
|
+
Every page or post, that needs to be translated must either have a `language` key or a `languages` array inside its YAML front-matter. Additionally, it may also have an `alias` key which tells the plugin to traverse one step further into the language data. So for example, if `alias` is `home` and the `language_data` configuration setting is `data.lang.%%` and the language is `en`, the plugin will look into `data.lang.en.home` for the translation keys used by the liquid tag. Of course, only pages and layouts can use the translation liquid tag but layouts used by posts can therefore benefit from an `alias`.
|
|
56
|
+
|
|
57
|
+
### Example
|
|
58
|
+
|
|
59
|
+
This is a page optimized for the language plugin, `home.html`:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
---
|
|
63
|
+
layout: default
|
|
64
|
+
alias: home
|
|
65
|
+
languages:
|
|
66
|
+
- en
|
|
67
|
+
- de
|
|
68
|
+
---
|
|
69
|
+
<h1>{% t title %}</h1>
|
|
70
|
+
<p>{% t description %}</p>
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`t` is the translation tag. In this case, it will look for `data.lang.en.home.title` and `data.lang.en.home.description` for the English language or `data.lang.de.home.title` and `data.lang.de.home.description` for the German language.
|
|
74
|
+
|
|
75
|
+
To have more of a structure for larger projects, languages are divided into subdirectories. For the English language, the data file `_data/lang/en.yml` will look similar to this:
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
---
|
|
79
|
+
home:
|
|
80
|
+
title: My example home page
|
|
81
|
+
description: This is my example home page powered by the Jekyll language plugin.
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
And respectively, the German language data file, `_data/lang/de.yml` looks similar to this:
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
---
|
|
88
|
+
home:
|
|
89
|
+
title: Meine Beispielhomepage
|
|
90
|
+
description: Dies ist meine Beispielhomepage getrieben vom Jekyll-Sprachplugin.
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Create a new file `_layouts/default.html` which will contain the default layout:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
<!DOCTYPE html>
|
|
97
|
+
<html>
|
|
98
|
+
<head{% if page.language %} lang="{{ page.language }}"{% endif %}>
|
|
99
|
+
<meta charset="utf-8">
|
|
100
|
+
<title>{% t title %} | {{ site.title }}</title>
|
|
101
|
+
</head>
|
|
102
|
+
<body>
|
|
103
|
+
{{ content }}
|
|
104
|
+
<p><small>{% t footnote %} | <a href="{{ site.baseurl }}/en/" title="English">en</a> | <a href="{{ site.baseurl }}/de/" title="German">de</a></small></p>
|
|
105
|
+
</body>
|
|
106
|
+
</html>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
As a sidenote, if an `alias` is given and the translation liquid tag can not find a key within the alias of a given language, it will look without the `alias`, basically one level upwards.
|
|
110
|
+
|
|
111
|
+
So if `footnote` is common to all pages and posts, it can be placed within the root of each language file. For the English language, add the following to `_data/lang/en.yml`:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
footnote: Copyright (c) Example home page 2015. All rights reserved.
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
For the German language, add the following line to `_data/lang/de.yml`:
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
footnote: Copyright (c) Beispielhomepage. Alle Rechte vorbehalten.
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
If you now run `jekyll build`, you will obtain two separate `home.html` files in your `_site` directory within the `en` and `de` subdirectories, respectively.
|
|
124
|
+
|
|
125
|
+
### Posts
|
|
126
|
+
|
|
127
|
+
Similar to pages, posts can also have the `languages` or `language` keys in its YAML front-matter. The `alias` key is also supported. Unlike pages, posts cannot use the translation liquid tag but the layout used by the post can. The post is rendered for each language specified, just like pages are.
|
|
128
|
+
|
|
129
|
+
## Liquid tags
|
|
130
|
+
|
|
131
|
+
Currently, there are two liquid tags provided by this plugin.
|
|
132
|
+
|
|
133
|
+
### Translation Liquid tag
|
|
134
|
+
|
|
135
|
+
The `t` liquid tag provides a convenient way of accessing language-specific translations from the language data referred to in the configuration file.
|
|
136
|
+
|
|
137
|
+
If an alias is given by the page's or post's front-matter, `t` will look into the language-specific alias first. Only if the key cannot be found there, it will perform another lookup without the alias. This can be useful for common translations like a copyright notice.
|
|
138
|
+
|
|
139
|
+
### Language-Specific Include Tag
|
|
140
|
+
|
|
141
|
+
The `tinclude` liquid tag works just like the Jekyll-standard `include` tag. But unlike `include`, `tinclude` will not look into the `_includes` directory. Instead it will look into the directory specified by the `language_includes_dir` configuration setting, here `_i18n`. Then it travels one subdirectory down for the language name. If you `{% tinclude lorem.txt %}`, `tinclude` will look for the file in `_i18n/en/lorem.txt` if the language is English.
|
|
142
|
+
|
|
143
|
+
# Example Site
|
|
144
|
+
|
|
145
|
+
This repository contains a ready-to-use example site using this plugin in the `example` subdirectory. Check it out and run `bundle install` followed by `bundle exec jekyll build` to build the site.
|
|
146
|
+
|
|
147
|
+
# Contribute
|
|
148
|
+
|
|
149
|
+
Fork this repository, make your changes and then issue a pull request. If you find bugs or have new ideas that you do not want to implement yourself, file an issue.
|
|
150
|
+
|
|
151
|
+
# Copyright
|
|
152
|
+
|
|
153
|
+
Copyright (c) Vincent Wochnik 2015.
|
|
154
|
+
License: MIT
|
|
155
|
+
|
|
156
|
+
[jekyll]: https://github.com/mojombo/jekyll
|
|
157
|
+
[ruby-gem]: https://rubygems.org/gems/jekyll-language-plugin
|