HisarBlok · documentation
Languages and translating
HisarBlok speaks to two audiences, translated separately: the visitors of a published site and the editors in the admin.
For version 0.13.1.
A multilingual site
Every site picks its languages and a default language. The default language is published at the site root, the others under their own prefix: on this site Turkish is at /, English at /en/. Pages that translate each other are joined by a shared key; the hreflang tags and the language switcher link only to translations that exist. The language button of a page without a translation goes to the other language's home page.
The blog, the forum, member pages, the search index, feeds and the sitemap are per language. A forum category can belong to one language or to all of them. A member has one account; their mail goes out in the language they chose. Dates are written in the page's language, and each site picks its time zone.
Which languages are ready
| Who reads it | What | Languages today |
|---|---|---|
| Visitors | theme wording, the forum, member pages and their mail, comments, forms, downloads, search, redirect pages, the endpoints' answers | Turkish, English, German, Spanish, French, Portuguese, Russian, Arabic |
| Editors | everything behind the sign-in | Turkish, English |
A page speaks the page's language whatever language the admin is in: a German page of a Turkish-run site says "Anmelden" while the admin keeps saying "Giriş". Strings with a number follow the language's plural rules (three forms in Russian, six in Arabic).
Right to left, and addresses in any script
Arabic, Persian, Hebrew and Urdu pages are drawn right to left with dir="rtl"; because the shipped themes use logical CSS properties, the layout turns by itself. Text fields in the admin take each paragraph's direction from its own text.
Addresses made from titles keep the letters of Arabic, Hebrew, Indic, Thai, Chinese, Japanese and other scripts; Cyrillic and Greek are transliterated with a fixed table that gives the same result on every server. Latin titles get exactly the addresses they had before.
Adding a visitor language
- Copy
core/lang/en.visitor.phptocore/lang/<code>.visitor.php(<code>: ISO 639-1, e.g.it,nl,pl). All of the roughly 200 strings a visitor can read are in that list. - Translate every string, keeping placeholders such as
%sand%dand tags exactly as they are. Separate plural forms with|. - The test suite checks that every language file has exactly the same keys, the same placeholders and the right number of plural forms.
A missing translation never breaks a page: the English text shows. A regional variant (pt-BR) only carries the words that differ and takes the rest from its language (pt). A translation that cannot be formatted falls back to the English text instead of an error.
The admin language
Admin strings are English in the code, with a Turkish table. A new admin language is added the same way, and the setup wizard offers the languages listed. We would welcome translators for other admin languages: write to us.
A module's own translations
A module ships translations of its own strings in modules/<name>/lang/<lang>.json. The files are read as JSON, so reading them never runs the module's code. A module can translate only its own strings; it can never change a word of core's.