Translations

Defining Translations

Translations live in a version-controlled translations.yaml file at the project root, alongside evidence.config.yaml and theme.yaml. They apply to every page in the project — there is no per-page translations file. Translations are defined in YAML format with 2-digit language codes (e.g., en, fr, es, de) as top-level keys. (Language Codes)

en:
  revenue: 'Revenue'
  top_products: 'Top Products'
  langcode: 'en'
fr:
  revenue: "Chiffre d'affaires"
  top_products: 'Meilleurs produits'
  langcode: 'fr'

The yaml structure follows i18next conventions for each language.

Nested Translations

You can organize translations into groups:

en:
  metrics:
    revenue: 'Revenue'
    customers: 'Customers'
  categories:
    electronics: 'Electronics'
    clothing: 'Clothing'
fr:
  metrics:
    revenue: "Chiffre d'affaires"
    customers: 'Clients'
  categories:
    electronics: 'Électronique'
    clothing: 'Vêtements'

Reusing Translations

Translations support i18next nesting syntax for reusing translations within other translations:

en:
  revenue: 'Revenue'
  report_title: 'Q4 $t(revenue) Report'
fr:
  revenue: "Chiffre d'affaires"
  report_title: 'Rapport $t(revenue) T4'

When rendered, $translations.report_title becomes “Q4 Revenue Report” in English or “Rapport Chiffre d’affaires T4” in French.

Using Translations in Pages

Translations are accessible via the special $translations variable.

{% $translations.revenue %}

Inline in Text

# {% $translations.revenue %} Dashboard

In Component Attributes

{% big_value
  data="daily_orders"
  title=$translations.revenue
  value="sum(total_sales)"
  fmt="usd"
/%}

Templated in Strings

{% line_chart
  data="daily_orders"
  title="{{ $translations.revenue }} from {{ $translations.top_products }}"
  x="order_date"
  y="sum(total_sales)"
/%}

In SQL

```sql home_sales
select
    label_{{ $translations.langcode }} as local_label
from description
```

Using Translations Inside SQL String Literals

Translation values often contain apostrophes (d'affaires, l'offre, chiffre d'affaires). Interpolating them raw into a '…' SQL string literal closes the literal early and the warehouse rejects the query. Use the .sql accessor in that position — Evidence escapes the value using the target warehouse’s own string-literal rules (doubled quote '' on Postgres, DuckDB, ClickHouse, Snowflake; backslash-escaped \' on BigQuery, Databricks):

```sql member_paid_offerings
select count(*) from t
where section = '{{ $translations.section_name.sql }}'
```

Given a French value Offre d'adhérents:

On Postgres / DuckDB / ClickHouse / Snowflake: where section = 'Offre d''adhérents'
On BigQuery / Databricks: where section = 'Offre d\'adhérents'

Both parse back to the same string (Offre d'adhérents) — the escape is SQL syntax only, never text the reader sees. Use .sql only inside a single-quoted SQL string literal. Elsewhere — plain text, headings, identifier concatenation like label_{{ $translations.langcode }} — the bare form is correct and .sql would incorrectly rewrite apostrophes that were never inside a SQL literal.

Built-in Report Text

translations.yaml covers your content. Everything Evidence itself draws inside a report follows the selected language automatically, with no translation keys required:

Chart date axes and tooltips — both the words (month abbreviations, quarter labels) and the conventions (day-month order, punctuation, 12/24-hour clock) switch.
Component text — table pagination and search, filter chips and operators, dropdown and date range picker labels and presets, legend “show more”, the “Download” button, sampling notices, computed “Total” labels, and similar.

Language	Axis labels	Tooltip	Component text
`en`	`Jun 5` · `Jul` · `Q3` · `4 pm`	`Jun 15–21, 2025`	`1 - 10 of 250 rows` · `Today`
`fr`	`5 juin` · `juil.` · `T3` · `16 h`	`15–21 juin 2025`	`1 à 10 sur 250 lignes` · `Aujourd'hui`

Currently supported: English (en) and French (fr). Regional variants such as fr-CA use the base language; any other language renders English built-in text (your translations.yaml content is unaffected). Component attributes you set explicitly always win over the built-in text — total_label="Net" on a waterfall chart stays Net in every language. Leave the attribute out to get the translated default, or pass total_label=$translations.net to translate it yourself.

Custom date formats

Explicit date formats keep working and translate their month and weekday names, wherever fmt is used — chart axes, tooltips, tables, big values. Numeric tokens, separators and quoted literals are left exactly as written:

`fmt`	`en`	`fr`
`mmm yyyy`	`Jan 2025`	`janv. 2025`
`dddd d mmmm yyyy`	`Wednesday 15 January 2025`	`mercredi 15 janvier 2025`
`dd/mm/yyyy`	`15/01/2025`	`15/01/2025`

Named presets whose English definition carries English word order or a 12-hour clock are redefined per language: in French longdate is 15 janvier 2025, fulldate is mercredi 15 janvier 2025 and hms is 16:05:09. AM/PM has no French form and stays as written.

Contributing a Language

Built-in text lives in the open-source Evidence repository. UI strings are standard i18next JSON resources (the same library that resolves translations.yaml) and date formats are date-fns locale configurations, so a new language is a small, self-contained pull request: one JSON file, one date config, and a one-line registration. The test suite verifies the files are complete. See core/src/locale/README.md for the step-by-step guide.

Fallback Behavior

If a translation key is missing for the selected language, it will fall back to English (en) if available.

Get Started

Core Concepts

Features

MCP

CLI

Self Host

Direct Connectors

Evidence Warehouse

Components

Guides