jekyll dont provide any official documentation for internationalization,below info generated by reading docs of different jekyll multilangual plugins
more popular i18n plugns for jekyll are jekyll multiple language plugin ,jekyll-polygot, jekyll-i18n.
list of supported plugins is given here which does not indclude any of the i18n plugin.but by having CI setup can make unsupported plugin work for us.
there is no native i18n support provided by jekyll,but can be achieved through plugins or by providing i18n support from scratch.
-
jekyll-i18n - not maintained anymore.
-
jekyll multiple language plugin - mostly used and reach in features but not supports githubpages. current stable release : 1.6.0 june 2020. beta version 1.7.0
-
polygot -
properly maintained and designed over the model of jekyll multiple language plugin. supports same features as that of jekyll multiple language plugin but implementation is more easier than above plugins. latest stable version 1.4.0 feb 2021 and supports jekyll >= 3.x. not supported on github pages. some interesting features includes parallel processing and getting page using path if "lang" is not defined in frontmatter of page
-
set languages supported by sites -
plugin - easy to set using
languagesattribute.manual method - using front matter defaults in _config.yml
-
set default language/fallback language for site -
plugin- using
default_lang:.manual method - using front matter defaults in _config.yml (generally we dont put default lang in any scope hence it becomes site wide and default and config for other languages in scope )
-
using same assets for localized folders too, without doing duplication of them -
plugin - using
exclude_from_localization. i.e _site/assets and _site/es/assets such duplication can be avoidedmanual - not a problem as we are creating whole structure manually
-
parallel/serial language processing -
plugin - using
parallel_localization.it is a interesting feature present in jekyll-polygot (may lack in larger site see here)
plugin which is properly maintained and which offers convinient organization of posts/pages and their metadata should be chosed.incase we replace plugin with different plugin in future, file organization must not effect.
major drawback using it is separation of metadata of page with its content (here).
we can see inorder to localize titles of pages and post we have to maintain whole different list of titles and fetch it in template to render appropriate title
major draw back is we need to assing permalink in frontmatter of each and every post. but this can be cured by settin permalinks in _config.yml
-
consistent site map - generates localized url for each and every post/page throughout the site (even if translation not present for localized version of the file will be generated)
-
fall back - if post is not present in current active language then polygot serves same post present in default language it also supports no translation message if localized version of file is not found. (there can be other cases too if post is only present in non default lang, here polygot is smart it will serve this non default lang version of file for all languages). * easy SEO optimization
polygot is easy to setup plugin, just by adding gem in gem file and enabling them in config.yml
polygot can be easily configured for properties such as available languages, default/fall back language,exclude assets from localization (not copying assests in localized folder of site to avoid redundancy), parallel localization (generate localization parallely for faster site generation (not support of windows environment))
we have all markdown files in docs folder.
docs
├── en
│ └── binary algebra
│ └── binary representation
│ └── ......
├── fr
│ └── binary algebra
│ └─- binary representation
|
| .....
polygot generates localized urls suchs as and hence site structure/folders in such manner
for en:
http://localhost:4000/docs/binary-representation/binary-numbers.html
for zh:
http://localhost:4000/zh/docs/binary-representation/binary-numbers.html
translated version of markdown file can be put in respective language folders as shown in above directory structure and polygot will handle the rest for us.
attributes such as site.title ,site.descriptions etc cannot be localized directly as such variable cant hold multiple values in it. (storing a structure of key-pair value seems unappropriate).
such attributes can be localized by modifying existing layots and includes which use such attributes and feeding proper translation according to active language of site.
we can use polygot site.data and put translation of all atrributes in folder _data
eg:
```
in _data/en/abc.yml
we can access key in layots as site.data.abc.title
polygot access right key according to active language of site
```
we are currently using just the docs theme for gsod branch , strings generated by theme bydefault can be translated by overriding theme.
we can put required format strings for date and time in respective language folders present in _data folder and use them for current active language of site eg:
en.yml
date_format: "%b %e, %Y"
zh.yml
date_format: "%F"
site wide language switcher (change language of page by staying at same page) can be implemented .
using appropriate logic and info through variables such as site.languages, site.default_lang, site.active_lang etc.
basically we have to create a dropdown list use site.languages and link localized version of url of current page for each language we support.
translations of locale in full langauage name can be done in _data folder and can be accessed easily in switcher logic.
when language of current page is not same as active language of site we can provide no translation message.
SEO can be optimized usng html meta tags,http headers,or generating sitemaps through any gem (reference)
polygot provides all the above using just one line in header
in header.html
: {% I18n_Headers <url of site> %}
polygot will do the rest for us and apply SEO in all pages of our site.