Skip to content

Commit

Permalink
Changed jekyll-multiple-languages-plugin for polyglot (#18)
Browse files Browse the repository at this point in the history
Signed-off-by: George Araujo <[email protected]>
  • Loading branch information
george-gca authored Feb 25, 2024
1 parent 8f1528a commit bee6a86
Show file tree
Hide file tree
Showing 152 changed files with 1,266 additions and 786 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/broken-links.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'
4 changes: 2 additions & 2 deletions .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
31 changes: 15 additions & 16 deletions CUSTOMIZE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion Gemfile
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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).

---

Expand Down Expand Up @@ -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
Expand Down
51 changes: 51 additions & 0 deletions UPGRADING.md
Original file line number Diff line number Diff line change
@@ -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.
26 changes: 14 additions & 12 deletions _config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
# -----------------------------------------------------------------------------
Expand Down Expand Up @@ -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
# -----------------------------------------------------------------------------
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit bee6a86

Please sign in to comment.