Echoes

Simple type safe translations for Avalonia and .NET.

Features

• Change language at runtime without reloading views or flicker (obviously - but hard with ResX)
• Translation keys are generated at compile time. Missing keys (from the invariant) will show up as compiler errors.
• Markup extension for simple usage
• Simple translation file format based on TOML
• Multiple translation files, so you can split translations by feature or module
• Inside each file, translations can be grouped and nested using dotted key syntax or group/table syntax, providing a clean, hierarchical structure within a single file
• Supports ISO 639-1 (en, de) and RRC 5646 (en-US, en-GB, de-DE) translation identifiers
• Built-in automatic fallback: if a key is missing in a specific locale (e.g., de-AT), it will automatically fall back to a language-only locale (e.g., de), and then to the invariant file if still not found
• Autocomplete of translation keys

Getting Started

It's best to take a look at the Sample Project

Add references to the following packages:

<PackageReference Include="Echoes" Version=".."/>
<PackageReference Include="Echoes.Generator" Version=".."/>

<!-- For Avalonia Helpers -->
<PackageReference Include="Echoes.Avalonia" Version=".."/>

Specify translations files (Embedded Resources, Source Generator)

<ItemGroup>
    <!-- Include all .toml files as embedded resources (so we can dynamically load them at runtime) -->
    <EmbeddedResource Include="**\*.toml" />

    <!-- Specify invariant files that are fed into the generator (Echoes.Generator) -->
    <AdditionalFiles Include="Translations\Strings.toml" />
</ItemGroup>

Caution

You currently have to place your translation (.toml) files and the generated code in a separate project. This is because Avalonia also generates code using their XAML compiler. In order for the xaml compiler to see your translations you need to put them in a different project. Otherwise you'll get a compiler error.

Translation Files

Translations are loaded from .toml files. The invariant file is special as it defines structure and configuration. Additional language files are identified by _{lang}.toml postfix.

Strings.toml
Strings_de.toml
Strings_de-AT.toml
Strings_es.toml

You can split translations in multiple toml files.

FeatureA.toml
FeatureA_de.toml
FeatureA_es.toml

FeatureB.toml
FeatureB_de.toml
FeatureB_es.toml

File Format

Example: Strings.toml

[echoes_config]
generated_class_name = "Strings"
generated_namespace = "Echoes.SampleApp.Translations"

[translations]
hello_world = 'Hello World'
greeting = 'Hello {0}, how are you?'

# Nested via dotted keys
dialog.ok     = "OK"
dialog.cancel = "Cancel"

# Nested via tables
[settings.display]
brightness = "Brightness"
contrast   = "Contrast"

Example: Strings_de.toml

hello_world = 'Hallo Welt'
greeting = 'Hallo {0}, wie geht es dir?'

dialog.ok     = "OK"
dialog.cancel = "Abbrechen"

[settings.display]
brightness = "Helligkeit"
contrast   = "Kontrast"

XAML Usage

Namespaces

Add namespaces for the generated translations and the helper markup extension:

<Window
    xmlns="https://github.com/avaloniaui"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:translations="clr-namespace:Your.Namespace;assembly=Your.Assembly"
    xmlns:echoes="clr-namespace:Echoes.Avalonia;assembly=Echoes.Avalonia">

Referencing keys (using the Echoes Avalonia markup extension)

Top-level entry (offers IntelliSense):

<TextBlock Text="{echoes:Translate {x:Static translations:Strings.hello_world}}" />

Nested entry (after + IntelliSense is currently limited by XAML tooling):

<TextBlock Text="{echoes:Translate {x:Static translations:Strings+settings+display.brightness}}" />
<Button Content="{echoes:Translate {x:Static translations:Strings+dialog.ok}}" />

When the culture is changed at runtime, all bound Translate values automatically update without needing to reload views.

Is this library stable?

No, it's currently in preview. See the version number.

Will there be support for other frameworks (WPF, MAUI, etc.)?

No, the focus is on Avalonia. However, the core library is framework-agnostic and can be used in any .NET project. So you can build your own helpers for other frameworks if needed. We'll just not include them in this repository because we want to keep the scope limited.

Will you add more features?

No, the library is intentionally kept simple. Unless we find a missing essential feature, we won't add more features. We might even remove some features if they complicate the library too much.

Why is it named "Echoes"?

The library is named after the Pink Floyd song Echoes.