LanguageSettings Class

Represents the language settings of the current thread. Use this class also when you want to be notified on language changes and to control the behavior of those DynamicResourceManager instances, which are configured to use centralized settings.

Definition

Namespace: KGySoft
Assembly: KGySoft.CoreLibraries (in KGySoft.CoreLibraries.dll) Version: 7.0.0
C#
public static class LanguageSettings
Inheritance
Object    LanguageSettings

Remarks

If you use KGySoft.CoreLibraries in a class library, then you do not really need to use this class. Just use the publicly available resources via the PublicResources class and let the consumers of your library adjusting the language settings by this class in their applications.

If you use KGySoft.CoreLibraries or other class libraries dependent on KGySoft.CoreLibraries in an application, then use this class to set the language of your application and the behavior of centralized resource managers. The KGySoft.CoreLibraries contains one centralized resource manager for the string resources used in the library. Some of these strings can be publicly accessed via the PublicResources members. See also the example below.

Example

The following example demonstrates how to generate resource files in your application for any language.
C#
using System;
using System.Globalization;
using KGySoft;
using KGySoft.Resources;

class Example
{
    static void Main(string[] args)
    {
        LanguageSettings.DisplayLanguage = CultureInfo.GetCultureInfo("de-DE");

        // Even though we set the language above centralized resources still return the built-in compiled resources.
        // Of course, if you use compiled resources in your application with the selected language, then they will be considered.
        Console.WriteLine("Non-localized resource:");
        Console.WriteLine(PublicResources.ArgumentNull);
        Console.WriteLine();

        // In an application that uses KGySoft.CoreLibraries you can opt-in to use dynamic resources from .resx files.
        LanguageSettings.DynamicResourceManagersSource = ResourceManagerSources.CompiledAndResX;

        // Next line tells that whenever a resource is requested, which does not exist in the resource file of the display
        // language, then its resource file will be dynamically created and/or expanded by the requested resource.
        LanguageSettings.DynamicResourceManagersAutoAppend = AutoAppendOptions.AppendFirstNeutralCulture;

        // Actually the default value is AutoAppendOptions.AppendFirstNeutralCulture | AutoAppendOptions.AppendOnLoad,
        // which causes to add not just the requested resource but all of the missing ones to the target resource file.
        // Delete the line above to see the difference.

        Console.WriteLine("Localized resource:");
        Console.WriteLine(PublicResources.ArgumentNull);
    }
}

// When this example is executed for the first time it produces the following output:

// Non-localized resource:
// Value cannot be null.
// 
// Localized resource:
// [T]Value cannot be null.

The [T] before a resource indicates that a new resource has been generated, which is not translated yet. In the Resources subfolder of your compiled project now there must be a new file named KGySoft.CoreLibraries.Messages.de.resx (the exact name depends on the display language and the appending strategy). Its content now must be the following:

XML
<?xml version="1.0"?>
<root>
  <data name = "General_ArgumentNull">
    <value>[T]Value cannot be null.</value>
  </data>
</root>

Search for the [T] values in the generated file to find the untranslated resources and feel free to change them. If you change the resource and execute the example again it will now show the translation you provided.

  Tip

  • If the AppendOnLoad flag is enabled in DynamicResourceManagersAutoAppend property, then not only the explicitly obtained resources but all resource entries will appeared in the localized resource set.
  • You can use the EnsureResourcesGenerated method to generate the possibly non-existing resource sets without explicitly accessing a resource first.
  • You can use the EnsureInvariantResourcesMerged method to forcibly merge all invariant resource entries even if a localized resource set already exists. This can be useful to add the possibly missing entries to the localization, if some new entries have been introduced in a new version, for example.
  • To see how to add a dynamic resource manager to your own class library see the Recommended usage for string resources in a class library section in the description of the DynamicResourceManager class.
  • To see how to use dynamically created resources for any language in a live application with editing support see the KGySoft.Drawing.Tools GitHub repository.

Properties

DisplayLanguage Gets or sets the display language of the current Thread, which is used for looking up localizable resources. When set, DisplayLanguageChanged and DisplayLanguageChangedGlobal events are triggered.
Default value: The display culture of the operating system.
DynamicResourceManagersAutoAppend Gets or sets the auto append options for the DynamicResourceManager instances of the current application domain when their UseLanguageSettings is .
Default value: AppendFirstNeutralCulture, AppendOnLoad
DynamicResourceManagersAutoSave Gets or sets the auto saving options for the DynamicResourceManager instances of the current application domain when their UseLanguageSettings is .
Default value: LanguageChange, DomainUnload, SourceChange
DynamicResourceManagersResXResourcesDir Gets or sets the path of the .resx resource files for the DynamicResourceManager instances of the current application domain when their UseLanguageSettings is . If , then even the centralized DynamicResourceManager instances may use individual path settings.
Default value:
DynamicResourceManagersSource Gets or sets the source, from which the DynamicResourceManager instances of the current application domain should take the resources when their UseLanguageSettings is .
Default value: CompiledOnly
FormattingLanguage Gets or sets the formatting language of the current Thread, which is used for formatting and parsing numbers, date and time values, currency, etc. When set, FormattingLanguageChanged and FormattingLanguageChangedGlobal events are triggered.
UnknownResourcePrefix Gets or sets the prefix of an unknown (non-existing) String resource. Used by the DynamicResourceManager instances if DynamicResourceManagersAutoAppend or AutoAppend property is configured to add non existing resources to the invariant resource set.
Default value: [U]
UntranslatedResourcePrefix Gets or sets the prefix of an untranslated String resource. Used by the DynamicResourceManager instances if DynamicResourceManagersAutoAppend or AutoAppend property is configured to use auto appending.
Default value: [T]

Methods

EnsureInvariantResourcesMerged Ensures that all invariant resource entries in all DynamicResourceManager instances with centralized settings are merged for the current DisplayLanguage. This method affects all DynamicResourceManager instances in the current application domain, whose UseLanguageSettings is .
EnsureResourcesGenerated Ensures that DynamicResourceManager instances with centralized settings load or generate the resource sets for the current DisplayLanguage. This method affects all DynamicResourceManager instances in the current application domain, whose UseLanguageSettings is .
ReleaseAllResources Ensures that DynamicResourceManager instances with centralized settings release all loaded resource sets without saving. This method affects all DynamicResourceManager instances in the current application domain, whose UseLanguageSettings is .
SavePendingResources Ensures that DynamicResourceManager instances with centralized settings save all pending changes. This method affects all DynamicResourceManager instances in the current application domain, whose UseLanguageSettings is .

Events

DisplayLanguageChanged Occurs when the display language (Thread.CurrentThread.CurrentUICulture) has been changed by setting the DisplayLanguage property. Only the subscriptions from the same thread are invoked.
DisplayLanguageChangedGlobal Occurs when the display language (Thread.CurrentThread.CurrentUICulture) has been changed in any Thread by setting DisplayLanguage property. The subscribers are invoked from all threads.
FormattingLanguageChanged Occurs when the formatting language (Thread.CurrentThread.CurrentCulture) has been changed by setting the FormattingLanguage property. Only the subscriptions from the same thread are invoked.
FormattingLanguageChangedGlobal Occurs when the formatting language (Thread.CurrentThread.CurrentCulture) has been changed in any Thread by setting FormattingLanguage property. The subscribers are invoked from all threads.

See Also