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
Tfalls back past it. Pluralknows two forms:.onefor exactly 1 and.otherfor everything else, 0 included. Languages with more forms, such as Arabic or Russian, need their own logic around it.DetectLocalechecksSALAM_LOCALE, thenLANG, thenLC_ALL, soLANGwins overLC_ALL, the reverse of the POSIX rule. With none of them set it returnsen; withLANG=Cit returnsc.- Lookups walk the whole catalog, which is fine for a few hundred messages per language. For thousands, keep your own
HashMapof 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.
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
endKeep 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.
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
endThe 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.
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)
endChoose 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.
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
endFind 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.
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| Job | Use |
|---|---|
| Translate a fixed message | T |
| Translate and fill in values | Tf |
| One or many | Plural, then Interpolate |
| Load a language from a file | LoadLocale |
| Check that a translation exists | Has |
| The text exactly as stored | RawGet |
Types
Catalog
struct CatalogNew and release it with Free.| Name | Type | Description |
|---|---|---|
keys | Vector | The stored keys, in the form "language:key". |
vals | Vector | The translations, in the same order as the keys. |
fallback | str = "en" | The fallback language. |
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
endFunctions
New
func New(default_locale: str): CatalogThe example for this item is shown with the ones above: i18n-Catalog.salam
Set
func Set(c &: Catalog, locale: str, key: str, val: str)The example for this item is shown with the ones above: i18n-Catalog.salam
Has
func Has(c &: Catalog, locale: str, key: str): boolThe example for this item is shown with the ones above: i18n-Catalog.salam
RawGet
func RawGet(c &: Catalog, locale: str, key: str): strThe example for this item is shown with the ones above: i18n-Catalog.salam
T
func T(c &: Catalog, locale: str, key: str): strThe 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{name} in the message with the value of that name. The names and the values are given in two vectors in the same order.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)
endTf
func Tf(c &: Catalog, locale: str, key: str, param_names: Vector<str>, param_vals: Vector<str>): strThe example for this item is shown with the ones above: i18n-Tf.salam
Plural
func Plural(c &: Catalog, locale: str, key: str, n: i64): strn: 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.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
endLoadLocale
func LoadLocale(c &: Catalog, locale: str, path: str): intkey = 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(): strSALAM_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)The example for this item is shown with the ones above: i18n-Catalog.salam