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

▶ Watch this deck — 7 scenes, ~4 min

01 What this topic covers

ABOUT THIS TOPIC Translations errors, help, guides and logs, translated through one catalog 1 The same guide in Polish 2 Errors that read the same in tests 3 Guides keep prose apart from commands 4 Log lines translated as they are written 5 Keeping the catalog in step
About this topic, Translations: the guide in Polish, errors, guides, logs, the catalog

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

THE SAME GUIDE IN POLISH English $ pkgproxyctl setup apt To cache apt packages with pkgproxy, add this to /etc/apt/apt.conf.d/99pkgproxy on each client: Acquire::http::Proxy "http://…:3142"; This makes apt download plain HTTP sources through pkgproxy, … a Polish locale $ pkgproxyctl setup apt Aby zapisywać pakiety apt w pamięci podręcznej pkgproxy, dodaj poniższe do /etc/apt/apt.conf.d/99pkgproxy na każdym kliencie: Acquire::http::Proxy "http://…:3142"; Dzięki temu apt pobiera źródła udostępniane przez zwykłe HTTP … the configuration line is identical: commands and paths are never in a message pkgproxyctl: błąd: nie można użyć -addr "nonsense": musi mieć postać host:port … the setup page follows the visitor's browser instead: Accept-Language
pkgproxyctl setup apt in English and in a Polish locale side by side: the prose is translated, the Acquire::http::Proxy line is identical; below, an error 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

ERRORS return l10n.D.Errorf("cannot use %s %q: the port must be a number from 0 to 65535", option, addr) var errTooManyRedirects = l10n.D.Errorf("cannot fetch a file: too many redirects") Error(): English cannot use -addr ":99999": the port must be a number … logs and tests stay the same on the terminal: translated pkgproxyctl: błąd: nie można użyć -addr ":99999": port … go-cmdr's error printer HTTP error bodies: English cannot fetch from upstream HTTP clients carry no locale cannot open … never: failed to open … could not open … opening X: %w
An error built with l10n.D.Errorf goes three ways: its Error() text stays English for logs and tests, go-cmdr prints it translated on the terminal, and HTTP error bodies stay English; below, the cannot wording rule

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

GUIDES: PROSE APART FROM COMMANDS g := &guide{} g.para(fmt.Sprintf(l10n.D.Tr(ctx, "To cache apt packages with pkgproxy, add this to %s on each client:"), aptConfPath)) g.code(aptProxyConf(base)) pl.po: prose only, %s for the path msgid "To cache apt packages with pkgproxy, add this to %s on each client:" msgstr "Aby zapisywać pakiety apt w pamięci podręcznej pkgproxy, dodaj poniższe do %s na każdym kliencie:" the guide: prose wrapped at 74 columns, code as is Aby zapisywać pakiety apt w pamięci podręcznej pkgproxy, dodaj poniższe do /etc/apt/apt.conf.d/99pkgproxy … Acquire::http::Proxy "http://…:3142"; piped scripts stay untranslated, except the messages they print, which are translated and shell-quoted
Code building a guide with g.para for translated prose and g.code for a verbatim line; the catalog entry has only prose with a %s placeholder; the rendered guide wraps the prose and keeps the code line as is

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

LOG MESSAGES logger.Error(i18n.MarkForTranslation("cannot open cache directory"), "dir", dir, "error", err) l10n.NewLogHandler translates msg and error values locale: the record's context, else the daemon's in the C locale level=ERROR msg="cannot open cache directory" dir=/var/cache/pkgproxy error="empty cache key" in a Polish locale: the same keys and values level=ERROR msg="nie można otworzyć katalogu pamięci podręcznej" dir=/var/cache/pkgproxy error="pusty klucz pamięci podręcznej" the snap's daemon runs under systemd, normally in the C locale: an English log
A logger call marks its message with i18n.MarkForTranslation; the log handler translates the message and the error attribute; the same record comes out in English in the C locale and in Polish in a Polish one, with the same keys

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

THE CATALOG the source Tr Errorf MarkFor… $ go tool i18n scan -C internal/l10n pkgproxy.pot follows constants · keeps TRANSLATORS: comments $ go tool i18n merge -C … -no-obsolete pl.po translate the new and fuzzy entries $ go tool i18n check -C … -auto -S //go:embed po the catalogs ship inside the binary · English is the source language
The catalog workflow: go tool i18n scan writes pkgproxy.pot from the source, merge updates pl.po, the new and fuzzy entries are translated, check confirms; the po directory is embedded in the binary

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

WHERE NEXT prose goes through one catalog; commands, paths and the error text in logs and tests stay as written you are here Translations How it is tested translated output pinned in tests The setup page the page in the browser's language The source tree the other conventions of a change
Where next from Translations: How it is tested, The setup page, The source tree

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 to Tr, TrN and Errorf.
  • 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

TextCallLanguage
An error, sentinels includedl10n.D.Errorf("cannot …", …), never fmt.Errorf or errors.NewError() English; go-cmdr's printer shows LocalizedError in the process's locale, wrapped causes included
Help, command output, page textl10n.D.Tr(ctx, …), l10n.D.TrN(ctx, …, n) for pluralsThe locale on ctx
A log messagelogger.Info(i18n.MarkForTranslation("…"), …)Translated by l10n.NewLogHandler as it is written
Setup guidanceg.para(l10n.D.Tr(ctx, …)) for prose, g.code(…) for commands, paths and configurationProse translated and wrapped to 74 columns (guideWidth); code verbatim, indented four spaces
A message a piped script printsshellFail(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

TranslatedNot translated
pkgproxyctl and pkgproxy help, through go-cmdr's own catalog tooError() of every error: logs and tests read the same in every locale
Errors as pkgproxyctl and pkgproxy print themHTTP 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 bannerScripts piped to sh, apart from what shellFail prints
The setup page and the cache page, in the visitor's Accept-LanguageCommands, paths, configuration and YAML: never part of a msgid
Daemon log messages, and error-valued log attributesLog attribute keys and other values
pkgproxyctl stats, offline, version and the other commands' outputA 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

WhereLocale
maini18n.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 scriptsl10n.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

FileWhat it is
internal/l10n/po/pkgproxy.potThe template scan writes: every msgid, with its source locations
internal/l10n/po/pl.poPolish, 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.goNewLogHandler: 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

TestWhat it checks
cmd/pkgproxy TestCtlSetupApt_GuidePolishsetup apt in Polish: prose translated and rewrapped, configuration identical to English
TestCtl_HelpPolish, TestCtlVersion_Polish, TestSetupPage_PolishHelp, version and the setup page in Polish
internal/l10n TestAcceptLanguageHeader to locale
internal/l10n TestLogHandler_*Messages and error attributes translated, groups, the record's locale winning, unknown messages passing through
internal/registryproxy TestErrors_LocalizeThe 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

INSIDE PKGPROXY · for contributors