:abc: Multilingual and i18n support tool for Jekyll Blogs
:abc: Multilingual and i18n support tool for Jekyll Blogs
Polyglot is a fast, painless, open-source internationalization plugin for Jekyll blogs. Polyglot is easy to set up 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"
endOr install the gem manually by doing gem install jekyll-polyglot and specify the plugin using _config.yml:
plugins:
- jekyll-polyglotIn your _config.yml file, add the following preferences
languages: ["en", "sv", "de", "fr"]
default_lang: "en"
exclude_from_localization: ["javascript", "images", "css", "public", "sitemap", "CNAME"]
parallel_localization: true
serial_default_lang: true
url: https://polyglot.untra.ioThese 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.)false if building on Windows hosts, or if Polyglot collides with other Jekyll plugins. - If parallel_localization collides with other jekyll plugins, this setting makes polyglot build the default language first before processing the other language sites.The optional lang_from_path: true option enables getting the page language from a filepath segment seperated by / or ., e.g de/first-one.md, or _posts/zh_HK/use-second-segment.md , if the lang frontmatter isn't defined.
If you are deploying to Netlify and use a _redirects file, you can enable automatic localization of redirects:
localize_redirects: true
exclude_from_redirect_localization:
- /signin
- /appSee Localizing Netlify _redirects for more details.
When adding new posts and pages, add to the YAML front matter:
lang: svor 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.
You can see how the live Polyglot website configures and supports multiple languages, and examples of community language contributions.
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.mdOrganized names will generate consistent permalinks when the post is rendered, and Polyglot will know to build separate language versions of the website using only the files with the correct lang variable in the front matter.
In short:
New in 1.8.0
Whenever page_id frontmatter properties are used to identify translations, permalink information for the available languages is available in permalink_lang.
This is useful in order to generate language menus and even localization meta information without redirects!
Sample code for meta link generation:
{% for lang in site.languages %}
{% capture lang_href %}{{site.baseurl}}/{% if lang != site.default_lang %}{{ lang }}/{% endif %}{% if page.permalink_lang[lang] != '/' %}{{page.permalink_lang[lang]}}{% endif %}{% endcapture %}
{% endfor %}New in 1.13.0
Polyglot exposes two arrays on every page describing its translation status:
page.available_languages — language codes that have an actual translation of this page.page.missing_languages — languages that don't yet have a translation of this page.missing_languages is intentionally empty for pages that have no per-language translations at all: a single-source page falls back to identical content for every visitor, so there is nothing missing to flag. Only pages that already have at least one translations report the gaps.
Combine with page.rendered_lang to also flag fallback content on the page itself.
New in 1.7.0
Optionally, for those who may want different URLs on different languages, translations may be identified by specifying a page_id in the frontmatter.
If available, Polyglot will use page_id to identify the page, and will default to the permalink otherwise.
As an example, you may have an about page located in /about/ while being in /acerca-de/ in Spanish just by changing the permalink and specifying a page_id that will link the files as translations:
---
title: About
permalink: /about
lang: en
page_id: about
---
This is us!---
title: Acerca de
permalink: /acerca-de
lang: es
page_id: about
---
Estos somos nosotros!Additionally, if you are also using the jekyll-redirect-from plugin, pages coordinated this way will automatically have redirects created between pages.
So /es/about will automatically redirect to /es/acerca-de and /acerca-de can redirect to /about. If you use this approach, be sure to also employ a customized redirect.html.
As of version 1.12, Polyglot also properly supports redirect_from frontmatter across sublanguages. When you add redirect paths to pages in non-default languages, Polyglot will correctly scope those redirects to each language's prefix, preventing duplicate redirects and ensuring proper routing.
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.
Polyglot only generates hreflang tags for languages that have actual translations. This improves SEO correctness by not advertising language alternatives that don't actually exist.
For example, if you have /about.html in English and Spanish but not French:
hreflang="en", hreflang="es", and hreflang="x-default"hreflang="fr" is generated, even though a French fallback page existsThis behavior:
hreflang tagshreflang for the default language and x-defaultTranslation detection works via:
page_id frontmatter are considered translationslang) are considered translations{% I18n_Headers %} tag searches site.collections and site.pagesNo 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 visitors 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
au sujet de notre entreprise
Nous sommes un restaurant situé à Paris . Ceci est notre menu.
Notice the link ... 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
Cliquez ici pour aller à l'entrée du site.For proper canonical URL handling on multilingual sites, we recommend using Polyglot's {% I18n_Headers %} tag for canonical URLs instead of jekyll-seo-tag's default canonical output. This provides intelligent canonical URL generation that:
page_id and permalink matching for translation detectionSetup with jekyll-seo-tag:
If you're using jekyll-seo-tag, you can disable its canonical output and let Polyglot handle it:
{% seo canonical=false %}
{% I18n_Headers %}The canonical=false option is available in jekyll-seo-tag v2.9.0+
Fallback Canonical Behavior:
To have fallback pages (pages without translations) point their canonical URL to the default language version, add to your _config.yml:
fallback_canonical_to_default_lang: trueWith this option enabled:
/es/sobre-nosotros/)/about/ instead of /es/about/)This improves SEO by:
Note: hreflang URLs pointing to the default language or x-default are intentionally NOT relativized, as they should always point to the canonical language-specific URLs.
New in 1.13.0
When using Polyglot with Netlify, redirect rules defined in a Netlify _redirects file will get relativized (e.g., /github becomes `/f
No open issues yet, or sync has not completed.