Translations
contributors for contributors
Errors, help, setup guides, the setup page and daemon logs are translated through one catalog in internal/l10n, with Polish shipped; commands and paths are never part of a message.
On the map: inside pkgproxy
01 What this topic covers
How errors, help, guides, pages and logs are translated through one catalog, with commands and paths kept out of it.
pkgproxy translates what people read, its errors, help, setup guides and log messages, through one catalog. If you have not seen The source tree yet, start there. First you see a setup guide in Polish. Then you see why error text stays the same in tests, how guides keep prose apart from commands, and how log lines are translated as they are written. Last, you see how to keep the catalog in step with the code.
02 The same guide in Polish
Prose is translated and reflowed; commands, paths and configuration stay
verbatim. TestCtlSetupApt_GuidePolish pins this output; the
setup page picks its language from Accept-Language.
pkgproxy speaks the language of the machine it runs on, and ships Polish. Run setup apt in a Polish locale and the explanation is in Polish, wrapped to the same width, while the configuration line is exactly the same as in English, because commands and paths are kept out of what translators see. Help screens and errors follow the locale too. The setup page follows the visitor's browser instead, through its Accept-Language header.
03 Errors that read the same in tests
l10n.D.Errorf keeps errors.Is identity for
sentinels. Error() is English; go-cmdr prints the
translation. Write "cannot …", not "failed to …" or "could not …".
Every error is built with l10n.D.Errorf, never with fmt.Errorf or errors.New, sentinels included, and a failed action is worded cannot, then a verb. The error's own text stays English, so logs and tests read the same in every locale. The command line's error printer recognises a localized error and shows the translation, wrapped causes included. HTTP error bodies stay English too: an HTTP client carries no locale, and people and tests match on those sentences.
04 Guides keep prose apart from commands
g.para(…) takes prose from l10n.D.Tr;
g.code(…) takes lines that are never translated or reflowed.
The msgid has %s where the path goes.
Setup guidance is assembled with the guide builder: para adds a paragraph of translated prose, and code adds verbatim lines computed from the real addresses and paths. A message is one unwrapped paragraph with placeholders for paths and names, so translators never see shell, and changing a command never invalidates a translation. The guide wraps each paragraph to 74 columns, in whatever language it is in. Piped scripts stay untranslated, except the messages they print, which are translated and shell quoted.
05 Log lines translated as they are written
l10n.NewLogHandler wraps the daemon's slog text
handler. A message from a library at run time passes through untranslated.
Log messages are not translated where they are written. Each call site wraps its message in i18n.MarkForTranslation, which only marks it for the scanner, and the daemon's log handler translates it as the line is written, in the daemon's locale or one its context carries. Error attributes are rendered in that language too, while attribute keys and other values stay as they are, so a log line keeps its machine readable shape. The snap's daemon runs under systemd, normally in the C locale, so its log is in English.
06 Keeping the catalog in step
go tool i18n scan, merge -no-obsolete, translate
pl.po, then check -auto -S, all with -C
internal/l10n.
After changing a user visible string, three commands keep the catalog in step. Scan reads the source for every string passed to a translation call or marked for translation, following constants, and keeps comments that start with TRANSLATORS for the translator. Merge brings the Polish catalog up to date and drops obsolete entries. The new or fuzzy entries are then translated, and check confirms the result. The catalogs are embedded in the binary, with English as the source language.
07 Where to go next general version
Next: How it is tested, for translated output in tests; The setup page, for the browser's language; The source tree, for the other conventions.
You now know which text goes through the catalog, and which stays as written: commands, paths, and the error text in logs and tests. To see how translated output is pinned in tests, watch How it is tested. To see the setup page follow the visitor's browser language, watch The setup page. For the other conventions a change follows, watch The source tree.
Read more
Adding or changing a message
- Write the English text in the code, through the call that fits it (below). A message shared by several call sites can live in a
const: the scanner follows constants passed toTr,TrNandErrorf. - If the translator needs context, put a comment starting with
TRANSLATORS:right above the call; other comments stay out of the catalog. - Update the catalog and translate:
go tool i18n scan -C internal/l10n go tool i18n merge -C internal/l10n -no-obsolete # translate the new and fuzzy entries in internal/l10n/po/pl.po go tool i18n check -C internal/l10n -auto -S
go tool i18n is gitlab.com/zygoon/go-i18n/cmd/i18n, a tool dependency in go.mod. Scan and merge run at development time only; the binary embeds the result.
Which call for which text
| Text | Call | Language |
|---|---|---|
| An error, sentinels included | l10n.D.Errorf("cannot …", …), never fmt.Errorf or errors.New | Error() English; go-cmdr's printer shows LocalizedError in the process's locale, wrapped causes included |
| Help, command output, page text | l10n.D.Tr(ctx, …), l10n.D.TrN(ctx, …, n) for plurals | The locale on ctx |
| A log message | logger.Info(i18n.MarkForTranslation("…"), …) | Translated by l10n.NewLogHandler as it is written |
| Setup guidance | g.para(l10n.D.Tr(ctx, …)) for prose, g.code(…) for commands, paths and configuration | Prose translated and wrapped to 74 columns (guideWidth); code verbatim, indented four spaces |
| A message a piped script prints | shellFail(l10n.D.Tr(ctx, …)) | Translated and shell-quoted; the rest of the script is not translated |
Wording: a failed action reads cannot <verb> …, not "failed to …", "could not …" or a gerund wrapper such as "creating X: %w". An error that describes a state ("malformed field line") stays as it is, and a package prefix such as apt: is kept. Daemon log messages and HTTP error bodies use the same wording. A msgid is one unwrapped paragraph with %s or %q where a path or name goes.
What is and is not translated
| Translated | Not translated |
|---|---|
pkgproxyctl and pkgproxy help, through go-cmdr's own catalog too | Error() of every error: logs and tests read the same in every locale |
Errors as pkgproxyctl and pkgproxy print them | HTTP error bodies, including snapd error results, the store-style error list of a refused snapd request, and offline.PlainAnswer's body |
| Setup guides on a terminal, and the daemon's startup banner | Scripts piped to sh, apart from what shellFail prints |
The setup page and the cache page, in the visitor's Accept-Language | Commands, paths, configuration and YAML: never part of a msgid |
| Daemon log messages, and error-valued log attributes | Log attribute keys and other values |
pkgproxyctl stats, offline, version and the other commands' output | A log message that comes from a library at run time, such as the checksum database client's |
The snap's daemon runs under systemd, normally in the C locale, so its log is in English unless the service is given a locale.
Where the locale comes from
| Where | Locale |
|---|---|
main | i18n.DetectLocale(), the process's locale, on the base context; i18n.BindAll(ctx, l10n.D, cmdrl10n.Domain) binds pkgproxy's and go-cmdr's catalogs |
| Setup page, cache page, setup scripts | l10n.AcceptLanguage(r.Header.Get("Accept-Language")): the best match among English and the catalogs, English for none or a malformed header; set on a context used only to render, never to log |
l10n.NewLogHandler(ctx, next) | The record's context when it carries a locale, otherwise the daemon's |
Catalog files
| File | What it is |
|---|---|
internal/l10n/po/pkgproxy.pot | The template scan writes: every msgid, with its source locations |
internal/l10n/po/pl.po | Polish, with three plural forms |
internal/l10n/l10n.go | //go:embed po; registers domain D = gitlab.com/zygoon/pkgproxy; English is the source language; every <lang>.po in po is a language |
internal/l10n/log.go | NewLogHandler: translates each record's message and renders error attributes through D.LocalizedError, groups included |
A new language is a new po/<tag>.po: AcceptLanguage and the language list pick it up from the embedded directory.
Tests that pin translated output
| Test | What it checks |
|---|---|
cmd/pkgproxy TestCtlSetupApt_GuidePolish | setup apt in Polish: prose translated and rewrapped, configuration identical to English |
TestCtl_HelpPolish, TestCtlVersion_Polish, TestSetupPage_Polish | Help, version and the setup page in Polish |
internal/l10n TestAcceptLanguage | Header to locale |
internal/l10n TestLogHandler_* | Messages and error attributes translated, groups, the record's locale winning, unknown messages passing through |
internal/registryproxy TestErrors_Localize | The side's errors localize |
Command tests run in English through invoke; invokeIn(t, locale, argv...) runs them in another locale.
In the documentation
Roads from here
SETUP AND THE COMMAND LINE
- Setting up clients — the guides being translated
- The setup page — the page that follows the browser's language
INSIDE PKGPROXY · for contributors
- The source tree — the error convention among the others
- How pkgproxy is tested — how translated output is tested
- A request in code — the request log the handler translates