Standard library · Text

i18n

A multilingual program: translating messages, placing values into them and choosing singular or plural.

import i18n

If your program has to speak several languages, do not write the messages into the code. Put them in a translation catalog under a key, and ask for the user's language when you display one.

Every catalog has a fallback language. When a message has no translation in the user's language, the fallback is shown, and when that is missing too, the key itself; so the program never shows an empty message.

For formatting dates in the Persian calendar see calendar, and for Persian digits and text direction unicode and bidi; this package only handles which message to show.

Things to know

  • An empty translation counts as missing, so T falls back past it.
  • Plural knows two forms: .one for exactly 1 and .other for everything else, 0 included. Languages with more forms, such as Arabic or Russian, need their own logic around it.
  • DetectLocale checks SALAM_LOCALE, then LANG, then LC_ALL, so LANG wins over LC_ALL, the reverse of the POSIX rule. With none of them set it returns en; with LANG=C it returns c.
  • Lookups walk the whole catalog, which is fine for a few hundred messages per language. For thousands, keep your own HashMap of the lines you use most.

Translate the words of a menu

Pick short, stable keys such as menu.save and keep the real text out of the code. Fill the catalog once at start up, then ask T for each label in the user's language. A language with only some of the keys still works: the missing labels come from the fallback language, and a language you never added at all shows the fallback everywhere.

i18n-guide-menu.salam
import i18n

func setup(c &: i18n.Catalog):
    i18n.Set(c, "en", "menu.open", "Open")
    i18n.Set(c, "en", "menu.save", "Save")
    i18n.Set(c, "en", "menu.quit", "Quit")
    i18n.Set(c, "fa", "menu.open", "باز کردن")
    i18n.Set(c, "fa", "menu.save", "ذخیره")
    i18n.Set(c, "fa", "menu.quit", "خروج")
    i18n.Set(c, "de", "menu.open", "Öffnen")
    i18n.Set(c, "de", "menu.save", "Speichern")
end

func show_menu(c &: i18n.Catalog, lang: str):
    open := i18n.T(c, lang, "menu.open")
    save := i18n.T(c, lang, "menu.save")
    quit := i18n.T(c, lang, "menu.quit")
    println lang + ":", open, "|", save, "|", quit
end

func main:
    mut c := i18n.New("en")
    defer i18n.Free(c)
    setup(c)
    each lang in ["en", "fa", "de", "ja"]:
        show_menu(c, lang)
    end
end
Outputen: Open | Save | Quit fa: باز کردن | ذخیره | خروج de: Öffnen | Speichern | Quit ja: Open | Save | Quit

Keep translations in files

Translators should not have to edit Salam code. Give each language its own file of key = value lines and load it with LoadLocale, which returns how many keys it read. Placeholders such as {name} stay in the text and Tf fills them in the same call that translates.

i18n-guide-files.salam
import i18n
import io

func main:
    io.WriteFile("en.txt", "# English\ntitle = Notes\nwelcome = Welcome back, {name}\nprice = 'Only $5 # today'\n")
    io.WriteFile("fa.txt", "# Persian\ntitle = یادداشت‌ها\nwelcome = {name}، خوش برگشتی\n")
    mut c := i18n.New("en")
    defer i18n.Free(c)
    println "en keys:", i18n.LoadLocale(c, "en", "en.txt")
    println "fa keys:", i18n.LoadLocale(c, "fa", "fa.txt")
    mut names := Vector {} as Vector<str>
    mut values := Vector {} as Vector<str>
    defer names.Free()
    defer values.Free()
    names.Push("name")
    values.Push("Sara")
    each lang in ["en", "fa"]:
        println i18n.T(c, lang, "title")
        println i18n.Tf(c, lang, "welcome", names, values)
        println i18n.T(c, lang, "price")
    end
end
Outputen keys: 3 fa keys: 2 Notes Welcome back, Sara Only $5 # today یادداشت‌ها Sara، خوش برگشتی Only $5 # today

The files are read with the same parser as .env files (see config). That means a line starting with # is a comment, an unquoted # in a value starts a comment too, and ${...} is expanded. Put a value in single quotes, as the price line does, when it contains either of them.

Numbers and plurals

