Built with Chinaski

Set Up a Multilingual Site

Authors write, and visitors read, in as many languages as you enable. This guide walks through going from a single-language site to full multilingual publishing: turning languages on, structuring URLs, authoring each locale, and translating efficiently where the tooling can help.

One-time setup

  1. Set the languages: Settings → General → Active Languages, a comma-separated list of two-letter codes (optionally regional, like zh-cn). Save the list before touching anything else. Each entry is validated (lowercase code, optional suffix); an empty list falls back to en.
  2. Pick the default language: the fallback language used when a translation is missing, the homepage anchor, and the x-default hreflang target. It must always be present in the list; if your save submits one that isn’t, it clamps to the first listed code.
  3. Let the URL mode settle: under Settings → Permalinks the Language URL Mode re-derives when your language count changes:
    • one language → no URL segment;
    • multiple languages → path mode (/en/…, /es/…);
    • subdomain mode is your own choice and stays that way until you change it; each language then is served from a subdomain like es.example.com.

Every output directory is per-language, so a change in language count reshapes the file layout at the next build; you rarely need to touch the mode by hand, but it’s worth checking after a save if you’re seeing unexpected /en/ prefixes (also see the Redirects & 404s troubleshooting page).

  1. Feeds and menus need per-language data. Menu items are per-language (each language has its own header/footer menus); the blog URL prefix and blog index title accept per-language overrides; URLs are served under /{lang}/… in path mode.

Authoring in two or more languages

Set language per item. Each page, post, block, snippet, and nav item has a Language dropdown (all items come from that list). Every language is a row: translating a page means saving a duplicate row in a different language, linked by the translation machinery.

Slugs pair with the language: two pages sharing a slug can coexist in two languages without conflicts, and both are linked in hreflang output.

Useful efficient helpers:

  • Create translations in bulk: clone an existing item into the missing languages from the Tools → Translations matrix, in one go.
  • Use the AI integrations: template translation helpers fetch the original record, copy it, and apply your supplied title/body translations, so you only write the language content.
  • Decide where forms go: with per-language pages, public forms apply to whichever language it’s embedded into the body. Forms are language-neutral (they work the same in all languages).

How the built site is organized

In path mode each language sorts its output under its own directory: /en, /es, with pages/posts under their blog prefix, per language; category pages, feeds, sitemap, robots, or search-index created per language. Menus and shares (from content types above) carry their items’ language. hreflang alternates are generated between languages with the x-default entry pointing at the default language’s corresponding page.

Air-gap mode doesn’t change URL planning by itself; what matters is the URL mode: single-language sites use one root with no per-language subtree, and monolingual sites generate no hreflang links at all.

Maintenance

  • Missing translations: the Tools → Translations screen is the dashboard. It matrixes every translated item per language (and detects forms, per the tool definition). Fill in missing items when ready.
  • Untranslated blocks fall back to the default language’s version in the built page, so pages never look broken because one block is missing in a language. Translate as the text becomes ready.
  • Deleting a language from the list requires clearing its content; any lingering pages/posts/blocks hold the save and tells you the counts.

A caution on languages that lag

Most multilingual sites grow unevenly: a language starts with menus and a couple of pages while the rest of the content catches up. Two verified behaviors help you plan:

  • Per-item hreflang links only appear when the destination language actually has a version of that item, so incomplete translations won’t send visitors to 404s.
  • The default-language content is the model: the missing-language fallback serves it, and translation helpers start from it.
Read this site in