Skip to content

About

xaml-lang-formatter is a formatter for WPF ResourceDictionary localization files.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

14 Commits

Folders and files

Repository files navigation

xaml-lang-formatter

CI GitHub Pages

xaml-lang-formatter is a formatter for WPF XAML and Avalonia AXAML ResourceDictionary localization files. It understands language-resource keys such as Meta.Name, Common.Action.Open, and Application.Window.Title, then rewrites the dictionary into deterministic, review-friendly sections.

The repository currently contains:

  • a Rust CLI binary, xaml-lang-formatter;
  • a reusable Rust library API used by both CLI and WASM;
  • a wasm-bindgen wrapper crate;
  • a Nuxt 4 + Nuxt UI 4 browser app using Bun and CodeMirror 6;
  • GitHub Actions workflows for CI and GitHub Pages deployment.

The current package version is 0.2.0.

Releases

Prebuilt binaries and the Weblate add-on wheel are published on the GitHub Releases page:

  • Windows x86-64: .zip archive or standalone .exe;
  • Linux x86-64 / arm64: static .tar.gz archives;
  • Weblate add-on: xaml_lang_formatter_weblate-<version>-py3-none-any.whl with bundled platform binaries.

Features

  • Formats .xaml WPF and .axaml Avalonia localization dictionaries.
  • Keeps the Avalonia root header in the aligned style used by Avalonia projects.
  • Supports individual files and recursive directory formatting.
  • Defaults to the current working directory when no path is provided.
  • Groups resources by dotted x:Key prefixes.
  • Keeps the Meta top-level section first.
  • Uses a configurable nested-group threshold. The default is 8.
  • Regenerates grouping comments consistently.
  • Adds a top formatter comment with a timestamp.
  • Rejects duplicate x:Key values.
  • Escapes XML text and attributes, including newline entities.
  • Provides the same formatter behavior in CLI and browser via Rust WebAssembly.
  • Ships a modern web UI with a single CodeMirror editor and in-place formatting.

Formatting examples

WPF XAML

Input:

<ResourceDictionary
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:sys="clr-namespace:System;assembly=mscorlib"
        xml:space="preserve">

    <sys:String x:Key="Common.Action.Open">Open</sys:String>
    <sys:String x:Key="Meta.Code">en-US</sys:String>
    <sys:String x:Key="Common.App">App</sys:String>

</ResourceDictionary>

Output with the default threshold 8:

<!-- Formatted by xaml-lang-formatter at 2026-06-28T15:21:30. -->
<ResourceDictionary
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:sys="clr-namespace:System;assembly=mscorlib"
        xml:space="preserve">

    <!-- Meta -->

    <sys:String x:Key="Meta.Code">en-US</sys:String>

    <!-- Common -->

    <sys:String x:Key="Common.Action.Open">Open</sys:String>
    <sys:String x:Key="Common.App">App</sys:String>

</ResourceDictionary>

A nested section such as Common.Action is only created when at least 8 resources share that prefix, unless you override the threshold.

Avalonia AXAML

Avalonia dictionaries use the same resource shape with an Avalonia root header. .axaml files are detected automatically, and the root header keeps the aligned Avalonia layout:

<!-- Formatted by xaml-lang-formatter at 2026-11-20T00:00:00. -->
<ResourceDictionary xmlns="https://github.com/avaloniaui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                    xmlns:sys="clr-namespace:System;assembly=System.Runtime"
                    xml:space="preserve">

    <!-- Meta -->

    <sys:String x:Key="Meta.Code">en-US</sys:String>

    <!-- Common -->

    <sys:String x:Key="Common.App">App</sys:String>

</ResourceDictionary>

CLI usage

Run from source:

cargo run -- ./Lang/en-US.xaml
cargo run -- ./Lang/en-US.axaml
cargo run -- ./Lang
cargo run -- ./Lang --check
cargo run -- ./Lang --dry-run
cargo run -- ./Lang --backup
cargo run -- ./Lang --group-threshold 8

When no path is passed, the formatter uses the current working directory:

cargo run

After installing or building the binary:

xaml-lang-formatter
xaml-lang-formatter ./Lang
xaml-lang-formatter ./Lang/en-US.xaml --check
xaml-lang-formatter ./Lang/en-US.axaml --check

CLI options

Option Description
[paths...] Files or directories to format. Defaults to the current directory when omitted.
--check Check whether files are already formatted. Does not write changes.
--dry-run Print files that would change. Does not write changes.
--backup Write a .bak file next to the original before overwriting it.
--group-threshold <N> Minimum number of resources sharing a prefix before creating a nested section. Default: 8.
--partition-threshold <N> Alias for --group-threshold.
--no-recursive Only format direct .xaml / .axaml files in a directory.
--help Show the full CLI help.

Formatting rules

  • Only the root ResourceDictionary is formatted.
  • WPF .xaml and Avalonia .axaml files are both supported.
  • Avalonia dictionaries are detected by the https://github.com/avaloniaui root namespace and keep an aligned root header.
  • Existing grouping comments are ignored and regenerated.
  • A formatter comment is written at the top of the file.
  • Top-level key prefixes always become sections.
  • Meta is always sorted before other top-level sections.
  • Other top-level sections are sorted alphabetically.
  • A nested prefix becomes a section only when its resource count reaches the group threshold.
  • Items that do not reach the nested threshold stay under the closest parent section.
  • Items inside the same section are sorted by full x:Key.
  • Duplicate x:Key values are rejected.
  • --check remains stable for already formatted files by reusing an existing formatter timestamp.

