Polyglot is a fast, painless, open-source internationalization plugin for Jekyll blogs. Polyglot is easy to setup and use with any Jekyll project, and it scales to the languages you want to support. With fallback support for missing content, automatic url relativization, and powerful SEO tools, Polyglot allows any multi-language jekyll blog to focus on content without the cruft.
Jekyll doesn't provide native support for multi-language blogs. This plugin was modeled after the jekyll-multiple-languages-plugin, whose implementation I liked, but execution I didn't.
Add jekyll-polyglot to your Gemfile
if you are using Bundler:
group :jekyll_plugins do
gem "jekyll-polyglot"
end
Or install the gem manually by doing gem install jekyll-polyglot
and specify the plugin using _config.yml
:
plugins:
- jekyll-polyglot
In your _config.yml
file, add the following preferences
languages: ["en", "sv", "de", "fr"]
default_lang: "en"
exclude_from_localization: ["javascript", "images", "css", "public"]
parallel_localization: true
These configuration preferences indicate
exclude: [ .gitignore ]
; you should exclude
files and directories in your repo you dont want in your built site at all, and exclude_from_localization
files and directories you want to see in your built site, but not in your sublanguage sites.)The optional lang_from_path: true
option enables getting page
language from the first or second path segment, e.g de/first-one.md
, or
_posts/zh_Hans_HK/use-second-segment.md
, if the lang frontmatter isn't defined.
When adding new posts and pages, add to the YAML front matter:
lang: sv
or whatever appropriate I18n language code the page should build for. And you're done. Ideally, when designing your site, you should organize files by their relative urls.
Polyglot works by associating documents with similar permalinks to the lang
specified in their frontmatter. Files that correspond to similar routes should have identical permalinks. If you don't provide a permalink for a post, make sure you are consistent with how you place and name corresponding files:
_posts/2010-03-01-salad-recipes-en.md
_posts/2010-03-01-salad-recipes-sv.md
_posts/2010-03-01-salad-recipes-fr.md
Organized names will generate consistent permalinks when the post is rendered, and polyglot will know to build seperate language versions of
the website using only the files with the correct lang
variable in the front matter.
In short:
Lets say you are building your website. You have an /about/
page written in english, german and
swedish. You are also supporting a french website, but you never designed a french version of your /about/
page!
No worries. Polyglot ensures the sitemap of your english site matches your french site, matches your swedish and german sites too. In this case, because you specified a default_lang
variable in your _config.yml
, all sites missing their languages' counterparts will fallback to your default_lang
, so content is preserved across different languages of your site.
No need to meticulously manage anchor tags to link to your correct language. Polyglot modifies how pages get written to the site so your french links keep vistors on your french blog.
---
title: au sujet de notre entreprise
permalink: /about/
lang: fr
---
Nous sommes un restaurant situé à Paris . [Ceci est notre menu.](/menu/)
becomes
<header class="post-header">
<h1 class="post-title">au sujet de notre entreprise</h1>
</header>
<article class="post-content">
<p>Nous sommes un restaurant situé à Paris . <a href="/fr/menu/">Ceci est notre menu.</a></p>
</article>
Notice the link <a href="/fr/menu/">...
directs to the french website.
Even if you are falling back to default_lang
page, relative links built on the french site will still link to french pages.
If you defined a site url
in your _config.yaml
, polyglot will automatically relativize absolute links pointing to your website directory:
---
lang: fr
---
Cliquez [ici]({{site.url}}) pour aller à l'entrée du site.
becomes
<p>Cliquez <a href="https://mywebsite.com/fr/">ici</a> pour aller à l'entrée du site.
New in 1.4.0 If you dont want a href attribute to be relativized (such as for making a language switcher), you can use the block tag:
{% static_href %}href="..."{% endstatic_href %}
<a {% static_href %}href="/about"{% endstatic_href %}>click this static link</a>
that will generate <a href="/about">click this static link</a>
which is what you would normally use to create a url unmangled by invisible language relativization.
Combine with a html minifier for a polished and production ready website.
New in 1.4.0
If you want to control which languages a document can be generated for, you can specify lang-exclusive: [ ]
frontmatter.
If you include this frontmatter in your post, it will only generate for the specified site languages.
For Example, the following frontmatter will only generate in the en
and fr
site language builds:
---
lang-exclusive: ['en', 'fr']
---
New in 1.5.0
Polyglot will only start builds after it confirms there is a cpu core ready to accept the build thread. This ensures that jekyll will build large sites efficiently streamlining build processes instead of overloading machines with process thrash.
There are cases when site.data
localization is required.
For instance: you might need to localize _data/navigation.yml
that holds "navigation menu".
In order to localize it, just place language-specific files in _data/:lang/...
folder, and Polyglot will bring those keys to the top level.
This plugin makes modifications to existing Jekyll classes and modules, namely Jekyll::StaticFile
and Jekyll::Site
. These changes are as lightweight and slim as possible. The biggest change is in Jekyll::Site.process
. Polyglot overwrites this method to instead spawn a separate process for each language you intend to process the site for. Each of those processes calls the original Jekyll::Site.process
method with its language in mind, ensuring your website scales to support any number of languages, while building all of your site languages simultaneously.
Jekyll::Site.process
is the entry point for the Jekyll build process. Take care whatever other plugins you use do not also attempt to overwrite this method. You may have problems.
This plugin stands out from other I18n Jekyll plugins.
default_lang
.{{ site.languages }}
to get an array of your I18n strings.{{ site.default_lang }}
to get the default_lang I18n string.{{ site.active_lang }}
to get the I18n language string the website was built for. Alternative names for active_lang
can be configured via config.lang_vars
.{{ I18n_Headers https://yourwebsite.com/ }}
to append SEO bonuses to your website.{{ Unrelativized_Link href="/hello" }}
to make urls that do not get influenced by url correction regexes.site.data
localization for efficient rich text replacement.Jekyll-polyglot has a few spectacular Search Engine Optimization techniques to ensure your Jekyll blog gets the most out of it's multilingual audience. Check them out!
Feel free to open a PR and list your multilingual blog here you may want to share:
Currently supports Jekyll 3.0 , and Jekyll 4.0
parallel_localization: false
in the _config.yml
config.yml
will disable sourcemap generation:sass:
sourcemap: never
Please! I need all the support I can get! 🙏
But for real I would appreciate any contributions and support. This started as an open-source side-project and has gotten bigger than I'd ever imagine! If you have something you'd like to contribute to jekyll-polyglot, please open a PR!
pt_BR
pt_PT
ar
ja
ru
nl
ko
he
Copyright (c) Samuel Volin 2023. License: MIT