Repository files navigation

Jekyll Multiple Languages is an internationalization plugin forJekyll. It compiles your Jekyll site for one or more languages with a similar approach as Rails does. The different sites will be stored in subfolders with the same name as the language it contains.

The plugin was developed as a utility atDaresay

Are you using this plugin? Could you test and verify incoming PRs? Please give us a shout!

• Jekyll Multiple Languages Plugin
  • Badges
  • !! We are looking for more maintainers !!
  • Table of Contents
  • 1. Current Release Notice
  • 2. Features
  • 3. Installation
    • 3.1. Using the gem
    • 3.2. Manually
    • 3.3. As a Git Submodule
  • 4. Configuration
    • 4.1. _config.yml
    • 4.2. Folder structure
  • 5. Usage
    • 5.1. Translating strings
    • 5.2. Including translated files
    • 5.3. Permalinks and Translating Links
    • 5.4. i18n in templates
    • 5.5. Link between languages
    • 5.6. Creating pages
    • 5.7. Creating posts
    • 5.8. Select pages to translations
  • 6. License
  • 7. Example website
    • 7.1. Adding a new language
    • 7.2. Adding new page
  • 8. Changelog
  • 9. Contributing
    • Contributors
    • Created by
    • Maintained by
    • Former maintainer
  • 10. Other Language Plugins

1.6.0 is the current stable release.

The support for Octopress is dropped, but the plugin should still work with it since Octopress core is Jekyll.Octopress 3 now has its own multi languages plugin:https://github.com/octopress/multilingual

• Supports multiple languages with the same code base.
• Supports all template languages that your Liquid pipeline supports.
• UsesLiquid tags in your HTML for including translated strings.
• Compiles the site multiple times for all supported languages into separate subfolders.
• Works with the --watch flag turned on and will rebuild all languages automatically.
• Contains an example website, thanks to@davrandom
• Supports translated keys in YAML format
• Supports translated template files
• Supports translated links

This plugin is available as a Ruby gem,https://rubygems.org/gems/jekyll-multiple-languages-plugin.

Add this line to your application's Gemfile:

gem 'jekyll-multiple-languages-plugin'

And then execute:$ bundle install

Or install it yourself as:$ gem install jekyll-multiple-languages-plugin

To activate the plugin add it to the Jekyll_config.yml file, under theplugins option:

plugins:  -jekyll-multiple-languages-plugin

See theJekyll configuration documentation for details.

1. Download the repository with Git or your preferred method.
2. Inside your Jekyll_plugins folder, create a new folder calledjekyll-multiple-languages-plugin.
3. Copy or link the directorylib, that is inside the downloaded repository, into your_plugins/jekyll-multiple-languages-plugin folder of your Jekyll project.

If your Jekyll project is in a git repository, you can easily manage your plugins by utilizing git submodules.

To install this plugin as a git submodule:

$ git submodule add git://github.com/screeninteraction/jekyll-multiple-languages-plugin.git _plugins/multiple-languages

To update:

$cd _plugins/multiple-languages$ git pull origin master

Add the languages available in your website into your _config.yml (obligatory):

languages:["sv", "en", "de", "fr"]

The first language in the array will be the default language, English, German and French will be added into separate subfolders.

To avoid redundancy, it is possible to exclude files and folders from being copied to the localization folders.

exclude_from_localizations:["javascript", "images", "css"]

In code, these specific files should be referenced viabaseurl_root. E.g.

<link rel="stylesheet" href="{{ "/css/bootstrap.css" | prepend: site.baseurl_root }}"/>

If you wish to avoid having the default_lang built into the root of your website, use:

default_locale_in_subfolder:true

Create a folder called_i18n and add sub-folders for each language, using the same names used on thelanguages setting on the_config.yml:

• /_i18n/sv.yml
• /_i18n/en.yml
• /_i18n/de.yml
• /_i18n/fr.yml
• /_i18n/sv/pagename/blockname.md
• /_i18n/en/pagename/blockname.md
• /_i18n/de/pagename/blockname.md
• /_i18n/fr/pagename/blockname.md

To add a translated string into your web page, use one of these liquid tags:

{%tkey %}or{%translatekey %}

This will pick the correct string from thelanguage.yml file during compilation.