Supported XAML shape

This formatter intentionally targets plain localization resources:

<ResourceDictionary ...>
<sys:String x:Key="Common.App">App</sys:String>
<sys:String x:Key="Common.Action.Open">Open</sys:String>
        </ResourceDictionary>

Supported:

  • ResourceDictionary as the root element;
  • WPF presentation namespaces and Avalonia (https://github.com/avaloniaui) namespaces;
  • direct child resources with an x:Key or *:Key attribute;
  • plain text content;
  • self-closing keyed child elements;
  • XML declarations and root attributes;
  • existing formatter comments.

Currently unsupported:

  • nested XAML objects inside resource values;
  • CDATA sections;
  • arbitrary non-keyed child resources;
  • preserving original hand-written grouping comments.

Rust library API

The root crate exposes a library API in src/api.rs so the CLI and WASM wrapper share one formatter implementation.

use xaml_lang_formatter::api::{format_xaml, FormatOptions};

let output = format_xaml(
input,
& FormatOptions {
group_threshold: 8,
timestamp: "2026-06-28T15:21:30".to_string(),
},
) ?;

The CLI feature is enabled by default. For non-CLI consumers such as WASM, use the crate with default features disabled.

Web UI

The web app lives in web/ and uses:

  • Nuxt 4;
  • Nuxt UI 4;
  • Bun;
  • CodeMirror 6 for XML editing;
  • a local WASM build generated from crates/wasm.

The UI formats the current CodeMirror editor content in place. It accepts WPF .xaml and Avalonia .axaml files. Files are read locally through the browser and are not uploaded.

Web development

Install dependencies and build the WASM package:

cd web
bun install
bun run wasm:build
bun --bun run dev

Open the Nuxt dev server URL printed by the command.

Web typecheck and production build

cd web
bun run typecheck
bun run wasm:build
NUXT_APP_BASE_URL=/xaml-lang-formatter/ bun run build
bun run preview

WASM build details

The web build command runs:

cd crates/wasm
wasm-pack build --target web --release --out-dir ../../web/public/wasm

wasm-opt is disabled in crates/wasm/Cargo.toml to avoid requiring Binaryen downloads during local builds and CI.

Weblate add-on

This repository ships a Weblate add-on in contrib/weblate/. It runs xaml-lang-formatter on ResourceDictionary translation files (.xaml and .axaml) right before Weblate commits them, so the formatted output is part of the same commit and no extra commit is created.

The add-on bundles prebuilt binaries per platform (Linux x86-64/arm64 and Windows) and exposes the group threshold, timeout, and a custom binary path as configuration options.

See contrib/weblate/README.md for installation, registration, configuration, and the platform matrix.

GitHub Pages deployment

The repository includes .github/workflows/pages.yml.

To enable deployment:

  1. Open the repository on GitHub.
  2. Go to Settings → Pages.
  3. Set Source to GitHub Actions.
  4. Push to master or run the workflow manually.

The default Pages URL is expected to be:

https://pcl-community.github.io/xaml-lang-formatter/

For a custom domain, adjust or remove NUXT_APP_BASE_URL in the Pages workflow.

Development checks

Run the Rust checks:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Run the WASM check/build:

cargo check --manifest-path crates/wasm/Cargo.toml --target wasm32-unknown-unknown
cd web
bun run wasm:build

Run the web checks:

cd web
bun install
bun run typecheck
bun run build

Project layout

xaml-lang-formatter/
├── src/
│   ├── api.rs          # Shared formatter API
│   ├── cli.rs          # clap CLI definition
│   ├── formatter.rs    # File and directory processing
│   ├── grouping.rs     # x:Key prefix tree and grouping rules
│   ├── lib.rs          # Library exports
│   ├── main.rs         # CLI entry point
│   ├── model.rs        # Document model
│   ├── parser.rs       # ResourceDictionary parser
│   └── writer.rs       # Deterministic XML writer
├── crates/
│   └── wasm/           # wasm-bindgen wrapper crate
├── contrib/
│   └── weblate/        # Weblate pre-commit add-on (bundles the CLI binary)
├── web/
│   ├── app/            # Nuxt 4 app source
│   ├── public/wasm/    # Generated WASM output
│   ├── bun.lock
│   ├── nuxt.config.ts
│   └── package.json
└── .github/workflows/
    ├── ci.yml          # Rust, WASM, and web checks
    └── pages.yml       # GitHub Pages deployment

Troubleshooting

wasm-pack tries to download Binaryen

The WASM crate disables wasm-opt in release builds:

[package.metadata.wasm-pack.profile.release]
wasm-opt = false

If you still see Binaryen download errors, make sure you are running bun run wasm:build from the current project files.

GitHub Pages loads a blank page or cannot find WASM

Use the repository base URL when building for Pages:

cd web
NUXT_APP_BASE_URL=/xaml-lang-formatter/ bun run build

The runtime imports WASM from public/wasm, so the base URL must match the deployment path.

--check reports files as changed after a previous format

--check reuses the existing formatter timestamp when it detects one. If a file was edited manually or the formatter comment was removed, run the formatter once before using --check in CI.

License

This project is licensed under the Apache License 2.0. See LICENSE for details.

About

xaml-lang-formatter is a formatter for WPF ResourceDictionary localization files.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages