Customizing Configuration for Multilingual Hugo-Managed Site

A multilingual site managed with Hugo static generator requires a couple of extra steps. I essence, you just need to tell Hugo which languages are you going to use, and how these languages are called in these languages (Eesti keel for Estonian, Bahasa Indonesia for Indonesian, etc.). The rest is really optional.

Before we begin, though, I’d like to suggest a few

Configuration Adjustments

I Choose YAML and config Directory

Your project configuration sits by default in config.toml file in the project root directory. This isn’t the only choice, though. Instead of a single file you can create a config sub-directory, and split your configuration into several files under it, if your configuration will start getting bushy.

Neither is your file format choice limited to TOML. The alternatives are YAML and JSON. I prefer YAML for its uniformity (and maybe out of habit), so I shall be using it throughout this tutorial.

Adjust the Default Archetype

An archetype is a boilerplate code for your content files. By default, there is one created automatically for you, and it is located under archetypes/default.md. It includes a few parameters to for each article you are going to create: title (to become HTML <title> of a generated page), date, and draft. Since in all likelihood you would like your pages to have a proper description to be exposed in search engine results, add description: TBD parameter as shown here:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
description: TBD
---

… where ‘TBD’ is just a placeholder.

I Call It ‘kontent’

There are two important directories in the root of your project, config and content, that compete with each other in terms of <TAB> completion when you work from a terminal. It would be rather practical to rename content directory into kontent. Now you will need to type k<TAB> instead of cont<TAB>, and c<TAB> instead of conf<TAB>). So,

mv content kontent

You will need to reflect this move in your project configuration, speaking of which…

Create a very basic multilingual configuration

From your project root, create a sub-directory for default configuration:

mkdir -p config/_default

With your favourite editor, create a file config/_default/config.yaml with the following content:

baseURL: "http://example.com/"
title: "Multilingua"
contentDir: "kontent"
languages:
    en:
        languageName: English
        weight: 10
    ru:
        languageName: Русский
        weight: 20

For the time being, baseURL can be whatever you like, if you didn’t buy a domain yet. The title parameter is what you want to append to every page title of your site. The languages section tells Hugo that your site will be in two languages, English and Russian, and that when available languages are listed, English comes before Russian - this is dictated by weight parameter. The lower the weight, the higher the priority.

Language configuration in a separate file.

To keep things tidy, you may choose to move the languages section into separate file. I recommend that you do, as it may grow substantially. In this case, create a file config/_default/languages.yaml:

en:
    languageName: English
    weight: 10
ru:
    languageName: Русский
    weight: 20

Notice, that languages key from the all-in-one config file has become the filename and it will be an error to include it into config/_default/languages.yaml. Also, don’t forget to remove the language section from config/_default/config.yaml.

Remove the generated configuration file

… or it will take priority over the configuration you’ve just created.

rm config.toml