README

hexo-multilang

Multi-language plugin for Hexo. Helps you manage a Hexo page whose contents are written in different languages.

Based in hexo-generator-basic-set and hexo-generator-i18n.

Demo

You can see this plugin in use in maldorne.org, a Hexo blog which uses the hexo-multilang plugin with a modified version of the Chic theme. It has a language selector in the upper right corner, so you can see the blog changes not only the language of the theme, but the language of the contents, also.

How to test the plugin in an easy way

This plugin provides functions which can help you build a multilang theme. The fastest way to see what can be achieved would be using an already compatible theme, so you could compare code and include the functionalities you would need in your own page. I've modified a version of the Chic Theme to make it compatible with hexo-multilang, which you can found in hexo-chic-theme-multilang. Take a look to its installation instructions if you want to test it in a local Hexo Blog, so you can see if this is what you are looking for.

Installation

$ npm install hexo-multilang

Remove any of these packages if they are installed:

$ npm remove hexo-generator-archive hexo-generator-category hexo-generator-index hexo-generator-tag hexo-generator-basic-set hexo-generator-i18n

In Hexo the list of plugins installed will be taken from the package.json file, and will be loaded and executed in the order which they are found in. Any change or update to this file, locally or in a continuous integration environment, might be able to set its contents in alphabetical order, potentially changing your expected results. As the generators (archive, index, tag, category) are called by the same name in every plugin, the last plugin which uses them will have precedence.

So, until Hexo has a better way of handling the loading and execution of plugins, my recommendation is to uninstall any other plugin which includes the same generators or helpers, like the four default ones (the npm remove you can see above these lines), or the plugins hexo-multilang is based on, like hexo-generator-basic-set and hexo-generator-i18n.

Config

_config.yml

plugins:
  hexo-multilang:
    languages: [en, es]  

    pagination-dir: page

    index-generator:
      per-page: 5
      order-by: -date
      index-dir: 
      default-lang: en

    archive-generator:
      per-page: 10
      order-by: -date
      archives-dir: archives
      yearly: true
      monthly: true
      daily: false

    category-generator:
      per-page: 10
      order-by: -date
      categories-dir: categories
      enable-index-page: true

    tag-generator:
      per-page: 5
      order-by: -date
      tags-dir: tags
      enable-index-page: true

Post creator modified

When you create a new blog post, it will be created (based on the corresponding scaffold) in every language set in the _config.yml file. i.e: for a config with:

language: [en, es]
permalink: :language/:year/:month/:day/:title/
new_post_name: :language/:year/:month/:day/:title.md

the creation of a new post will be like this:

$ hexo new 'Something something'
INFO  Posts created in: en, es
INFO  Created: /<your path>/source/_posts/es/1900/01/01/something-something.md
INFO  Created: /<your path>/source/_posts/en/1900/01/01/something-something.md

Helpers included

url_for

This plugin overwrites the original hexo url_for helper with a new one. By default it would prepend the needed language in the url path: https://domain.com/some/thing/ would be https://domain.com/<lang>/some/thing/. If you need the original helper, it is saved as __hexo_multilang_url_for.

<a href="<%- url_for(post.path) %>"><%= post.title %></a>

It also accepts a second parameter with options:

url_for(path, { ignore : bool, language : string })

If ignore is present and is true, the url_for helper will behave as the original Hexo helper. This is useful to use for assets or other urls which would not be multilanguage. When you use this plugin with an already installed template, you will have to add this parameter to the links in the <head> of the web, like css, js, etc.

<% theme.stylesheets.forEach(url => { %>
<link rel="stylesheet" href="<%- url_for(url, { ignore: true }) %>">
<% }); %>

If language is present and is one of the languages defined as an option in the plugin configuration, the language part of the url will be forced to be this value.

License

MIT

Usage no npm install needed!