# 📝 Templating and Localization
Templates are parsed **once at startup**. The same template engine is used for all output formats. When a custom
HTML template is set via `--html-template`, the `--template-name` and `--rotation-mode` flags are ignored.
### Go template primer
Error pages uses the standard Go [`text/template`][go-text-template] package (with HTML output treated as text to
preserve full control over markup). If you have never written a Go template before, do not worry - it is genuinely one
of the **simplest** templating languages around. The full mental model fits in a few minutes.
**Key concepts:**
- `{{ }}` - action delimiters; everything outside them is emitted verbatim.
- `{{ .Field }}` - output a field from the data object (`.` is "current value").
- `{{ if .Cond }} ... {{ else }} ... {{ end }}` - conditional.
- `{{ range .Slice }} {{ . }} {{ end }}` - iteration (`.` becomes each element).
- `{{ .Value | funcName }}` - pipeline; passes the value on the left as the last argument to the function on the right.
- `{{ /* comment */ }}` - comment (not emitted).
**Documentation**:
- [`text/template` package - the complete, authoritative reference][go-text-template].
- [Go Templates Guide](https://hackmd.io/@gekart/go-templates?utm_source=chatgpt.com) - syntax explained with
examples (recommended for beginners).
[go-text-template]: https://pkg.go.dev/text/template
> [!WARNING]
> `{{` and `}}` are reserved as Go template delimiters - any literal occurrence causes a parse error. This is
> common in JSDoc type annotations (`/** @param {{ id: number }} ❌ */`), CSS, etc. To work around this, you can simply
> add a single space between the braces: `/** @param { { id: number } } ✅ */`.
### Template data
All templates receive a data object with the following fields:
| Field | Type | Description |
|------------------------------|----------|------------------------------------------------------------------------|
| `.StatusCode` | `uint16` | HTTP status code (e.g. `404`) |
| `.Message` | `string` | Short status text (e.g. `Not Found`) |
| `.Description` | `string` | Longer description (e.g. `The server can not find the requested page`) |
| `.OriginalURI` | `string` | Request URI that caused the error * |
| `.Namespace` | `string` | Kubernetes namespace of the backend service * |
| `.IngressName` | `string` | Name of the Ingress resource * |
| `.ServiceName` | `string` | Name of the backend service * |
| `.ServicePort` | `string` | Port of the backend service * |
| `.RequestID` | `string` | Unique request ID * |
| `.ForwardedFor` | `string` | Original client IP(s) from `X-Forwarded-For` * |
| `.Host` | `string` | Request `Host` header * |
| `.HomepageURL` | `string` | Homepage URL set via `--homepage-url` (empty if not configured) |
| `.Links` | `[]Link` | Extra links set via `--add-link` (empty slice if not configured) |
| `.Config.ShowRequestDetails` | `bool` | Whether `--show-details` is enabled |
| `.Config.L10nDisabled` | `bool` | Whether `--disable-l10n` is set |
> `*` - Requires `--show-details`
Each element of `.Links` has the following sub-fields:
| Sub-field | Type | Description |
|---------------|----------|-----------------------|
| `.Label` | `string` | Link text |
| `.URL` | `string` | Target URL |
Example usage in a custom template:
```html
{{ if .Links }}
{{ end }}
```
In addition to the fields above, templates also have access to a set of built-in functions (see below), which are
pipeline-friendly (needle before haystack): `{{ .Message | default "Unknown" | upper }}`.
| Function | Description | Example |
|------------------------------|--------------------------------------------------|----------------------------------------------------------------|
| `now` | Current time (`time.Time`) | `{{ now.Format "2006-01-02" }}` / `{{ now.Unix }}` |
| `hostname` | Server hostname | `{{ hostname }}` |
| `version` | Application version string | `{{ version }}` |
| `env "KEY"` | Env var value (sensitive keys masked with `***`) | `{{ env "STAGE" }}` |
| `toJson` / `toJSON` | JSON-encode a value | `{{ .Message \| toJson }}` |
| `toInt` / `int` | Convert to integer | `{{ .StatusCode \| int }}` |
| `toString` / `str` | Convert to string | `{{ .StatusCode \| str }}` |
| `escape` | HTML-escape | `{{ .OriginalURI \| escape }}` |
| `urlEncode` | URL-encode | `{{ .OriginalURI \| urlEncode }}` |
| `trim` | Strip leading/trailing whitespace | `{{ .Message \| trim }}` |
| `trimPrefix` | Remove prefix | `{{ .Message \| trimPrefix "Error: " }}` |
| `trimSuffix` / `trimPostfix` | Remove suffix | `{{ .Message \| trimSuffix "!" }}` |
| `trimAll` | Strip specific characters | `{{ ".test." \| trimAll "." }}` |
| `lower` / `upper` | Change case | `{{ .Message \| upper }}` |
| `replace` | Replace all occurrences | `{{ .Message \| replace " " "_" }}` |
| `contains` | Substring check | `{{ .Message \| contains "test" }}...{{ end }}` |
| `hasPrefix` / `hasSuffix` | Prefix/suffix check | `{{ .Message \| hasPrefix "test" }}...{{ end }}` |
| `split` | Split string by separator | `{{ split ";" "a;b;c" }}` |
| `join` | Join slice with separator | `{{ split ";" "a;b;c" \| join ", " }}` |
| `fields` | Split string by whitespace | `{{ fields "foo bar baz" \| join "-" }}` |
| `substr` | Substring by rune index and length | `{{ "Hello, World!" \| substr 7 5 }}` |
| `truncate` | Truncate with `...` appended | `{{ .Description \| truncate 80 }}` |
| `repeat` | Repeat string N times | `{{ "Ha" \| repeat 3 }}` |
| `quote` / `squote` | Wrap in double/single quotes | `{{ .Message \| quote }}` |
| `count` | Count substring occurrences | `{{ "test" \| count "t" }}` |
| `default` | Fallback value for empty input | `{{ .OriginalURI \| default "N/A" }}` |
| `coalesce` | First non-empty value from a list | `{{ coalesce .Message .Description "error" }}` |
| `ternary` | Inline conditional | `{{ .Config.ShowRequestDetails \| ternary "shown" "hidden" }}` |
| `isEmpty` / `isNotEmpty` | Emptiness check | `{{ if isNotEmpty .Description }}...{{ end }}` |
| `l10nScript` | Inline the localization JS script | `` |
> [!NOTE]
> `env` masks values whose key (split by `_`) contains `PASSWORD`, `SECRET`, `KEY`, `TOKEN`, `PASS`, `PWD`,
> or `CRED` (case-insensitive). Those calls return a string of `*` characters instead of the actual value.
### Localization
HTML pages support automatic **client-side localization** in 15+ languages, templates that want l10n must:
1. Add `data-l10n` attributes to elements whose text content should be translated
2. Include `` in the HTML
The browser detects the visitor's preferred language via `navigator.languages` and translates all `[data-l10n]`
elements in-place - no server round-trip required. Localization can be disabled globally with `--disable-l10n`
(or via env `DISABLE_L10N=true`).
You can find more details on handling localization in templates in the [Localization documentation](../l10n/readme.md).