Set a site's languages and language URLs

• Sign in with an account that holds admin:dashboard:setting, or a wildcard that covers it, such as admin:dashboard:*. See How permissions work.
• Have the language codes: two or three lowercase letters, such as en or fa, with an optional region, such as pt-br.
• A master account also sees a Settings for list. See Sites, masters and global records.

1. In the admin sidebar, click Settings, then open the General tab.
2. As a master, pick the scope in Settings for. Global sets the list for every site that has no list of its own. A site's own list replaces the global one. As a site admin, the page edits your site and a badge names it.
3. In Languages, type the codes separated by commas, such as en, fa, ar.
4. Click Save Changes. The page answers Settings saved.

The Languages and Language in addresses fields on the General tab.

The CMS trims each code, lowercases it and drops repeats. A list that is empty, or holds text that is not a language code such as Persian, is not saved, and the page answers Some settings could not be saved. The change applies on the next request, with no restart.

• An address that names no language is answered in it, when addresses leave it unprefixed.
• The x-default alternate in the head of a page that exists in several languages points to the edition in it.
• A link built with site_path/2 and no language uses it.

The language switcher in the header lists the languages a page is written in, in the order of the Languages field, so the first language leads it. A page in fewer than two languages has no switcher. For a record that an extension answers for, such as a blog post, the switcher offers only the languages in this list, so a language you remove disappears from it. See Languages and language editions.

In Language in addresses, choose one of two styles. Both keep the stored paths of your pages as they are, so switching rewrites no page.

• The option that begins The first language has no prefix is the default.
• The option that begins Every language has a prefix puts the language in every address.

Take a site with en first and fa second, and a page stored at /:lang/blog that answers both languages. The style decides what a visitor gets:

The CMS remembers the language a visitor reads in. If the site later stops listing that language, the memory is ignored and the visitor gets the first language.

In a template, build links with site_path/2 so they follow the style you chose:

<.link navigate={site_path("/:lang/about", @page.language)}>About</.link>

A master sees two more fields on the General tab in the Global view. Site admins do not see them.

• Languages sites may publish: a site can list only these codes. Leave it empty to allow any language.
• Languages every site publishes: these codes are part of every site's list, whether the site listed them or not. Leave it empty to require none.

A code outside the allowed list is not saved. If a site's list loses every code to the allowed list, the site publishes the required languages, else the first allowed language.

Adding a language does not create pages in it. Three things follow:

• A page whose path has :lang starts answering the language, but only if it is written in that language or is marked to answer every language.
• To write a page in the language, add a translation. See Translate a page.
• Words that templates ask for with t() get a row in the new language when the template is next saved, or when you click Scan templates on the Translations screen. See Translate interface words with t().

Removing a language closes its /:lang addresses, which then answer the not-found page. A page stored at a literal path, such as /fa/about, keeps answering that path.

The language menu of the dashboard offers the site's languages and English.

1. Open Settings, then the General tab.
2. Set Languages to en, fa.
3. Choose the Every language has a prefix option in Language in addresses.
4. Click Save Changes.
5. In a browser that has not read the site yet, open /blog. The CMS sends you to /en/blog.

• Translate a page: write a page in the new language.
• Languages and language editions: how the list, the address and the editions fit together.
• Settings: every setting key, with its default.