> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evidence.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Translations

> Create multi-language versions of your pages with a version-controlled translations.yaml file at the project root.

## Defining Translations

Translations live in a version-controlled `translations.yaml` file at the project root, alongside [`evidence.config.yaml` and `theme.yaml`](/features/project-settings). 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](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes))

```yaml theme={null}
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](https://www.i18next.com/translation-function/essentials) for each language.

### Nested Translations

You can organize translations into groups:

```yaml theme={null}
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](https://www.i18next.com/translation-function/nesting) for reusing translations within other translations:

```yaml theme={null}
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.

```markdown theme={null}
{% $translations.revenue %}
```

### Inline in Text

```markdown theme={null}
# {% $translations.revenue %} Dashboard
```

### In Component Attributes

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

### Templated in Strings

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

### In SQL

````markdown theme={null}
```sql home_sales
select
    label_{{ $translations.langcode }} as local_label
from description
```
````

## Fallback Behavior

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