CodeChops.Idioma 0.7.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package CodeChops.Idioma --version 0.7.0
                    
NuGet\Install-Package CodeChops.Idioma -Version 0.7.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CodeChops.Idioma" Version="0.7.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CodeChops.Idioma" Version="0.7.0" />
                    
Directory.Packages.props
<PackageReference Include="CodeChops.Idioma" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add CodeChops.Idioma --version 0.7.0
                    
#r "nuget: CodeChops.Idioma, 0.7.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package CodeChops.Idioma@0.7.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=CodeChops.Idioma&version=0.7.0
                    
Install as a Cake Addin
#tool nuget:?package=CodeChops.Idioma&version=0.7.0
                    
Install as a Cake Tool

Idioma

Introduction

Translations for any .NET app, written in C#. The build makes sure every text exists in every language you support.

With resx files and IStringLocalizer, a text is a string key, and a mistake stays hidden until a user sees it: a mistyped key shows as the key itself, and a wording nobody translated shows in the default language. Here texts are C#, so both are build errors.

Declare your languages once, [assembly: SupportedLanguages("en", "nl")], and write each text in one of two ways.

Inline texts

An inline text is written in one line, where you use it:

<button>
  @LocalizableText.Inline(en: "Checkout", nl: "Afrekenen")
</button>

Check the demo InlineTextsDemo.cs to see it in action on your machine.

Sets

A set holds the texts that belong together, in one language: a class with a property per text. From the set of your default language, the build writes the contract IShopTranslations, which the other sets implement, and the class ShopTranslations, which shows the texts.

public partial class ShopTranslationsEN : ITranslationSet
{
    public virtual string Cart => "Cart";
    public virtual string Checkout => "Checkout";
}

public class ShopTranslationsNL : IShopTranslations
{
    public virtual string Cart => "Winkelwagen";
    public virtual string Checkout => "Afrekenen";
}
<button>
  @ShopTranslations.Checkout
</button>

Check the demo SetsDemo.cs to see it in action on your machine.

Add German to your languages, and the build asks for it in every inline text, and names the set to write:

error LOC004: 'ShopTranslations' has no translation into 'de', which [assembly: SupportedLanguages] requires. Add 'class ShopTranslationsDE : IShopTranslations'. A nested, generic, or file-local class does not count as a set.

Besides that:

  • No resource files and no string keys. In your IDE, hovering over ShopTranslations.Checkout shows its wording in every language, and you can jump to each.
  • Showing a text allocates no memory (what it costs), and the package is safe to trim.
  • In Blazor WebAssembly, users switch language without reloading the app, where resx files reload it or download every language at startup (details).

The rest of this page shows how to write your texts and show them. To see it working first, run a demo. For the details, such as which wording a user sees and what each build error means, see how Idioma works.

Getting started

Install

dotnet add package CodeChops.Idioma

The source generator comes with the package, so there is nothing else to set up. It needs .NET 10 or later and C# 14, the language version .NET 10 uses unless your project sets an older LangVersion.

Declare your languages

Add this to any C# file of your project, after its using lines:

using CodeChops.Idioma;

[assembly: SupportedLanguages("en", "nl")] // the first is the default

From then on, the build makes sure that every text of the project has each of these languages.

In a Blazor or Razor project, add the namespace to _Imports.razor as well, together with the namespace of your sets:

@using CodeChops.Idioma
@using MyApp.Translations

Write your texts

Write a text in one of two ways, and mix them as you like:

  • Inline text, written in one line where you use it, for single use in a component or page.
  • A set per language, each a class, for many reusable texts that belong together.
Write an inline text

Write the text where you use it: in markup, as in the introduction, or in C#:

public LocalizableText Title { get; } = LocalizableText.Inline(en: "Orders", nl: "Bestellingen");

Inline takes one argument per language you declared, so leaving a language out does not compile.

Write a set

A set is a class that holds your texts in one language. Write the set of your default language as a partial class named after that language, with one property per text:

public partial class ShopTranslationsEN : ITranslationSet
{
    public virtual string Cart => "Cart";
    public virtual string Checkout => "Checkout";
    public virtual string Greeting => "Hello, {0}!";
}

The source generator then writes the contract IShopTranslations, which lists every text, and the class ShopTranslations to show them with. Both take their name from the set's name without its language code, and land in the set's namespace. Write a set for every other language, a class that implements the contract:

public class ShopTranslationsNL : IShopTranslations
{
    public virtual string Cart => "Winkelwagen";
    public virtual string Checkout => "Afrekenen";
    public virtual string Greeting => "Hallo, {0}!";
}

Each text is virtual, so that a set deriving from this one can override it: a regional variant, or an app's rewording of a library's texts (details).

Show a text by its name, wherever you need it:

<button>
  @ShopTranslations.Cart
</button>

A missing text or a missing language is a build error. There is nothing to register: every set registers itself.

A regional variant, such as British English

ShopTranslationsEN serves every English culture, en-US and en-GB alike. For the texts that differ in Britain, list en-GB, and write a set with just those texts, named after the code in PascalCase and deriving from your English set:

