How language selection works

Localization — part 1 of 6

Two different things are called "another language" here, and they are independent:

  • Translating the ENGINE -- the menu, the labels, the dates, the wizards. That is this page, and it is one file of data.
  • Publishing the SITE in more than one language -- posts with a text per language, a root per language, a switcher. That is Publishing in more than one language at the foot of this page.

A site can do either without the other: a Czech blog whose engine speaks Czech publishes one language, and a blog published in Czech and German needs both locales to exist first.

How to translate blog.sh -- the generated site and the CLI wizards -- into a language it doesn't ship yet. No code changes are involved: a language is data, and a partial translation is useful from day one.

site.lang in config/site.yml picks locales/<lang>.yml. Every string the engine renders or prints goes through that file, and any key missing from it falls back to English individually (lib/i18n.rb) -- so a half-finished locale shows your language where it exists and English where it doesn't, instead of breaking. Only locales/en.yml must stay complete: it is the fallback for everyone, and the build aborts if a key is missing from both.