Changed jekyll-multiple-languages-plugin for polyglot (#18)

Signed-off-by: George Araujo <[email protected]>

.github/workflows/broken-links.yml

@@ -49,4 +49,4 @@ jobs:
         with:
           fail: true
           # removed md files that include liquid tags
-          args: --exclude-path README.md --exclude-path _pages/404.md --exclude-path _pages/blog.md --exclude-path _i18n/en-us/_posts/2018-12-22-distill.md --exclude-path _i18n/pt-br/_posts/2018-12-22-distill.md --verbose --no-progress './**/*.md' './**/*.html'
+          args: --exclude-path README.md --exclude-path _pages/en-us/404.md --exclude-path _pages/pt-br/404.md --exclude-path _pages/en-us/blog.md --exclude-path _pages/pt-br/blog.md --exclude-path _posts/en-us/2018-12-22-distill.md --exclude-path _posts/pt-br/2018-12-22-distill.md --verbose --no-progress './**/*.md' './**/*.html'

.prettierignore

@@ -3,5 +3,5 @@
 assets/css/main.scss
 assets/plotly/demo.html
 lighthouse_results/**
-_i18n/en-us/_posts/2015-10-20-math.md
-_i18n/pt-br/_posts/2015-10-20-math.md
+_posts/en-us/2015-10-20-math.md
+_posts/pt-br/2015-10-20-math.md

CUSTOMIZE.md

@@ -10,28 +10,27 @@ The project is structured as follows, focusing on the main components that you w
 .
 ├── 📂 assets/: contains the assets that are displayed in the website
 │   └── 📂 json/
-│   │   └── 📄 resume_LANG.json: CV in JSON format (https://jsonresume.org/)
+│       └── 📄 resume_LANG.json: CV in JSON format (https://jsonresume.org/)
 ├── 📂 _bibliography/
 │   └── 📄 papers.bib: bibliography in BibTeX format
 ├── 📄 _config.yml: the configuration file of the template
 ├── 📂 _data/: contains some of the data used in the template
 │   ├── 📂 LANG/: data for the LANG version. Must have one for each language defined in _config.yml
-│   │   └── 📄 cv.yml: CV in YAML format, used when assets/json/resume_LANG.json is not found
+│   │   ├── 📄 cv.yml: CV in YAML format, used when assets/json/resume_LANG.json is not found
+|   |   └── 📄 strings.yml: localized variables (placeholders). Must have one for each language defined in _config.yml
 │   └── 📄 repositories.yml: users and repositories info in YAML format
-├── 📂 _i18n/: contains the translations of the template
-│   ├── 📂 LANG/: must have one for each language defined in _config.yml
-│   │   ├── 📂 _news/: the localized content of the news that will appear in the news section in the about page
-│   │   ├── 📂 _pages/: the localized content of some pages
-│   │   ├── 📂 _posts/: contains the localized blog posts
-│   │   ├── 📂 _projects/: contains the localized content of the projects
-│   └── 📄 LANG.yml: localized variables (placeholders). Must have one for each language defined in _config.yml
 ├── 📂 _includes/: contains code parts that are included in the main HTML file
 │   └── 📄 news.liquid: defines the news section layout in the about page
 ├── 📂 _layouts/: contains the layouts to choose from in the frontmatter of the Markdown files
 ├── 📂 _news/: the news that will appear in the news section in the about page
+│   └── 📂 LANG/: must have one for each language defined in _config.yml
 ├── 📂 _pages/: contains the pages of the website
-|   └── 📄 404.md: 404 page (page not found)
+│   └── 📂 LANG/: must have one for each language defined in _config.yml
+|       └── 📄 404.md: 404 page (page not found)
+├── 📂 _posts/: contains the blog posts
+│   └── 📂 LANG/: must have one for each language defined in _config.yml
 ├── 📂 _projects/: contains the projects
+│   └── 📂 LANG/: must have one for each language defined in _config.yml
 └── 📂 _sass/: contains the SASS files that define the style of the website
     ├── 📄 _base.scss: base style of the website
     ├── 📄 _cv.scss: style of the CV page
@@ -67,27 +66,27 @@ The user and repository information is defined in [\_data/repositories.yml](_dat
 
 ## Creating new pages
 
-You can create new pages by adding new Markdown files in the [\_pages](_pages/) directory. The easiest way to do this is to copy an existing page and modify it. You can choose the layout of the page in the [frontmatter](https://jekyllrb.com/docs/front-matter/) of the Markdown file. You can also add new layouts in the [\_layouts](_layouts/) directory if you feel the need for it.
+You can create new pages by adding new Markdown files in the [\_pages](_pages/) directory. The easiest way to do this is to copy an existing page and modify it. To have the page be displayed for different languages, simply create one markdown file with the same name in each language. It is possible to [use different permalinks per language](https://github.com/untra/polyglot?tab=readme-ov-file#using-different-permalinks-per-language) if you want to. You can choose the layout of the page in the [frontmatter](https://jekyllrb.com/docs/front-matter/) of the Markdown file. You can also add new layouts in the [\_layouts](_layouts/) directory if you feel the need for it.
 
 ## Creating new blog posts
 
-To create a new blog post, you can add a new Markdown file in the [\_i18n/LANG/\_posts](_i18n/en-us/_posts/) directory. The [name of the file must follow](https://jekyllrb.com/docs/posts/#creating-posts) the format `YYYY-MM-DD-title.md`. The easiest way to do this is to copy an existing blog post and modify it. Note that some blog posts have optional fields in the [frontmatter](https://jekyllrb.com/docs/front-matter/) that are used to enable specific behaviors or functions.
+To create a new blog post, you can add a new Markdown file in the [\_posts/LANG/](_posts/en-us/) directory. The [name of the file must follow](https://jekyllrb.com/docs/posts/#creating-posts) the format `YYYY-MM-DD-title.md`. The easiest way to do this is to copy an existing blog post and modify it. Note that some blog posts have optional fields in the [frontmatter](https://jekyllrb.com/docs/front-matter/) that are used to enable specific behaviors or functions.
 
 If you want to create blog posts that are not ready to be published, but you want to track it with git, you can create a [\_drafts](https://jekyllrb.com/docs/posts/#drafts) directory and store them there.
 
 ## Creating new projects
 
-You can create new projects by adding new Markdown files in the [\_projects](_projects/) directory. The easiest way to do this is to copy an existing project and modify it.
+You can create new projects by adding new Markdown files in the [\_projects/LANG/](_projects/en-us/) directory. The easiest way to do this is to copy an existing project and modify it.
 
 ## Adding some news
 
-You can add news in the about page by adding new Markdown files in the [\_i18n/LANG/\_news](_i18n/en-us/_news/) directory. There are currently two types of news: inline news and news with a link. News with a link take you to a new page while inline news are displayed directly in the about page. The easiest way to create yours is to copy an existing news and modify it.
+You can add news in the about page by adding new Markdown files in the [\_news/LANG/](_news/en-us/) directory. There are currently two types of news: inline news and news with a link. News with a link take you to a new page while inline news are displayed directly in the about page. The easiest way to create yours is to copy an existing news and modify it.
 
 ## Adding Collections
 
 This Jekyll theme implements `collections` to let you break up your work into categories. The theme comes with two default collections: `news` and `projects`. Items from the `news` collection are automatically displayed on the home page. Items from the `projects` collection are displayed on a responsive grid on projects page.
 
-You can easily create your own collections, apps, short stories, courses, or whatever your creative work is. To do this, edit the collections in the [\_config.yml](_config.yml) file, create a corresponding folder, and create a landing page for your collection, similar to [\_pages/projects.md](_pages/projects.md).
+You can easily create your own collections, apps, short stories, courses, or whatever your creative work is. To do this, edit the collections in the [\_config.yml](_config.yml) file, create a corresponding folder, and create a landing page for your collection, similar to [\_pages/LANG/projects.md](_pages/en-us/projects.md).
 
 ## Adding a new publication
 
@@ -128,7 +127,7 @@ If the entry matches one form of the last names and the first names, it will be
     url: https://en.wikipedia.org/wiki/Carl_Philipp_Emanuel_Bach
 ```
 
-If the entry matches one of the combinations of the last names and the first names, it will be highlighted and linked to the url provided.
+If the entry matches one of the combinations of the last names and the first names, it will be highlighted and linked to the url provided (see [related discussion](https://github.com/alshedivat/al-folio/discussions/2213)).
 
 ### Buttons (through custom bibtex keywords)
 

Gemfile

@@ -10,8 +10,8 @@ group :jekyll_plugins do
     gem 'jekyll-jupyter-notebook'
     gem 'jekyll-link-attributes'
     gem 'jekyll-minifier'
-    gem 'jekyll-multiple-languages-plugin'
     gem 'jekyll-paginate-v2'
+    gem 'jekyll-polyglot'
     gem 'jekyll-scholar'
     gem 'jekyll-sitemap'
     gem 'jekyll-toc'

README.md

@@ -242,7 +242,9 @@ For customization details please refer to [CUSTOMIZE.md](CUSTOMIZE.md).
 
 ### Multi Language Support
 
-The default language will be the first in the list of languages in the [\_config.yml](_config.yml) file. When using two languages, the theme will show a button in the header that switches to the other language directly.
+In a previous version this was achieved using the [jekyll-multiple-languages-plugin](https://github.com/kurtsson/jekyll-multiple-languages-plugin), but since the plugin repository has been archived it was replaced by the [polyglot](https://github.com/untra/polyglot) plugin. This plugin was created based on the functionalities of the [jekyll-multiple-languages-plugin](https://github.com/kurtsson/jekyll-multiple-languages-plugin) and it is actively maintained. For more information about this change, see [UPGRADING.md](UPGRADING.md).
+
+The default language (and used as a fallback language when a link for a different language is not found) will be the language defined as `default_lang` in the [\_config.yml](_config.yml) file. When using two languages, the theme will show a button in the header that switches to the other language directly.
 
 ![Switch language](assets/img/readme_preview/multi-language-diff-1.png)
 ![Switch back language](assets/img/readme_preview/multi-language-diff-2.png)
@@ -255,7 +257,7 @@ When using three or more, it will be created a dropdown menu with all the availa
 
 ![Switch language between 3 or more](assets/img/readme_preview/multi-language-3-or-more.png)
 
-Note that throughout the [README.md](README.md) and [CUSTOMIZE.md](CUSTOMIZE.md) files, the default language is English (LANG = en). You must have an equivalent file or path for each language you have defined in [\_config.yml](_config.yml). For example, if you have defined `languages: ["en-us", "pt-br"]`, you must have 2 versions of the file `_data/LANG/cv.yml`: [\_data/en-us/cv.yml](_data/en-us/cv.yml) and [\_data/pt-br/cv.yml](_data/pt-br/cv.yml).
+Note that throughout the [README.md](README.md) and [CUSTOMIZE.md](CUSTOMIZE.md) files, the default language is English (LANG = en-us). You must have an equivalent file or path for each language you have defined in [\_config.yml](_config.yml). For example, if you have defined `languages: ["en-us", "pt-br"]`, you must have 2 versions of the file `_data/LANG/cv.yml`: [\_data/en-us/cv.yml](_data/en-us/cv.yml) and [\_data/pt-br/cv.yml](_data/pt-br/cv.yml).
 
 ---
 
@@ -325,8 +327,8 @@ For more details on how to create distill-styled posts using `<d-*>` tags, pleas
 **al-folio** supports fast math typesetting through [MathJax](https://www.mathjax.org/) and code syntax highlighting using [GitHub style](https://github.com/jwarby/jekyll-pygments-themes). Also supports [chartjs charts](https://www.chartjs.org/), [mermaid diagrams](https://mermaid-js.github.io/mermaid/#/), and [TikZ figures](https://tikzjax.com/).
 
 <p align="center">
-<a href="https://george-gca.github.io/multi-language-al-folio/blog/2015/math/" target="_blank"><img src="assets/img/readme_preview/math.png" width=400></a>
-<a href="https://george-gca.github.io/multi-language-al-folio/blog/2015/code/" target="_blank"><img src="assets/img/readme_preview/code.png" width=400></a>
+<a href="https://george-gca.github.io/multi-language-al-folio/blog/2015/math/" target="_blank"><img src="assets/img/readme_preview/math.png" width=400 alt="example of post with math"></a>
+<a href="https://george-gca.github.io/multi-language-al-folio/blog/2015/code/" target="_blank"><img src="assets/img/readme_preview/code.png" width=400 alt="example of post with code"></a>
 </p>
 
 #### Photos, Audio, Video and more

UPGRADING.md

@@ -0,0 +1,51 @@
+# Upgrading
+
+As of Jan 15, 2024, the [jekyll-multiple-languages-plugin](https://github.com/kurtsson/jekyll-multiple-languages-plugin) repository has been archived by its owner and is now read-only, meaning it will not receive further updates. As discussed in [#17](https://github.com/george-gca/multi-language-al-folio/issues/17), one possible solution was to replace the plugin with [jekyll-polyglot](https://github.com/untra/polyglot). This change has been implemented as of version 1.11.0 of this theme.
+
+## Project changes
+
+A few changes were made necessary by the switch to `polyglot`. More specifically:
+
+- all usages of `site.lang` were replaced by `site.active_lang`, since this is how the `polyglot` plugin stores the active language
+- moved `_i18n/` contents to their respective `LANG/` directories inside the `_news/`, `_pages/`, `_posts/`, and `_projects/` directories. E.g.: `_i18n/en-us/_pages/about.md` was moved to `_pages/en-us/about.md`
+- a few modifications were made to the `_config.yml` file related to the `polyglot` plugin
+- contents of the files `_i18n/LANG.yml` were moved to `_data/LANG/strings.yml`. Note that not all variables were moved. The rest of the variables were used directly in the pages contents
+
+### Directory changes
+
+[Previously](https://github.com/george-gca/multi-language-al-folio/tree/8f1528a4816aaf16e916791ae0f8cddbecf2416a) some pages were composed by a main page, like the [\_pages/about.md](https://github.com/george-gca/multi-language-al-folio/blob/8f1528a4816aaf16e916791ae0f8cddbecf2416a/_pages/about.md) page, and a translated subpage, like the [\_i18n/en-us/\_pages/about.md](https://github.com/george-gca/multi-language-al-folio/blob/8f1528a4816aaf16e916791ae0f8cddbecf2416a/_i18n/en-us/_pages/about.md). This structure was changed to a single page with all the content in the same file, one file for each language in [\_pages/LANG/](https://github.com/george-gca/multi-language-al-folio/tree/polyglot/_pages/en-us). This change was made to simplify the structure of the theme and to make it easier to maintain. It also allows to have completely different pages for different languages if needed.
+
+### Translated strings
+
+Another change was the usage of translated strings in the pages. Before, the translated strings were used in the pages by using the `t` filter, like `{% t titles.about %}`, and these strings were defined inside [\_i18n/LANG.yml](https://github.com/george-gca/multi-language-al-folio/blob/8f1528a4816aaf16e916791ae0f8cddbecf2416a/_i18n/en-us.yml). Now, when possible, the translated strings are used directly in the pages for that language. When a string is used at the layout level, like in the [\_layouts/about.liquid](_layouts/about.liquid) file, we now have to call for the translated string inside [\_data/LANG/strings.yml](https://github.com/george-gca/multi-language-al-folio/blob/polyglot/_data/en-us/strings.yml). What previously was:
+
+```liquid
+{% t main.contact_note %}
+```
+
+now is:
+
+```liquid
+{{ site.data[site.active_lang].strings.contact_note }}
+```
+
+### Other information
+
+Due to the usage of the `polyglot` plugin, a lot of the previous workarounds were made unnecessary. For example, the `t` filter was used to translate the `page.title` and `page.description` variables in a lot of different files. Now, the values of these variables can be directly used. The same applies to some solutions regarding page redirects or assets usage. For example, in the file [\_layouts/archive-category.liquid](_layouts/archive-category.liquid), we had this piece of code:
+
+```liquid
+{% assign is_asset = post.redirect | startswith: '/assets/' %}
+{% if is_asset %}
+  <a class="post-link" href="{{ post.redirect | prepend: site.baseurl_root }}">{{ post.title }}</a>
+{% else %}
+  <a class="post-link" href="{{ post.redirect | prepend: site.baseurl }}">{{ post.title }}</a>
+{% endif %}
+```
+
+Which was responsible to assess if the `post.redirect` was an asset or a page and to build the correct link considering the current language. Now, we can simply use:
+
+```liquid
+<a class="post-link" href="{{ post.redirect | relative_url }}">{{ post.title }}</a>
+```
+
+since the `polyglot` plugin takes care of the language prefix in the URLs.

_config.yml

@@ -8,8 +8,6 @@ middle_name: R.
 last_name: Name
 email: [email protected]
 keywords: jekyll, jekyll-theme, academic-website, portfolio-website # add your own keywords or leave empty
-
-lang: en-us # the main language of your site (for example: en, fr, cn, ru, etc.)
 icon: ⚛️ # the emoji used as the favicon (alternatively, provide image name in /assets/img/)
 
 url: https://george-gca.github.io # the base hostname & protocol for your site
@@ -115,7 +113,6 @@ bing_site_verification: # out your bing-site-verification ID (Bing Webmaster)
 # Blog
 # -----------------------------------------------------------------------------
 
-blog_nav_title: true
 permalink: /blog/:year/:title/
 
 # Pagination
@@ -226,8 +223,8 @@ plugins:
   - jekyll-jupyter-notebook
   - jekyll-link-attributes
   - jekyll-minifier
-  - jekyll-multiple-languages-plugin
   - jekyll-paginate-v2
+  - jekyll-polyglot
   - jekyll/scholar
   - jekyll-sitemap
   - jekyll-toc
@@ -242,14 +239,9 @@ defaults:
       sitemap: false
 
 sass:
+  sourcemap: never
   style: compressed
 
-# multi language settings
-default_locale_in_subfolder: false
-exclude_from_localizations: ["assets"]
-languages: ["en-us", "pt-br"]
-country_flag: false # set true for allowing flag symbol in language toggle
-
 # -----------------------------------------------------------------------------
 # Jekyll Minifier
 # -----------------------------------------------------------------------------
@@ -334,6 +326,17 @@ external_links:
   target: _blank
   exclude:
 
+# -----------------------------------------------------------------------------
+# Jekyll Polyglot
+# -----------------------------------------------------------------------------
+
+languages: ["en-us", "pt-br"]
+default_lang: "en-us"
+exclude_from_localization: ["assets"]
+lang_from_path: true
+country_flag: false # set true for allowing flag symbol in language toggle
+# parallel_localization: true
+
 # -----------------------------------------------------------------------------
 # Responsive WebP Images
 # -----------------------------------------------------------------------------
@@ -377,7 +380,6 @@ enable_masonry: true # enables automatic project cards arrangement
 enable_math: true # enables math typesetting (uses MathJax)
 enable_tooltips: false # enables automatic tooltip links generated for each section titles on pages and posts
 enable_darkmode: true # enables switching between light/dark modes
-enable_localization: true # enables switching between languages
 enable_navbar_social: false # enables displaying social links in the navbar on the about page
 enable_project_categories: true # enables categorization of projects into multiple categories
 enable_medium_zoom: true # enables image zoom feature (as on medium.com)
@@ -459,7 +461,7 @@ vega-lite:
 # -----------------------------------------------------------------------------
 
 jekyll_get_json:
-  - data: resume_en
+  - data: resume_en-us
     json: assets/json/resume_en-us.json # it can also be an url
   - data: resume_pt-br
     json: assets/json/resume_pt-br.json # it can also be an url