One particularly useful feature of Lektor is the ability to define alternatives to a content file. This allows you to translate your website into many different languages or to customize content specifically for some languages or regions.

Alternatives are a fully functional feature in Lektor but very underdocumented and lacking in parts. The result of this is that it might not be working exactly as you expect in parts. In particular one of the limiting factors is that you need to have at least one alternative at the URL root or the system will refuse to build the website.

Enabling Alternatives

To enable alternatives you need to extend your Project File. For each alternative a new section has to be added. It's important that one of the alternatives is marked as "primary" which informs the system which of the alternatives is the reference.

name = English
primary = yes
locale = en_US

name = French
url_prefix = /fr/
locale = fr

The locale key is used to define the locale that Lektor assumes for the alternative. This is for instance used for date formatting.

Content Files of Alternatives

Once alternatives are enabled your website will be built multiple times. Once for each alternative. By default nothing will change as no content files exist for the non primary alternatives. In the example of above if you navigate to /fr/ you will see the same index page as if you would have navigated to /.

However you can now start translating your content. Each alternative has a content file named where ALT is the short code of your alternative (for instance fr for French). Once a file for an alternative exists it's loaded instead of the default file.

What's Loaded

To make this a bit more concrete: let's go with the example we configured above. There are two alternatives: English (en) and French (fr) and English is configured as the primary.

In that case depending on which files exist and which alternative is targeted, different files will be used. This table visualizes this: Target File Used
en missing
fr missing

Alternatives and Paths

Alternatives have a special behavior with regards to paths. The alternative code does not exist in the path! This can be confusing at first, but has the advantage that they automatically work in most places as the paths are the same for different alternatives. For more information see Alternatives and Paths.