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.
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.
[alternatives.en] name = English primary = yes locale = en_US [alternatives.fr] 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.
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 contents+ALT.lr 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 contents.lr file.
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:
| contents.lr | contents+fr.lr | contents+en.lr | Target | File Used |
|---|---|---|---|---|
| ✓ | en | contents.lr | ||
| ✓ | fr | contents.lr | ||
| ✓ | ✓ | en | contents.lr | |
| ✓ | ✓ | fr | contents+fr.lr | |
| ✓ | ✓ | en | contents+en.lr | |
| ✓ | ✓ | fr | contents+fr.lr | |
| ✓ | en | missing | ||
| ✓ | fr | contents+fr.lr | ||
| ✓ | en | contents+en.lr | ||
| ✓ | fr | missing |
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.
Comments