i18n

kanna-i18n compiles a directory of locale files into Go: a typed constructor for every message, and the translations
themselves, so nothing is parsed or read at run time.
Part of the kanna family of code generators. Requires Go 1.26.
Install
go get -tool github.com/go-kanna/i18n/cmd/kanna-i18n
The generated code calls the runtime at the root of this module, github.com/go-kanna/i18n, which the line above
already requires. The runtime does what depends on run-time values: choosing the language, picking the CLDR plural
form, and formatting numbers for the locale.
Use
One YAML file per language, named by its language tag:
# locales/en.yaml
greeting: "Hello!"
hello: "Hello, {name}!"
items_count:
plural:
one: "You have {count} item."
other: "You have {count} items."
total_price: "Total: {price:number}"
user:
not_found: "User not found."
# locales/ja.yaml
greeting: "こんにちは!"
hello: "こんにちは、{name}さん!"
items_count:
plural:
other: "アイテムが{count}個あります。"
total_price: "合計: {price}"
user:
not_found: "ユーザーが見つかりません。"
//go:generate go tool kanna-i18n
With the defaults, that line reads locales/ and writes messages/i18n_gen.go: a constructor per message, a
Localizer function, and the translations of every language. Write it in a Go file of the package whose directory holds
locales/, such as main.go at the root of the module, since the paths are relative to the directory of the line.
With two or more kanna generators, run them with go tool kanna gen, which runs
them in the order they need.
// Code generated by kanna-i18n. DO NOT EDIT.
package messages
import (
"github.com/go-kanna/i18n"
)
// Hello returns the message "hello":
//
// Hello, {name}!
func Hello(name string) i18n.Message {
return i18n.Message{Key: "hello", Args: []i18n.Arg{
{Name: "name", Value: name},
}}
}
// ItemsCount returns the message "items_count", in the form count selects:
//
// one: You have {count} item.
// other: You have {count} items.
func ItemsCount(count int) i18n.Message {
return i18n.Message{Key: "items_count", Args: []i18n.Arg{
{Name: "count", Value: count},
}}
}
// ...
// Localizer renders this package's messages in the language that best matches
// langs, each a language tag or an Accept-Language value, tried in order.
// A message missing from that language falls back to its parent languages and
// then to en.
func Localizer(langs ...string) i18n.Localizer {
return bundle.Localizer(langs...)
}
// bundle holds every language this package was generated from, en, the
// default, first.
var bundle = i18n.NewBundle(
i18n.Catalog{Lang: "en", Entries: map[string]i18n.Entry{
"hello": {Single: i18n.Template{{Text: "Hello, "}, {Param: "name"}, {Text: "!"}}},
"items_count": {Plural: &i18n.Plural{
One: i18n.Template{{Text: "You have "}, {Param: "count"}, {Text: " item."}},
Other: i18n.Template{{Text: "You have "}, {Param: "count"}, {Text: " items."}},
}},
// ...
}},
i18n.Catalog{Lang: "ja", Entries: map[string]i18n.Entry{
// ...
}},
)
Each constructor's documentation carries what the default language says, so an editor shows the text of a message
where it is called.
A constructor returns an i18n.Message, not a string: code that does not know the reader's language can hand one back
(inside an error, say), and the code that does know renders it:
loc := messages.Localizer(r.Header.Get("Accept-Language"))
fmt.Fprintln(w, loc.Localize(messages.Hello("Alice"))) // Hello, Alice! or こんにちは、Aliceさん!
fmt.Fprintln(w, loc.Localize(messages.ItemsCount(1))) // You have 1 item. or アイテムが1個あります。
fmt.Fprintln(w, loc.Localize(messages.TotalPrice(1234.56))) // Total: 1,234.56 or 合計: 1,234.56
A translation that does not fit the default language stops generation, rather than the first request that meets it.
Had ja.yaml above misspelled a placeholder and a key, and given the price a kind of its own:
$ go generate ./...
locales/ja.yaml:2:8: error: parameter "namae" of key "hello" is not in en
did you mean "name"?
locales/ja.yaml:6:14: error: parameter "price" of key "total_price" is int, but number in en
locales/ja.yaml:8:3: error: key "user.not_fund" is not in en
did you mean "user.not_found"?
locales/ja.yaml: warning: missing keys: user.not_found
Locale files
The locale directory is flat (one file per language, no recursion), and the file name without its extension is the
language: en.yaml, pt-BR.yaml, ja.yml. Nothing named like a language is skipped in silence: a subdirectory such as
locales/en/ or locales/en.yaml/, or a file in another format such as en.json or en.toml, stops generation. Other
files are skipped with a warning, so a stray config.yaml does not fail the run, and names starting with a dot are
skipped without one. Three letters name a language under ISO 639-3, so a stray app.yaml or dev.yaml is read as one;
a language that x/text holds no CLDR data for, with no plural rules or number format of its own, gets a warning.
Nested mappings become dot-joined keys, and keys become constructor names: user.not_found generates UserNotFound().
Each part of a key matches [a-z][a-z0-9_]*. Two keys that generate one name, or a key that generates a name the
destination package already declares, stop generation; so do the key localizer, whose name the generated file takes
for itself, and a Localizer the destination package declares by hand.
Every value is a string or a mapping. Quote a value that YAML would read as something else, such as "true" or
"123". A message cannot hold a control character other than a line break or a tab, nor a byte order mark.
A message declares its plural forms under an explicit plural mapping, keyed by CLDR category (zero, one, two,
few, many, other) and always defining other. Keys that merely happen to be named one or other are ordinary
nesting: the only name a locale file cannot use freely is plural, which holds the forms of the message above it and
nothing else, takes no other keys beside it, and is no message of its own. A Japanese message written as
plural: "{count}個" stops generation, since its one form goes under other.
The constructor takes count int first, and the count picks the form under the plural rules of the language rendering
it: 1 is one in English, while Japanese has no one and uses other for every count. A plural message that lacks a
form its language uses gets a warning, because those counts would render with other: Russian with only other lacks
one, few, and many, while Japanese with only other lacks nothing. So does a form its language never takes, such
as one in Japanese, which no count renders with.
A count of 0 renders with zero whenever the message has it, as in Rails, so zero: "You have no items." in en.yaml
works although English has no zero category. In a language whose rules do have one, such as Latvian, zero takes the
other counts of that category too: 10 through 20, for one.
A count passed some other way, such as a param of a rule or one of i18n.Coded, picks the form by its value whatever
its integer type is: an int64, a uint8, and a type Count int all do. A float count renders with other, 1.0
included.
Placeholders
| Form |
Parameter |
Rendered |
{name} |
string |
as it is |
{name:int} |
int |
in the language's digits, without grouping: counts, IDs |
{name:number} |
float64 |
in the language's format, three decimals at most: 1,234.56 in en, 1.234,56 in de |
{{, }} |
|
literal braces |
{name} writes no kind, and is a string where nothing else gives it one; {name:string} says it is one, which
another form or the default language giving it another kind contradicts. count in a plural message is always an int.
An int is written in the digits of the language and without grouping, so that an ID reads as one: 1234 renders as
1234 in en and ١٢٣٤ in ar. A number is written as CLDR's default pattern for the language has it, which keeps
three fraction digits at most: 1234.5678 renders as 1,234.568. Within a message, a placeholder written without a kind
takes the one written for it elsewhere (in another plural form, say), and two different kinds are an error. The default
language decides each parameter's type: a translation may leave the kind off, as ja.yaml above does for the price, and
one that writes a different kind stops generation.
Parameters come in the order of the names of their placeholders, a plural message's count first, so that rewording a
text cannot swap two arguments of one type: "{last}, {first}" makes FullName(first string, last string), as
"{first} {last}" does. They are named in camelCase: {user_name} becomes userName. A name Go reserves or
predeclares gets Arg appended: {type} becomes typeArg, and {error} becomes errorArg.
Languages
The default language (-default, en unless said otherwise) defines the constructors: their names, parameters, and
types come from its file, and every other file is checked against it. It is served by its own file alone:
-default en takes en.yaml, and -default en-US takes en-US.yaml. Another file of the language does not stand in
for it, so a locale directory holding en-US.yaml but no en.yaml needs -default en-US.
Localizer takes language tags such as "ja" or "pt-BR", Accept-Language values such as "fr, ja;q=0.8", or both,
and tries them in order, value by value, until one is close to a language the package was generated with, as CLDR
judges closeness: a request for en-US is served by en, and one for nb by da when the package has Danish but no
Norwegian. So messages.Localizer(cookie.Value, r.Header.Get("Accept-Language")) prefers the language the user picked,
then the ones the browser asks for. An entry that does not parse is skipped, and the rest of its value is still tried;
the weight is read in either case, q=0.5 or Q=0.5. When nothing matches, the default language is used.
A message the chosen language lacks falls back through its parent languages (en-GB to en) and then to the default
language, and is rendered under the plural rules and number format of the language it is found in. Localize never
fails: the zero Localizer renders every message as its key, and a placeholder whose argument is missing renders as
{name}.
Validation errors
kanna-validator and kanna-value report a broken rule as a code with params, such as too_long with count, and leave
its text to the caller, as Rails' errors.details does. i18n.FullMessages renders them as sentences naming their
fields, and i18n.ErrorMessages by field, as Rails' errors.full_messages and errors.messages do:
loc := messages.Localizer(lang)
if errs, ok := errors.AsType[validator.Errors](err); ok {
for _, m := range i18n.FullMessages(loc, errs) {
fmt.Println(m)
}
}
// Title can't be blank
// Tags is too long (maximum is 20 characters)
// Confirm doesn't match Password
//
// タイトルを入力してください
// Tagsは20文字以内で入力してください
// 確認用パスワードとパスワードの入力が一致しません
i18n.ErrorMessages leaves the field's name out, to be shown beside the field. The built-in Japanese texts start with a
particle, を入力してください, so a message shown anywhere else reads better from i18n.FullMessages.
The texts of every code kanna-validator and kanna-value report are built in, in English as Rails writes them and in
Japanese as rails-i18n does. Rails has no texts for the counts of a slice or a map, too_few, too_many, and
wrong_count, so theirs are the texts of the lengths of a string with items for characters:
is too long (maximum is 3 items), は3件以内で入力してください. A locale file names the fields, overrides any built-in
text, and adds the codes of rules of your own, which the default language writes first, as it does every key:
# locales/en.yaml
errors:
messages:
corp_domain: must be a company address
# locales/ja.yaml
errors:
attributes:
title: タイトル
confirm: 確認用パスワード
password: パスワード
address: 住所
address.zip: 郵便番号
messages:
corp_domain: は会社のアドレスにしてください
errors.format puts a field's name and its message together: "{attribute} {message}" in English,
"{attribute}{message}" in Japanese.
- A field is named by
errors.attributes: the fields on its path, address.zip, then the last of them, zip, and
failing both, the last written out: Completed at for completed_at. An index or a map key on the path is no field
and is left out, so tags[1] is named as tags, and notes.first_note, the key first_note of the map notes, as
notes. A camelCase JSON name is not split into words, so completedAt reads CompletedAt until
errors.attributes names it. A confirmation's attribute, the field it is checked against, is named as the field
beside it. The path is one key, so that address and address.zip are named side by side; nested under address,
they could not be, and generation stops.
- A problem with the value as a whole, at
base, reads as its message alone.
- A message is looked up in the reader's language and its parents, the application's text first and then the built-in
one, before the default language: a reader of Japanese gets the built-in Japanese rather than the application's
English.
A translation may override a built-in text that the default language leaves as it is, and name a field that the
default language leaves to be written out: Japanese names
title, while English reads Title anyway. A built-in
text is overridden in the forms of its own language, plural or not, whatever the default language writes, and fills
its own placeholders, such as {count}; the name of a field fills none.
Anything with Path, Code, and Params methods renders: this package imports no validation package. A problem may
also have a FieldNames() []string method, as validator.FieldError does, returning the fields on its path without the
map keys and indexes; the path of one without it, or whose FieldNames returns none, such as a FieldError built by
hand, is taken as the name of one field, so address.zip is named by errors.attributes.address.zip alone, and written
out as Address.zip. For one message without its field, i18n.Coded("errors.messages", code, params) builds it. A
*rule.Error of go-kanna/value, from building or decoding a value type, has Code and Params as well.
errors.format, errors.attributes, and errors.messages are what these functions read, so no constructor is
generated for them. Other keys under errors, such as errors.not_found, are messages like any other.
A code no language has renders as its key, errors.messages.taken, so a rule without a text shows rather than
vanishes.
The params of a code render by their Go type. A kind written in those keys, such as {count:int}, would decide nothing,
and stops generation. What a count's type does decide is the plural form: an integer of any type picks one, and any
other count, a float included, takes other. The lengths of too_short, too_long, wrong_length, too_few,
too_many, and wrong_count are always an int, so they may be written in plural forms. The bound of greater_than and
the other numeric codes has the type of the field it was checked on, such as a float32 or a type Ratio float64, so
keep its message single.
A number renders by its kind, whatever its type is named: an integer as an int does and a float as a number does, so
a float32 bound of 1000.5 reads 1.000,5 in de. A param that is neither a string nor a number, or whose type has a
String or Error method, renders through fmt, as i18n.Arg says: a time.Time a hook passed as count reads
2000-01-01 00:00:00 +0000 UTC, and an enum with a String method reads as its name. To write one otherwise, replace
it in the params before building the message; Params of either package returns a copy.
Checking the codes your code reports
A code gets its text only when it renders, so a code no locale file has, or one misspelled, shows as its key,
errors.messages.too_young_for_admin, and a param the call leaves out shows as its placeholder, {domain}.
kanna-i18n vet finds such calls without running them:
go tool kanna-i18n vet ./...
usecase/user.go:42:37: error: "too_yuong" has no text in any language of internal/messages, so it renders as errors.messages.too_yuong
did you mean "too_young"?
model/email.go:18:9: error: errors.messages.corp_domain renders "{domain}" in every language of internal/messages that has its text: the call gives no domain
It checks the calls of validator.Fail and validator.FailWith of kanna-validator, of rule.Fail and rule.FailWith
of kanna-value, and of i18n.Coded, where the code, and the prefix, are constants. The codes of Fail and FailWith
render as errors.messages.<code>. What it checks is how the error would render if it were rendered with the params the
call gives: whether it is rendered at all, or logged or wrapped instead, it does not follow.
The texts are those of every package of the module holding the i18n_gen.go kanna-i18n generated, in every language,
looked up as the runtime does: in the language, its parents, the built-in texts that reach it, and the default
language. Which language a reader is shown is decided at run time, so vet reports only what breaks in every one of
them:
- a code no language has a text for, which renders as its key in each. The hint suggests the closest code one has,
the built-in texts a language reaches included;
- a placeholder used in every language that has the text, in every form the call may render, and not given by the
params. A plural message may render any of its forms when the params give
count, and other alone when they do
not. The params are known when they are nil or a map literal of constant keys; Fail gives none.
It leaves alone:
- a code or a placeholder missing in some languages only: a translation may leave a placeholder out, and kanna-i18n
warns of the keys a translation lacks;
- a code or a prefix that is not a constant, and params known only at run time, whose code is still checked;
- params the text does not use;
- the codes
validator.TooLong and the other functions of kanna-validator and kanna-value report themselves.
The texts are read from the generated files, as the program is built with them: a locale file changed since the last
run is checked as it was, which -check tells. A module without a messages package stops vet, as does a generated file
it cannot read. Test files are not checked, as a test may report a code without a text on purpose. A package that
passes holds nothing vet found; that is not to say there is nothing.
Validation
Errors stop generation:
- a key a translation has but the default language does not
- a message that is plural in one language and not in the other, but for a built-in text
- a placeholder the default language's message does not have, or one written with a different kind
- a placeholder the built-in text a language overrides does not fill, and any in the name of a field
- two different kinds for one placeholder within a message, and a kind in a key
i18n.FullMessages reads
- a malformed file, key, or placeholder, and names that collide
Warnings do not:
- keys a translation lacks. The runtime falls back, so the generated code never breaks when a translation lags behind;
it renders the fallback until the translation lands. A built-in text the default language overrides is not missing
from a translation into another language that has one: Japanese readers get the built-in Japanese.
- plural forms a language uses that a message does not provide, and forms a message provides that its language never
takes, such as
one in Japanese, which no count renders with
- files skipped in the locale directory, and locale files for a language without CLDR data
A misspelled key, placeholder, plural category, or kind comes with the name it was probably meant to be.
Flags
kanna-i18n [flags]
kanna-i18n vet [flags] [packages]
Generating:
| Flag |
Meaning |
-locales <dir> |
directory holding the locale files (default locales) |
-default <lang> |
language that defines the constructors and is the last fallback (default en) |
-destination <dir> |
directory to write i18n_gen.go into (default messages) |
-tags <list> |
comma-separated build tags |
-check |
verify the output is up to date instead of writing it; KANNA_CHECK=1 does the same |
-v |
list the files written, removed, or left unchanged |
-deps |
print what a run reads and writes as JSON, for the kanna command, and exit |
-version |
print the version |
Vetting:
| Flag |
Meaning |
-tags <list> |
comma-separated build tags |
-version |
print the version |
The packages vet checks default to the one in the current directory.
Paths are relative to the directory go generate runs in, the one holding the //go:generate line. The package of the
generated file is the one the Go files already in the destination declare, and the directory's name when there are none
yet: write a doc.go there, package msgs, for another name. A run that succeeds prints nothing but its warnings,
which Validation lists, such as the keys a translation lacks. A file named i18n_gen.go without the
generated-code header is never touched.
Code calling the messages is checked with what a run is about to write in place: the destination's own, and that of the
packages of its module importing it, tests included, which a run loads through the go command. A key removed or renamed,
or a placeholder changed, stops the run while code still calls the message as it was, and so does a mistake that a call
to a message added hid; nothing is written then. An error that code had before the run does not stop it, but one in the
destination does, the output's own package, as does a destination that does not parse. Code may call a message before
the first run has written it.
Example
example renders the same messages in English and Japanese (plurals, locale-formatted numbers, a fallback
for a missing translation, and a language chosen from an Accept-Language value) with nothing to set up at run time. CI
regenerates it, checks it with kanna-i18n vet, and fails if the output would change or vet reports a code.
Development
make test # unit tests
make lint # golangci-lint
make example # regenerate the example, vet it, and run it
License
MIT