[assembly: SupportedLanguages("en", "nl", "en-GB")]

public class ShopTranslationsEnGB : ShopTranslationsEN
{
    public override string Cart => "Basket";
}

British users see "Basket" and the rest of your English.

Once you list en-GB, the build asks for British wording everywhere, so that none is forgotten:

  • Every contract gets a British set. One with nothing British about it is a single line: public class GridTranslationsEnGB : GridTranslationsEN;.
  • Every inline text takes a British wording: LocalizableText.Inline(en: "Color", nl: "Kleur", enGB: "Colour").

To add British wording in one place only, see Language codes.

Show a text

A text shows the wording for the user's language wherever you put it: in markup as above, in string interpolation, or as a string, as in string label = ShopTranslations.Checkout;. A user whose language you do not support sees your default language (details).

For the wording in a language other than the user's, such as the language of an email's recipient, pass its culture to ToString:

string dutch = ShopTranslations.Checkout.ToString(CultureInfo.GetCultureInfo("nl"));

To compare a text with a string, use ==, as in text == "Afrekenen": it compares the wording for the current UI culture, where Equals and Contains do not (details).

Format a text

<p>
  @ShopTranslations.Greeting.Format(customer.Name)
</p>

Format fills in a text's placeholders. Give every language the same placeholders: the build checks it.

For a language other than the user's, pass its culture to Format, which then also formats the values for it:

string greeting = ShopTranslations.Greeting.Format(CultureInfo.GetCultureInfo("nl-NL"), customer.Name);

Blazor

Every language is compiled into your app, so in Blazor WebAssembly a user switches language without a download or a reload. Blazor in the details shows a language picker that does it, and covers Blazor on a server, dates and numbers, and texts passed between render modes.

Translating your texts

Your texts are C# in your repository, where an AI coding assistant works, and translating is something it does well. The build tells it what to write: add a language to the list, and the build names each set that is missing; add a text, and it names that text for each language that lacks it. So a text does not wait for its translation: it gets a wording in every language in the change that adds it.

That leaves a translator to review the wording, in a file with a line per text:

public virtual string Checkout => "Afrekenen";

The build checks every edit, an assistant's or a person's: a text left out or a placeholder dropped does not compile, so neither reaches a user.

Run a demo

The repository has two demos in its demos folder. Each is a complete app in one file, which dotnet run runs without a project:

Both support English, Dutch, and British English (en-GB), a regional variant of English, and print their texts in each. Run one from the demos folder of a clone:

dotnet run SetsDemo.cs

A demo runs with .NET 10 or later. Its first line fetches the latest version of the package.

Remove a Dutch wording from either file, and it no longer builds.

License

MIT. Code the source generator writes into your project is yours, and carries no obligations under this license.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.8.0 64 11/15/2026
0.7.0 80 11/14/2026
0.5.0 59 11/13/2026
0.4.0 62 11/13/2026
0.3.0 54 11/13/2026
0.2.0 57 11/13/2026
0.1.0 62 11/13/2026

A string compared as a text is a build error (LOC017): text.Equals("Orders"), list.Contains(name), Array.IndexOf(texts, name), and counts[name] on a dictionary of texts. They compare texts, not the wording a text shows, and a string becomes a text without translations, which equals no translated text, so the comparison was false while the text showed that wording. Compare the wording with ==, as in text == "Orders", or cast the string to LocalizableText to compare texts. A comparer you pass along, as in list.Contains(name, comparer), may compare the wording, so that call passes. The fix in an IDE turns text.Equals(wording) into text == wording.

A LanguageCode that is no culture name, such as "en_GB", is build error LOC018: the set would throw as it registers.

The generated class holds nothing but the texts: the constant ResourceKeyPrefix is gone, so a text can be named ResourceKeyPrefix, and LOC014 is left with a text named like the class itself. Read the prefix from a text's key, as in ShopTranslations.Checkout.Key, which is "Shop.Checkout".

A set whose language the build cannot read, because its LanguageCode is no constant, is no longer reported as a missing language, and the placeholders of a text a set inherits from a base class are held to those of the contract as well (LOC016).

How the package works is in docs/how-it-works.md, which the README links to.

Version 0.6.0 was not published, so its changes come with this version:

A text written inline is LocalizableText.Inline(en: "Checkout", nl: "Afrekenen"), where it was LocalizableText.Translated. That is the name the docs and the messages of the build already gave it: an inline text.

A set implements ITranslationSet, where it was ITranslations: public partial class ShopTranslationsEN : ITranslationSet. The interface names one set, as the docs do. The generated contract keeps its name, such as IShopTranslations, and so do the generated class and TranslationsRegistry.

Three parameters are named after the set: Register and RegisterDefaults take sets, ResourceText.GetTranslation takes set, and ITranslationSet.GetLanguageCode takes setType. Only a call that names such an argument needs the new name.

To move a project, replace LocalizableText.Translated with LocalizableText.Inline, and ITranslations with ITranslationSet. The messages of the build and the fixes in an IDE use the new names.