Plural chooses between key.one and key.other, and Interpolate then places the number in the chosen text. Persian usually needs one form only (۵ فایل), but watch the fallback: if the fallback language has a .one form and your language does not, n = 1 shows the fallback's text. Defining .one in every language avoids the surprise.

i18n-guide-plural.salam
import i18n
import str

func count_message(c &: i18n.Catalog, lang: str, key: str, n: int): str:
    mut names := Vector {} as Vector<str>
    mut values := Vector {} as Vector<str>
    defer names.Free()
    defer values.Free()
    names.Push("n")
    values.Push(str.FromInt(n))
    ret i18n.Interpolate(i18n.Plural(c, lang, key, n), names, values)
end

func main:
    mut c := i18n.New("en")
    defer i18n.Free(c)
    i18n.Set(c, "en", "files.one", "{n} file selected")
    i18n.Set(c, "en", "files.other", "{n} files selected")
    i18n.Set(c, "fa", "files.other", "{n} فایل انتخاب شد")
    each n in [0, 1, 2, 25]:
        println count_message(c, "en", "files", n), "/", count_message(c, "fa", "files", n)
    end
    i18n.Set(c, "fa", "files.one", "{n} فایل انتخاب شد")
    println count_message(c, "fa", "files", 1)
end
Output0 files selected / 0 فایل انتخاب شد 1 file selected / 1 file selected 2 files selected / 2 فایل انتخاب شد 25 files selected / 25 فایل انتخاب شد 1 فایل انتخاب شد

Choose the user's language

DetectLocale reads SALAM_LOCALE, then LANG and LC_ALL, and reduces a value like fa_IR.UTF-8 to fa. It returns whatever language the system names, so compare the result with the list you actually ship and fall back to your default otherwise. A web server would read the Accept-Language header instead and pass the same short code to T.

i18n-guide-detect.salam
import i18n
import env

func pick_language(wanted: str, supported: Vector<str>, fallback: str): str:
    each s in supported:
        if s == wanted: ret s end
    end
    ret fallback
end

func main:
    mut supported := Vector {} as Vector<str>
    defer supported.Free()
    supported.Push("en")
    supported.Push("fa")
    each setting in ["fa_IR.UTF-8", "EN-us", "de_DE.UTF-8"]:
        env.Set("SALAM_LOCALE", setting)
        lang := i18n.DetectLocale()
        println setting, "->", lang, "->", pick_language(lang, supported, "en")
    end
end
Outputfa_IR.UTF-8 -> fa -> fa EN-us -> en -> en de_DE.UTF-8 -> de -> en

Find missing translations

T never fails, which is good for users and bad for spotting gaps. Has checks one language only and ignores the fallback, so it can tell you which keys a translator still has to do. The catalog's keys field lists every entry as language:key.

i18n-guide-audit.salam
import i18n

func main:
    mut c := i18n.New("en")
    defer i18n.Free(c)
    i18n.Set(c, "en", "title", "Settings")
    i18n.Set(c, "en", "save", "Save changes")
    i18n.Set(c, "en", "reset", "Reset to defaults")
    i18n.Set(c, "en", "help", "Help")
    i18n.Set(c, "fa", "title", "تنظیمات")
    i18n.Set(c, "fa", "save", "ذخیره‌ی تغییرات")
    mut total := 0
    mut missing := 0
    each k in c.keys:
        if k.Substr(0, 3) == "en:":
            key := k.Substr(3, k.Len() - 3)
            total++
            if i18n.Has(c, "fa", key) == false:
                missing++
                println "fa is missing", key, "and shows:", i18n.T(c, "fa", key)
            end
        end
    end
    println "fa:", total - missing, "of", total, "translated"
end
Outputfa is missing reset and shows: Reset to defaults fa is missing help and shows: Help fa: 2 of 4 translated
JobUse
Translate a fixed messageT
Translate and fill in valuesTf
One or manyPlural, then Interpolate
Load a language from a fileLoadLocale
Check that a translation existsHas
The text exactly as storedRawGet

Types

Catalog

struct Catalog
A catalog of translations. Build one with New and release it with Free.
NameTypeDescription
keysVectorThe stored keys, in the form "language:key".
valsVectorThe translations, in the same order as the keys.
fallbackstr = "en"The fallback language.
i18n-Catalog.salam
import i18n

