CodeChops.Idioma
0.8.0
dotnet add package CodeChops.Idioma --version 0.8.0
NuGet\Install-Package CodeChops.Idioma -Version 0.8.0
<PackageReference Include="CodeChops.Idioma" Version="0.8.0" />
<PackageVersion Include="CodeChops.Idioma" Version="0.8.0" />
<PackageReference Include="CodeChops.Idioma" />
paket add CodeChops.Idioma --version 0.8.0
#r "nuget: CodeChops.Idioma, 0.8.0"
#:package CodeChops.Idioma@0.8.0
#addin nuget:?package=CodeChops.Idioma&version=0.8.0
#tool nuget:?package=CodeChops.Idioma&version=0.8.0
Idioma
Translations for any .NET app, written in C# and checked at compile time:
- The build catches the mistakes that resx files hide until a user sees them: a mistyped key, a text missing from a language, or a translation whose placeholders differ from the original.
- There are no resource files, so you get full IDE support: autocomplete, go to definition, and find all references.
- An AI coding assistant can translate your texts, and the build tells it which are missing (details).
- The package has no dependencies, is light and fast, and is safe to trim and to publish with Native AOT.
Declare your languages once, [assembly: SupportedLanguages("en", "nl")], and write each text in one of two ways:
in a set per language, for texts you reuse, or inline, where you use it once.
public partial class ShopTranslationsEN : ITranslationSet
{
public string Cart => "Cart";
public string Checkout => "Checkout";
}
public class ShopTranslationsNL : IShopTranslations
{
public string Cart => "Winkelwagen";
public string Checkout => "Afrekenen";
}
From the English set, the source generator writes the contract IShopTranslations, which the Dutch set implements, and the class ShopTranslations, which shows each text in the user's language:
@* A text of a set *@
<button>
@ShopTranslations.Checkout
</button>
@* An inline text *@
<button>
@LocalizableText.Inline(en: "Cancel", nl: "Annuleren")
</button>
Getting started
For complete apps to run, see the demos, or run them in your browser:
Install
dotnet add package CodeChops.Idioma
The package 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.
When your texts are in a library, declare your languages in the app's own project as well, the project that starts: your users get the languages of the app (details).
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.
Write a set
A set (like a resx file) holds the texts that belong together, in one language: a class with a property per text.
It suits texts you reuse. Write the set of your default language as a partial class whose name ends in the code of that language in capitals, as in ShopTranslationsEN:
public partial class ShopTranslationsEN : ITranslationSet
{
public string Cart => "Cart";
public string Checkout => "Checkout";
public string Greeting => "Hello, {0}!";
}
That makes three names to tell apart:
ShopTranslationsENis the set you wrote, in your default language.IShopTranslationsis the contract, which lists every text. The source generator writes it from your set.ShopTranslationsis the class you show the texts with. The source generator writes it as well.
Both generated names are the set's name without its language code, and both land in the set's namespace.
Write a set for every other language, a class that implements the contract:
public class ShopTranslationsNL : IShopTranslations
{
public string Cart => "Winkelwagen";
public string Checkout => "Afrekenen";
public string Greeting => "Hallo, {0}!";
}
A missing text or a missing language is a build error. There is nothing to register: every set registers itself.
Add German to your languages, and the build 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.
Write an inline text
An inline text is written in one line where you use it, for single use in markup or in C#:
public LocalizableText Title { get; } = LocalizableText.Inline(en: "Orders", nl: "Bestellingen");
Inline takes one argument per language you declared, so leaving out a translation does not compile.
Show a text
Show a text by its name, wherever you need it:
<button>
@ShopTranslations.Cart
</button>
In your IDE, hovering over ShopTranslations.Cart shows its wording in every language, and you can jump to each.
A text shows the wording for the user's language in markup, 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).
Every text is a LocalizableText, so that is the type for a text your own code holds or takes, as the Title above does. A text of a set is a ResourceText: a LocalizableText that also carries a key (details).
The user's language is CultureInfo.CurrentUICulture.
A desktop or console app starts with the language of the user's system, and a Blazor WebAssembly app with that of the browser.
An ASP.NET Core app needs request localization, as in
app.UseRequestLocalization("en", "nl"), which sets the language for each request. Without it, every user gets the language of the server.
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"));
Format a text
Format fills in a text's placeholders, which are those of String.Format, so one can carry a format, as in {0:N2}:
<p>
@ShopTranslations.Greeting.Format(customer.Name)
</p>
Give every language the same placeholders. A Dutch greeting that lost its {0} is a build error:
error LOC016: 'ShopTranslationsNL.Greeting' has no placeholders, while the default wording of 'IShopTranslations.Greeting' has placeholder {0}. Give every language the same placeholders: otherwise Format throws, or leaves out a value, for the users of one language.
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);
Going further
Add 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, make them virtual in your English set, and write a set with just those texts, named after the code in PascalCase and deriving from the English one:
[assembly: SupportedLanguages("en", "nl", "en-GB")]
public partial class ShopTranslationsEN : ITranslationSet
{
public virtual string Cart => "Cart"; // Virtual, so the British set can override it
// Your other texts, as they were
}
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.
Compare a text with a string
To compare a text with a string, use ==, which compares the wording for the current UI culture:
bool isCheckout = text == "Afrekenen";
Equals and Contains compare texts instead, so they are false for a string even while the text shows that wording. The build rejects a string passed to them (LOC017).
Change a text of a library
A library can use Idioma for its own texts, as your app does. To change one of them, write a set in your app that derives from the library's set of that language, name it after that language too, and override the text:
// DataTableTranslationsEN is the English set of a library your app uses
public sealed class MyDataTableTranslationsEN : DataTableTranslationsEN
{
public override string Empty => "No orders yet"; // Empty is virtual in DataTableTranslationsEN
}
Your wording wins over the library's, and every other text keeps the library's wording.
For a text that is not virtual, or a library that lacks one of your languages, see Libraries that use Idioma.
Translating your texts
An AI coding assistant can translate your texts, as they are C# in your repository, and 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 the build names it 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.
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.
Where Idioma does not fit
- When you need to add translations without a new build. Every language is compiled into your assembly, so a new language or a changed wording takes a new build. Where a wording must change without one, your app can let a resource file override it (details).
- When your translators work in a translation tool, which reads files such as XLIFF.
- When you use an older version of .NET than 10 or C# 14.
Details
Each subject has a page of its own:
- How Idioma works: which wording a user sees, what the source generator writes, how sets register, how to read a set yourself, and how a text travels through JSON.
- Language codes: how a set's name gives its language, and the two ways to add a regional variant.
- Libraries that use Idioma: which project's languages your users get, what the build asks when such a library lacks one of them, and how your app changes one of its texts.
- Blazor: switching language without a reload, Blazor on a server, dates and numbers, and a text as a component parameter.
- What the build rejects: every build error and warning by its code, what still converts to a text, and what the build misses.
- Coming from resx: what becomes what, moving a resource file, and keeping a resource file as an override.
- The demos: two complete apps, each in one file, which
dotnet runruns without a project, and which fetch the latest package version.
License
MIT. Code the source generator writes into your project is yours, and carries no obligations under this license.
| Product | Versions 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. |
-
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.
The key of a text of a set is its full name: MyApp.Translations.ShopTranslations.Checkout for ShopTranslations.Checkout in the namespace MyApp.Translations, where it was Shop.Checkout. The old key left out the namespace and a trailing Translations, so the texts of two sets of one name shared a key: sets in two namespaces, in a library and in the app that uses it, or ShopTranslationsEN next to ShopEN. Now each text has a key of its own. A set in the global namespace gives ShopTranslations.Checkout, and a namespace part named like a keyword comes without its @.
The package itself never reads the key, so every text shows the wording it showed. Only an app or library that looks wording up by the key, as in a resource file through IStringLocalizer, has something to do: rename each entry to the full name of its text, which is the name your code calls the text by, with its namespace in front.
A language code that is wrong is not a culture name in the messages of the build and of the registry, where it was no culture name (LOC010, LOC018), and LOC016 names a brace that is not a placeholder. Only a test that holds such a message to its wording needs the new one.
The details have a page per subject under docs/, which the README links to: how Idioma works, language codes, libraries that use Idioma, Blazor, what the build rejects, and coming from resx. New in them: your users get the languages of the app's own project, so an app that keeps its texts in a library declares its languages in both; what the build misses in a call of Format, where a value too few throws when the call runs; and the class the source generator writes to register your sets, which is public in an assembly that has sets.
The demos are SetDemo.cs and InlineTextDemo.cs, and run in a codespace from the README.