README.md in jekyll-language-plugin-1.1.1 vs README.md in jekyll-language-plugin-1.1.2

- old
+ new

@@ -51,20 +51,20 @@ 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`. ## Usage -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`. +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 `subset` key which tells the plugin to traverse one step further into the language data. So for example, if `subset` 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 `subset`. ### Example This is a page optimized for the language plugin, `home.html`: ``` --- layout: default -alias: home +subset: home languages: - en - de --- <h1>{% t title %}</h1> @@ -105,11 +105,11 @@ <p><small>{% t footnote %} | <a href="{{ site.baseurl }}/en/" title="English">en</a> | <a href="{{ site.baseurl }}/de/" title="German">de</a></small></p> </body> </html> ``` -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. +As a side note, if a `subset` is given and the translation liquid tag can not find a key within the given subset of the specified language, it will perform another lookup without the given subset. 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`: ``` footnote: Copyright (c) Example home page 2015. All rights reserved. @@ -123,22 +123,22 @@ 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. ### Posts -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. +Similar to pages, posts can also have the `languages` or `language` keys as well as the `subset` key in its YAML front-matter. You can use all supported liquid tags and filters to translate posts but you can also create multiple posts, one for each language. ## Liquid tags Currently, there are two liquid tags provided by this plugin. ### Translation Liquid tag The `t` liquid tag provides a convenient way of accessing language-specific translations from the language data referred to in the configuration file. -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. The key can also be a dot-notation of multiple keys which are traversed upon lookup. +If a `subset` is given by the page's or post's front-matter, `t` will look into the given `subset` of the language specified. Only if the key cannot be found there, it will perform another lookup without traversing into the given subset. This can be useful for common translations like a copyright notice. The key can also be a dot-notation of cascaded keys which are traversed upon lookup. -*Example*: `{% t homepage_welcome %}` +*Example*: `{% t homepage_welcome %}` or `{% t homepage.welcome %}` ### Language-Specific Include Tag 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.