Taglocalization⁶

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.

1. locales/<lang>.yml -- copy locales/en.yml and translate the values (never the keys). The sections, roughly in order of what a visitor vs. an author sees:

• Placeholders survive verbatim. %{count}, %{slug}, %{path} -- same set as the English string, spelled exactly. A renamed placeholder isn't substituted and the reader sees %{cout} in the output.
• Prompts keep their trailing space. A string ending ": " puts the cursor one space after the colon; drop the space and input sticks to it.
• There is no plural system, on purpose. Write count phrases so one wording works for any number -- the way the Czech locale phrases around its three plural forms, or a neutral Posts: %{count} shape. Don't invent one:/many: variants; nothing reads them.
• Some terms stay untranslated: repost, boost, reblog name three distinct mechanisms on three networks and are established loanwords; Markdown and RSS are names.
• Use your language's own typography -- quotes („…", «…», “…”), dashes, spacing. The English text is the meaning, not the punctuation.
• Multi-line messages may reflow. Match the content, not the line count.

Key parity against English (empty arrays = complete):

ruby -ryaml -e '
def keys(h, p = ""); h.flat_map { |k, v| v.is_a?(Hash) ? keys(v, "#{p}#{k}.") : ["#{p}#{k}"] }; end
en = keys(YAML.load_file("locales/en.yml")); xx = keys(YAML.load_file("locales/de.yml"))
p missing: en - xx, extra: xx - en'

Then see it live: set site.lang: <lang> in config/site.yml, and

ruby build/build_blog.rb        # the site side
./blog.sh preview                # read a post page, /search/, /markdown/, /404.html
./blog.sh help                   # the CLI side
./blog.sh                        # the wizard menu
./blog.sh doctor                 # and check, stats, export -- the reporting sections
./import.sh --help

A placeholder typo shows up immediately as a literal %{...} in the output -- worth grepping the rendered public.nosync/ for %{ before submitting.

• Right-to-left languages. The templates don't mirror the layout (dir="rtl" is not set anywhere), so an Arabic or Hebrew locale would render left-to-right. Honest status: not supported until someone does the layout work, which is CSS and templates, not YAML.
• Slugs stay ASCII. Titles are transliterated (NFKD plus a table for ß, ł, œ and friends -- see lib/slug.rb); scripts that don't transliterate (CJK, Cyrillic, Arabic) produce an id-based slug instead. URLs work either way.

site.lang is the language the site is WRITTEN in; site.locales is the list of languages it is PUBLISHED in:

site:
  lang: cs
  locales: [cs, de]

Both locale files have to exist (locales/cs.yml, locales/de.yml) -- that is the first half of this page.

A language the engine has not been translated into

The engine ships en, cs and de. Naming any other language in site.locales stops the build and says so: without words of its own that branch would quietly inherit English, which is worse than being told.

There are three ways out, and the third one is why this section exists:

# config/site.yml -- the site, and one sentence about its languages
site:
  lang: cs
  locales: [cs, sk]