func main:
    mut c := i18n.New("en")
    defer i18n.Free(c)
    i18n.Set(c, "en", "hello", "Hello")
    i18n.Set(c, "fa", "hello", "سلام")
    i18n.Set(c, "en", "bye", "Goodbye")
    println i18n.T(c, "fa", "hello"), i18n.T(c, "fa", "bye"), i18n.T(c, "fa", "missing")
    println i18n.Has(c, "fa", "bye"), i18n.RawGet(c, "fa", "bye") == ""
    println c.fallback
end
Outputسلام Goodbye missing false true en

Functions

New

func New(default_locale: str): Catalog
Creates an empty catalog with the given fallback language.

The example for this item is shown with the ones above: i18n-Catalog.salam

Set

func Set(c &: Catalog, locale: str, key: str, val: str)
Records the translation of a key for a language, replacing any earlier one.

The example for this item is shown with the ones above: i18n-Catalog.salam

Has

func Has(c &: Catalog, locale: str, key: str): bool
True when a translation is recorded for this language and key. It does not look at the fallback language.

The example for this item is shown with the ones above: i18n-Catalog.salam

RawGet

func RawGet(c &: Catalog, locale: str, key: str): str
Returns the recorded translation with no substitution at all, or an empty string when there is none.

The example for this item is shown with the ones above: i18n-Catalog.salam

T

func T(c &: Catalog, locale: str, key: str): str
Returns the translation of the key, or the fallback language's translation, or, failing that, the key itself.

The example for this item is shown with the ones above: i18n-Catalog.salam

Interpolate

func Interpolate(msg: str, param_names: Vector<str>, param_vals: Vector<str>): str
Replaces every {name} in the message with the value of that name. The names and the values are given in two vectors in the same order.
i18n-Tf.salam
import i18n

func main:
    mut c := i18n.New("en")
    defer i18n.Free(c)
    i18n.Set(c, "en", "greet", "Hello {name}, you have {n} new messages")
    mut names := Vector {} as Vector<str>
    mut values := Vector {} as Vector<str>
    defer names.Free()
    defer values.Free()
    names.Push("name")
    names.Push("n")
    values.Push("Maryam")
    values.Push("3")
    println i18n.Tf(c, "en", "greet", names, values)
    println i18n.Interpolate("{name} and {name} again", names, values)
end
OutputHello Maryam, you have 3 new messages Maryam and Maryam again

Tf

func Tf(c &: Catalog, locale: str, key: str, param_names: Vector<str>, param_vals: Vector<str>): str
Translation and interpolation in one step.

The example for this item is shown with the ones above: i18n-Tf.salam

Plural

func Plural(c &: Catalog, locale: str, key: str, n: i64): str
Chooses the right form of a message for the number n: the key .one for one and .other for the rest. It does not place the number in the message itself; use Interpolate for that. A language that needs only one form can define .other alone, but only when the fallback language has no .one either; otherwise the fallback's .one is shown for n = 1, so define .one as well.
i18n-Plural.salam
import i18n
import io

func main:
    mut c := i18n.New("en")
    defer i18n.Free(c)
    io.WriteFile("en.txt", "apple.one = one apple\napple.other = {n} apples\n")
    println i18n.LoadLocale(c, "en", "en.txt")
    mut names := Vector {} as Vector<str>
    defer names.Free()
    names.Push("n")
    each n in [1, 5]:
        mut values := Vector {} as Vector<str>
        values.Push("" + n)
        println i18n.Interpolate(i18n.Plural(c, "en", "apple", n), names, values)
        values.Free()
    end
    println i18n.DetectLocale().Len() > 0
end
Output2 one apple 5 apples true

LoadLocale

func LoadLocale(c &: Catalog, locale: str, path: str): int
Loads the translations of one language from a file of key = value lines and returns how many keys were read.

The example for this item is shown with the ones above: i18n-Plural.salam

DetectLocale

func DetectLocale(): str
Guesses the user's language from the environment: SALAM_LOCALE first, then LANG and LC_ALL. When none is set it returns en.

The example for this item is shown with the ones above: i18n-Plural.salam

Free

func Free(c &: Catalog)
Releases the catalog's memory.

The example for this item is shown with the ones above: i18n-Catalog.salam