Start by identifying whether the failure is in the core service pipeline, a framework adapter, source generation, documentation, packaging, or platform tooling. ProTranslate keeps these areas intentionally separate, so a failure in one package should not be fixed by duplicating policy in another adapter.
If Translate, T, Format, F, or Translation.* cannot be resolved, verify the adapter package reference and the XAML namespace for the target framework.
Avalonia and WPF can use prefix-free sample syntax after the adapter assembly is referenced because those adapters map into the framework default namespace. They also support the shared ProTranslate URI:
xmlns:pt="https://github.com/protranslate/xaml"
MAUI should use the shared URI because its default namespace is protected:
xmlns:pt="https://github.com/protranslate/xaml"
WinUI should use the adapter namespace directly:
xmlns:pt="using:ProTranslate.WinUI"
Uno emits the shared URI mapping for tooling that honors XmlnsDefinition, but the sample uses WinUI-compatible syntax:
xmlns:pt="using:ProTranslate.Uno"
If prefix-free markup works in Avalonia or WPF but not in MAUI, WinUI, or Uno, switch to the explicit pt: form. That is expected.
Check that the adapter is connected to the same core services used by the application.
With dependency injection, register both the core and the framework adapter helper:
services.AddProTranslate(provider, CultureInfo.GetCultureInfo("en-US"));
services.AddProTranslateAvalonia();
using ServiceProvider serviceProvider = services.BuildServiceProvider();
serviceProvider.UseProTranslateAvalonia();
Use the matching AddProTranslateWpf, AddProTranslateMaui, AddProTranslateWinUI, or AddProTranslateUno helper and post-build UseProTranslate... bootstrap method for other frameworks.
Without dependency injection, connect the static adapter binding source:
ProTranslate.Avalonia.TranslationService.UseService(translations, cultures);
Use the matching static adapter class for the active framework. If XAML uses attached Translation.Culture or Translation.AutoFlowDirection, verify the property is applied to an element that participates in the relevant visual or logical tree.
Missing keys return the key by default and set LocalizedString.ResourceNotFound. They are also represented through structured diagnostics. This is the expected production-safe behavior unless the host configures failure behavior differently.
Check these points:
CompositeTranslationProvider.resx base names and resource visibility are correct for ResourceManagerTranslationProviderIStringLocalizer is registered for the expected resource typeEnable ProTranslate.Analyzers to catch missing static keys at build time with PTA001.
Provider exceptions can be reported and continued or reported and thrown depending on configured failure behavior. If translations fall back unexpectedly, subscribe to ITranslationService.DiagnosticReported or use an IProTranslateDiagnosticSink to inspect provider-failure diagnostics.
For ResourceManager, verify satellite assemblies, resource base names, culture-specific files, and build actions. For IStringLocalizer, verify that Microsoft.Extensions localization is configured before adding the ProTranslate string-localizer provider.
ITranslationService.Format uses string.Format(CurrentCulture, value, args). Invalid placeholders or mismatched arguments produce format-failure diagnostics. By default, the unformatted localized value is returned unless the host opts into throwing.
For dynamic values in XAML, use view-model properties when native binding support is limited. Avalonia, WPF, and MAUI support bound Value formatting through native multi-binding. WinUI and Uno preserve Value={Binding ...} through a formatting converter, while complex formatted workflows are still best kept in view-model or x:Bind paths.
The source generator reads additional files named:
*.protranslate.keys.txtStrings.*.json*.protranslate.jsonFor text files, use one key per line. Lines beginning with # are comments. For JSON catalogs, use valid JSON with flat or nested keys. Invalid JSON reports warning PTSG001; duplicate keys in one catalog report warning PTSG002.
If generated constants are missing, verify that the catalog file is included as an additional file in the consuming project and that the project references ProTranslate.SourceGenerator as an analyzer package or project reference according to the current repository pattern.
If generated identifiers collide, the generator normalizes identifiers and adds stable hash suffixes. Prefer stable, descriptive resource keys to keep generated member names readable.
Use the narrowest command that matches the failure:
dotnet restore ProTranslate.CI.slnx
dotnet build ProTranslate.CI.slnx -c Release --no-restore
dotnet test tests/ProTranslate.Tests/ProTranslate.Tests.csproj -c Release --no-build
dotnet test tests/ProTranslate.Analyzers.Tests/ProTranslate.Analyzers.Tests.csproj -c Release --no-build
dotnet test tests/ProTranslate.Avalonia.Tests/ProTranslate.Avalonia.Tests.csproj -c Release --no-build
WPF and WinUI require Windows targeting. The repository enables Windows targeting where needed, and real WPF/WinUI sample validation belongs on Windows. Uno samples use Uno.Sdk desktop heads, so build failures there should be investigated as regular Uno XAML generator or desktop host issues rather than treated as non-Windows stubs.
MAUI builds require the MAUI workload. Install it before building the MAUI sample or expecting pack.sh to produce ProTranslate.Maui:
dotnet workload install maui
Run:
./build-docs.sh
The script restores .NET tools and runs Lunet from the site directory. If navigation references a missing article, either create the article or update the menu in a separate documentation task. For this docs site, generated output is under site/.lunet/build/www.
To reproduce the local serve path:
./serve-docs.sh
If the default port is busy:
DOCS_PORT=8081 ./serve-docs.sh
Use:
./pack.sh 0.1.0
Package artifacts are written to artifacts/packages. The script discovers packable projects under src, requires .nupkg outputs and runtime .snupkg outputs, validates README inclusion, and checks analyzer/source-generator layout. Release publishing requires NUGET_API_KEY in GitHub Actions. Tag releases must use v* tags, and manual release runs publish to NuGet only when publish_nuget is true.
Current limitations are not setup errors:
XmlnsDefinitionAttribute