The language.yml files are written in YAML syntax which caters for a simple grouping of strings.

global:swedish:Svenskaenglish:Englishpages:home:Homework:Work

To access theenglish key, use one of these tags:

{%tglobal.english %}or{%translateglobal.english %}

You can also access translated strings by accessing thesite.translations hash, this allows you to loop through your translations within Liquid using the translated string's index:

{%foriteminsite.translations[site.lang].my_nested_yaml_collection %}    <p>{{item[0] }} -> {{item[1] }}</p>{%endfor %}

or the translated string's assignment:

my_nested_yaml_collection:  -title:Firstmessage:Message  -title:Secondmessage:Message

{%foriteminsite.translations[site.lang].my_nested_yaml_collection %}   <li>      <h2>{{item["title"] }}</h2>      <p>{{item["message"] }}</p>   </li>{%endfor %}

The plugin also supports using different markdown files for different languages using the liquid tag:

{%tfpagename/blockname.md %}or{%translate_filepagename/blockname.md %}

This plugin has exactly the same support and syntax as the Jekyll's built in liquid tag:

{%includefile %}

so plugins that extend its functionality should be picked up by this plugin as well.

To use localized pages with permalinks, you must provide a defaultpermalink and the language specific permalinks, for example,permalink_fr for French.

To translate links, you must also add aunique namespace on the YAML front matter along with the permalinks.

Example:

---layout:defaultnamespace:teampermalink:/team/permalink_fr:/equipe/---

And then you can use the translate link liquid tag like this:

<ahref="{%tlteam %}"><!--This link will return /team if we are in the English version of the website and /fr/equipe if it's the French version</a>--><ahref="{%tlteamfr %}"><!--This link will always return /fr/equipe</a>-->or the longer version:<ahref="{%translate_linkteam %}"><!--This link will return /team if we are in the English version of the website and /fr/equipe if it's the french version</a>--><ahref="{%translate_linkteamfr %}"><!--This link will always return /fr/equipe</a>-->

Sometimes it is convenient to add keys even in template files. This works in the exact same way as in ordinary files, however sometimes it can be useful to include a different string in different pages even if they use the same template.

A perfect example is this:

<html><head><title>{% t page.title %}</title></head></html>

So how can I add different translated titles to all pages? Don't worry, it's easy. The Multiple Languages plugin supports Liquid variables, as well as strings so, define a page variable in your page definition

---layout:defaulttitle:titles.home---

and<title>{% t page.title %}</title> will pick up thetitles.home key fromlanguage.yml

titles:home:"Home"

This plugin gives you the variables

{{site.lang }}and{{site.baseurl_root }}

to play with in your template files.

This allows you to create solutions like this:

{%ifsite.lang=="sv" %}  {%capture link1 %}{{site.baseurl_root }}/en{{page.url}}{%endcapture %}  <ahref="{{link1 }}" >{%tglobal.english %}</a>{%elsifsite.lang=="en" %}  {%capture link2 %}{{site.baseurl_root }}{{page.url  }}{%endcapture %}  <ahref="{{link2 }}" >{%tglobal.swedish %}</a>{%endif %}

This snippet will create a link that will toggle between Swedish and English. A more detailed description of the variables used follows:

Depending on the theme, or your preferences, you need to create a "template" page in the root folder or in a folder (ex._pages). Inside each page (in this example anabout.md) you should have at least the following in the header and body:

---layout:pagetitle:Aboutpermalink:/about/---{% translate_file about/about.md %}

Inside each of the language folders, you should create mirror pages to provide the actual content for that language (ex.i18n/es/about/about.md). Make sure to erase the headers from those md files, or else your site will break.

There are no global posts. The posts are localized by language. And your posts will live in the_i18n/[lang]/_posts directory. So if, for example, you have English language on your website you should put your posts on_i18n/en/_posts directory.

Sometimes you want to generate only selected versions of the page, especially excluding default language. You can do this using languages tag.

Example:

---permalink:/team/permalink_fr:/equipe/languages:["fr"]---

This generate only french version of the page.

This project is available under theMIT License.

This repository has an example website where you can test the plugin.After downloading the repository, get into theexample directory and run:bundle install to install the newest version of Jekyll (edit the Gemfile to install another version) and all other dependencies.

Then runbundle exec jekyll serve to start the Jekyll server. Using your web browser, access the addresshttp://localhost:4000.

Imagine you want to add German pages on the test website. First, add a new language to the list of languages on_config.yml:

languages:["it","en","es","de"]

Create a new folder for the language under the_i18n folder and add a markdown file containing the translation, just like on the other language folders, and you're done.

Let's say you want to create an about page for the example website, you will create anabout.html page on the root of the website (same place as index.html), with this:

---layout: pagetitle: Aboutpermalink: /about/---{% translate_file about/about.md %}

Then, create a file namedabout.md under_i18n/en with the English content. Repeat this for the other languages (_i18n/es/about.md ...). When running the website, visit the addresshttp://localhost:4000/about to see the English version,http://localhost:4000/es/about for the Spanish one, etc.

• 1.8.0
  • I18n for site and Front Matter configurations@pgoltsev
• 1.7.0
  • Option to build the default language into a subfolder
  • Configurable verbosity
  • Improved documentation
  • Removed deprecation warning
• 1.6.1
  • Improved testing
  • Support for Jekyll 4
  • Russian examples
  • Translations rebuilt every time page is reloaded in developer mode
• 1.6.0
  • fix: check if static_file_r_path is set
  • Missing slash before lang prefix in lang picker example
  • Updated README.md with _posts directory
  • Build translations in pre_render hook
  • If include not found, fall back to default language
• 1.5.1
  • Fix a bug (#70) wheresite.static_files would be empty on subsites ifexclude_from_localizations is used.
  • Some overall project enhancements and minor fixes.
  • A simple Rake task is available to test the plugin, CI services now have something to run.
• 1.5.0
  • Enables Liquid expansions within Liquid Tags.
  • The example website post language switchers were rewritten in an algorithmic way.
• 1.4.2
  • Exposes thesite.translations hash containing the translated strings to Liquid.
• 1.4.1
  • Fixes a bug during site regeneration where translation paths were being nested based on wrongly set Jekyll variables.
• 1.4.0
  • Support for Jekyll 3, thanks to@pedrocarmona
  • How to create pages documentation, thanks to@elotroalex
  • Many bug fixes
  • Code refactoring, cleanup and reorganization
  • Files and folders reorganization
  • Improved and fixed issues on the example website
  • Improvements and fixes on documentations
  • Improved license files
• 1.3.0
  • Support for localized links and custom permalinks, thanks to@jasonlemay
  • Support for excluding posts from translation, thanks to@ctruelson
• 1.2.9
  • Bug fix when excluding files from translation, again thanks to@h6
• 1.2.8
  • Support for excluding files from translation, thanks to@h6
• 1.2.7
  • Support for Jekyll 2.5+, thanks to@caxy4
• 1.2.6
  • Added fallback to default language, thanks to@agramian
• 1.2.5
  • Fixed a bug when global variables weren't as global as expected
• 1.2.4
  • Fixed a bug when changes in .yml files got lost during live reload.
• 1.2.3
  • Much, much, much faster compilation when lots of translated strings.
• 1.2.2
  • Supports translated posts in Octopress
• 1.2.1
  • Supports writing translated posts in Jekyll
  • Supports translated .yml files in Octopress
• 1.2.0
  • Renamed the project to jekyll-multiple-languages-plugin
• 1.1.2
  • Support for both variables and strings intranslate_file
• 1.1.1
  • Fixed documentation
• 1.1.0
  • Pull request that removed dirty forward slash from URLs
• 1.0.0
  • First release

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

@kurtsson fromDaresay (https://daresay.co)

• @shushugah

• @Anthony-Gaudino

Below is a list of other language plugins for Jekyll (2019/06/27):

Seems to be maintained:

• Polyglot

Seems to be unmaintained / abandoned:

• jekyll-task-i18n
• Jekyll Language Plugin
• jekyll-i18n_tags
• Octopress Multilingual
• Jekyll Multiple Languages
• Jekyll-Multilingualism
• Jekyll::Languages
• Jekyll I18n support
• jekyll-multilingual
• jekyll-msgcat
• jekyll-localize
• Jekyll i18n Filter
• jekyll-localization
• Jekyll i18n

This plugin will in the future try to merge all pertinent features of all those plugins into it.