languages.toml

Before you begin

If you didn’t use the Alpha Starter Site, copy the entire config folder (themes/alpha/config/) to your site’s root directory before editing anything.
This ensures that your changes are preserved and won’t be overwritten by future Alpha updates.

Overview

The config/_default/languages.toml file defines the languages supported by your site and sets the order and display name for each. Alpha is multilingual ready.

Usage

If your site is multilingual or your main language is not English, you need to declare the supported languages in the languages.toml file.

Language Entry Format

[en]
  weight = 1
  languageName = "English"
  languageCode = "en"

To add a second language, for example Canadian French:

[en]
  weight = 1
  languageName = "English"
  languageCode = "en"

[fr]
  weight = 2
  languageName = "Français"
  languageCode = "fr-CA"

Best Practices

Alpha uses filename based translation, not directories. To learn more about setting up a multilingual site with Alpha, refer to the Multilingual documentation.

If multiple languages are found in languages.toml the language switch is activated.

Keys Reference

Each language key is defined under a section (table) with a language code (ex. [en]).
Only two or three-letter codes are valid here.
For region or variants of the language, use the languageCode key.

weight: weight = 1 — (integer, recommended); Sets the order of the languages. Lower values have priority.
languageName: languageName = "English" — (string, recommended); Full display name of the language, shown in the language switch.; If missing, triggers the ocd-lang-100 error.
languageCode: languageCode = "en-US"— (string, optional); The IETF language tag used to define the content language for browsers and search engines.; Can be a simple two-letter code (en), a language-region pair (fr-CA), or a more specific form like hy-Latn-IT-arevela. For valid formats and examples, refer to RFC 5646 Appendix A.; If omitted, the language code from the section will be used.