Contents

How to localize permalinks in Hugo: a workaround

And a word or two on going open source

When working with Hugo’s multilingual mode, it’s nothing but natural to wonder whether it exists a simple and direct way to localize (i.e. translate) the articles permalinks.

I couldn’t find a direct way to achieve it. Fortunately, it does exist a simple way to do it, which I’ll cover here.

Configs

This article assumes the following prerequisites, which the solution was tested with. Other configurations should also work after a few tweaks (or none at all).

For this tutorial I’ll use the source code of this article itself. You can find it here.

1. Enable slugorfilename in the config file

Navigate to your config file and under the Permalinks section set the posts field to slugorfilename:

1
2
[Permalinks]
  posts = ":slugorfilename"

2. Set a proper slug in the front matter of your content files

This article (and the whole website) has two versions: one in English and one in Spanish. The English filename is index.en.md, whereas the Spanish one is index.es.md. We need to set a slug for each of them, since is not possible to set only the English one and then translate it to Spanish.

For the English one, in the front matter:

1
2
slug: "localizing-permalinks"
aliases:

For the Spanish one:

1
2
slug: "traducir-enlaces"
aliases:

So far, so good. When the site is built, the English content is accesible via /localizing-permalinks/ and the Spanish content can be reached by following /es/traducir-enlaces. But what happens if we request /traducir-enlaces/ or /es/localizing-permalinks?

Failure

/localizing-permalinks/failure_slug_en.png
The ubiquitous Error 404

/localizing-permalinks/failure_slug_es.png

We can go a step further and improve the website’s behavior by using aliases.

3. [Optional] Use aliases to redirect the translated content

The content it’s already linked by Hugo since we’re using a translation by filename approach. However, if a curious reader (or a bilingual one) wants to access the corresponding translation by typing in the permalink, will receive an error.

To correct that, we add the following in the front matter:

index.en.md

1
2
slug: "localizing-permalinks"
aliases: "traducir-enlaces"

index.es.md

1
2
slug: "traducir-enlaces"
aliases: "localizing-permalinks"

That way the slugs will redirect properly.

A closing thought on going open source

I started this website a few days ago (first post here) and from the beginning I was sure that I wanted it to be open source. In short, that means that the code for building this site is publicly available here.

There are a few reasons for that:

  • I love open source. Most of the things I know about development I learned from others, by reading articles or diving in their codebases.
  • This is a solo project, but that doesn’t mean it has to be a mess. Being open source pushes me to adopt a set of best practices and stick to it.
  • It’s a great way to showcase my learning path.