untra
Polyglot lacks something in the documentation to make it easy to use
I've been trying to get it working for more time that I would like to admin and it is still not working, the documentation seems to be confusing and unclear.
I have a simple job to be done. I would like to have an index page and to see this 1 index page in two languages.
- Create a jekyll project,
- Install polyglot
- Create an index.html
Here is the three structure
kireto@kireto-pc my-website % tree
.
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _layouts
│ └── default.html
├── _site
│ ├── 404.html
│ ├── bg
│ │ ├── 404.html
│ │ ├── feed.xml
│ │ └── index.html
│ ├── feed.xml
│ └── index.html
└── index.html
That is simple enough. There is an index.html that has the following content
---
lang: en
title: Home
layout: default
---
<!doctype html>
<html lang="{{ page.lang }}">
<head>
<meta charset="utf-8">
<title>{{ page.title }}</title>
</head>
<body>
<h1>{{ "Hello World!" | downcase }}</h1>
</body>
</html>
As a result we have _site/index.html and _site/bg/index.html Both with the same content.
And now the question is how do I create a second version of the index.html that will have a different content, because that's the whole job to be done here.
The documentation just says "don't stress about it" but it gives little directions and explanations on how to do it. Like
How To Use It
When adding new posts and pages, add to the YAML front matter:
lang: sv
or whatever appropriate [I18n language code](https://developer.chrome.com/webstore/i18n) 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](https://github.com/untra/polyglot/blob/master/site/_config.yml#L28-L37), and examples of https://github.com/untra/polyglot/pull/155 https://github.com/untra/polyglot/pull/167 https://github.com/untra/polyglot/pull/177.
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:
Organized 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:
Be consistent with how you name and place your posts files
Always give your pages permalinks in the frontmatter
Don't overthink it, 😉
So what we can do from this is create an index-bg.html. file looking at the example for _post. But this does not work.
.
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _layouts
│ └── default.html
├── _site
│ ├── 404.html
│ ├── bg
│ │ ├── 404.html
│ │ ├── feed.xml
│ │ ├── index-bg.html
│ │ └── index.html
│ ├── feed.xml
│ ├── index-bg.html
│ └── index.html
├── index-bg.html
└── index.html
So it is not an appending on the file name
We could try with a new bg folder with index.html in it and we get
kireto@kireto-pc my-website % tree
.
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _layouts
│ └── default.html
├── _site
│ ├── 404.html
│ ├── bg
│ │ ├── 404.html
│ │ ├── bg
│ │ │ └── index.html
│ │ └── feed.xml
│ └── feed.xml
├── bg
│ └── index.html
└── index.html
I think the documentation could benefit from an example of how polyglot could be used. It is still not clear for me how to get same index.html page, two languages accomplished and I kind of stress about it, despite the documentation telling me not to stress about it :D
The way I manage to do it is by adding permalink to the frontmatter
---
lang: en
title: Home
layout: default
permalink: /
---
<!doctype html>
<html lang="{{ page.lang }}">
<head>
<meta charset="utf-8">
<title>{{ page.title }}</title>
</head>
<body>
<h1>{{ "Hello World!" | downcase }}</h1>
</body>
</html>
Thanks for the sentence there Always give your pages permalinks in the frontmatter
An example in the documentation could be valuable. Should I prepare one?
It is just confusing to have a page and in the same time to have a permalink in the page and to have this permalink the same as the directory structure. I was expecting that polyglot will interfere this from the directory structure, however I might be wrong.
It is confusing for example how I have this generated
kireto@kireto-pc my-website % tree
.
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _layouts
│ └── default.html
├── _site
│ ├── 404.html
│ ├── bg
│ │ ├── 404.html
│ │ ├── bg
│ │ │ └── index.html
│ │ └── feed.xml
│ ├── feed.xml
│ └── index.html
├── bg
│ └── index.html
└── index.html
When the bg/index.html is
---
title: Home
layout: default
---
<!doctype html>
<html lang="{{ page.lang }}">
<head>
<meta charset="utf-8">
<title>{{ page.title }}</title>
</head>
<body>
<h1>{{ "Български" | downcase }}</h1>
</body>
</html>
and lang_from_path: true
At the same time as lang_from_path is true I would expect that the language comes from the path, but jekyll generates _site/bg and inside of it generates _site/bg/bg
Why would it do that? Is this a bug or the documentation should be improved. Because it says lang_from_path: true but at the same time permalink: should be set for it to work
Hi @thebravoman, I had a similar experience. One thing that helped me was the config setting lang_vars: ["lang"]. This was because the theme(chirpy) uses "lang" to lookup translations. That is how I got my index pages working. Hope that helps. (I'd also like to explore what could be improved here.)
Hi @thebravoman, I had a similar experience. One thing that helped me was the config setting
lang_vars: ["lang"]. This was because the theme(chirpy) uses "lang" to lookup translations. That is how I got my index pages working. Hope that helps. (I'd also like to explore what could be improved here.)
You can refer to my blog. I achieved this by modifying the theme. Replace all site.data.locales.lang to site.data.locales[site.active_lang] can resolve the problem.
In a word, whenever you want to do something with the polyglot, you need to insert site.active_lang into the HTML template. This means if you want to integrate Polyglot into Chirpy, you must fork/clone the theme repository and do some customization work.
I found that Untra has already posted an article to explain this: https://polyglot.untra.io/2024/02/29/localized-variables/
