Using GetText - perpetualKid/GetText.NET GitHub Wiki

Using GetText.NET

Installation

Install as NuGet package from the package manager console:

PM> Install-Package GetText.NET

or through .NET CLI utility:

$ dotnet add package GetText.NET

Using GetText.NET:

	using GetText;
	// This will load translations from "./locale/<CurrentUICulture>/Example.mo"
	ICatalog catalog = new Catalog("Example", "./locale");
	
	// or
	
	// This will load translations from "./locale/ru_RU/Example.mo"
	ICatalog catalog = new Catalog("Example", "./locale", new CultureInfo("ru-RU"));
	Console.WriteLine(catalog.GetString("Hello, World!")); // will translate "Hello, World!" using loaded translations
	Console.WriteLine(catalog.GetString("Hello, {0}!", "World")); // string.Format support
	Console.WriteLine(catalog.GetString($"Hello, {"World"}!")); // string interpolation support

.NET CoreCLR

To use this library under CoreCLR for encodings different from UTF-8 in *.mo files, System.Text.Encoding.CodePages package needs to be included into the application and initialized like this:

	#if NETCOREAPP1_0
		Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
	#endif

Culture-specific message formatting

	// All translation methods support String.Format optional arguments
	catalog.GetString("Hello, {0}!", "World");
	
	// Catalog's current locale will be used to format messages correctly
	catalog.GetString("Here's a number: {0}!", 1.23);
	// Will return "Here's a number: 1.23!" for en_US locale
	// But something like this will be returned for ru_RU locale with Russian translation: "А вот и номер: 1,23!"

Plural forms

	catalog.GetPluralString("You have {0} apple.", "You have {0} apples.", count);
	// Returns (for en_US locale):
	//     "You have {0} apple." for count = 1
	//     "You have {0} apples." otherwise


	catalog.GetPluralString("You have {0} apple.", "You have {0} apples.", 5, 5);
	// Returns translated plural massage: "You have 5 apples." (for en_US locale)
	// First “5” used in plural forms determination; second — in String.Format method


	// Example plural forms usage for fractional numbers:
	catalog.GetPluralString("You have {0} apple.", "You have {0} apples.", (long)1.23, 1.23);
	// Internal String.Format will be used in context of catalog's locale and formats objects respectively

Contexts

	catalog.GetParticularString("Menu|File|", "Open"); // will translate message "Open" using context "Menu|File|"
	catalog.GetParticularString("Menu|Project|", "Open"); // will translate message "Open" using context "Menu|Project|"

Multiple locales and domains in one application instance

	// "./locale/en_US/Example.mo"
	ICatalog example_en = new Catalog("Example", "./locale", new CultureInfo("en-US"));

	// "./locale/fr/LC_MESSAGES/Example.mo"
	ICatalog example_fr = new Catalog("Example", "./locale", new CultureInfo("fr"));

	// "./locale/<CurrentUICulture>/AnotherDomainName.mo"
	ICatalog anotherDomain = new Catalog("AnotherDomainName", "./locale");

Direct MO file loading

	Stream moFileStream = File.OpenRead("path/to/domain.mo");
	ICatalog catalog = new Catalog(moFileStream, new CultureInfo("en-US"));

Parsing plural rules from the *.mo file header

GetText.NET can parse plural rules directly from the *.mo file header and compile it to a dynamic method in runtime. To enable this option pass the MoCompilingPluralLoader from the GetText.NET.PluralCompile package to the Catalog constructor:

	ICatalog catalog = new Catalog(new MoCompilingPluralLoader("Example", "./locale"));

This loader will parse plural formula from the *.mo file header and compile it to plural rule for the Catalog instance at runtime, just when the *.mo file loads. The Catalog's *PluralString methods performance will be the same as if using GetText.NET default precompiled plural rules, only *.mo file loading will be slightly slower.

This feature requires enabled JIT compiler in the runtime. MoCompilingPluralLoader can not be used in an full-AOT environment. This is why MoCompilingPluralLoader moved to a separate library.

For hosts without enabled JIT, use MoAstPluralLoader which will only parse plural formulas to an abstract syntax tree and interpret it every time a call to *PluralString method is made from the catalog, without compiling. Please note that this solution is slightly slower than MoCompilingPluralLoader even it's pretty well optimized.

Custom plural formulas

	catalog.PluralRule = new PluralRule(numPlurals, n => ( n == 1 ? 0 : 1 ));

Custom plural rule generator can be created by implementing IPluralRuleGenerator interface, which will create a PluralRule for any culture.

Debugging

Debug version of the GetText.NET binary outputs debug messages to System.Diagnostics.Trace. Register trace listeners to see GetText.NET debug messages. Please note that Release version of the GetText.NET binary does not produse any trace messages.

	Trace.Listeners.Add(new TextWriterTraceListener(Console.Out));

Poedit compatibility

For Poedit compatibility, the plural form needs to be specified in the *.po file header, also for english language:

	"Plural-Forms: nplurals=2; plural=n != 1;\n"

And a keywords list:

	"X-Poedit-KeywordsList: GetString;GetPluralString:1,2;GetParticularString:1c,2;GetParticularPluralString:1c,2,3;_;_n:1,2;_p:1c,2;_pn:1c,2,3\n"
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️