Overview

L10NSharp is a .NET localization library. It collects strings which need localization when your application first runs and saves them in a translation memory file.

L10NSharp.Windows.Forms builds on L10NSharp and should be used for localization of Windows Forms applications.

L10NSharp works with XLIFF files as translation memory.

How to use

L10NSharp and L10NSharp.Windows.Forms are provided as nuget packages.

To use L10NSharp in your application, call the Create method on LocalizationManager, passing the location of the translation memory XLIFF files and some other information:

using (var lm = LocalizationManager.Create(lang, "SampleApp",
    "SampleApp", productVersion, directoryOfInstalledXliffFiles, "MyCompany/L10NSharpSample",
    "[email protected]", "SampleApp")
{
    // existing code to run the application
}

To use L10NSharp.Windows.Forms in your Windows forms application, you can call the Create method on LocalizationManagerWinforms instead, passing the location of the translation memory XLIFF files and the other information as above. Note that the Create for Windows forms applications can optionally include an additional icon argument:

using (var lm = LocalizationManager.Create(lang, "SampleApp",
    "SampleApp", productVersion, directoryOfInstalledXliffFiles, "MyCompany/L10NSharpSample",
    icon, "[email protected]", "SampleApp")
{
    // existing code to run the application
}

One of two conventions must be used to name xlf files (only the ones for requested languages are loaded into memory, so we need the file names to tell us which ones to load). By default, directoryOfInstalledFiles contains files named Whatever.lang.xlf; if LocalizationManager.UseLanguageCodeFolders is true, then they are in folders whose names are the language tags. These names must match the target-language declared in the XLF for lazy loading to work properly. If the target-language is a multi-part tag (like es-ES), the lang component in the file path may be either the full tag (Whatever.es-ES.xlf or es-ES/Whatever.xlf) or its first component, the bare language tag (Whatever.es.xlf or es/Whatever.xlf).

Selecting a Language

If an exact match for the requested language is not available, L10NSharp will try to find the best available language. For example, if the client requests es but only Whatever.es-ES.xlf is available, Whatever.es-ES.xlf will be loaded automatically, and vice versa.

In L10NSharp.Windows.Forms, if the client requests es and both Whatever.es-ES.xlf and Whatever.es-MX.xlf are available, or if no Whatever.es[-details].xlf is available, a Windows forms dialog will inform the user that the selected language is not available and prompt the user to select from the available languages.

Thread safety

In general, L10NSharp is not written with thread safety in mind; callers should ensure that only one thread at a time enters L10NSharp methods. There is one exception: we have attempted to make the various varieties of GetString thread-safe,.

L10NSharpExtender

To localize a Windows Forms form or control, simply add the L10NSharpExtender from L10NSharp.Windows.Forms. It will automatically collect all the localizable strings on your form or control and its children.

Upgrading to a newer version

The migration guide describes the necessary changes when upgrading to a higher major version.

Building

Just download the repository and build the solution (L10NSharp.sln).

The command line build command would look something like this:

dotnet build

Running Unit Tests

We use NUnit to run our unit tests. NUnit is downloaded via NuGet. There may be a few tests that do not run, but all tests that run should pass.

The tests can be run from the command line like this:

dotnet test

It is also possible to run the tests from inside Visual Studio or Rider.

Testing in client projects (as applicable):

• Set an enviroment variable LOCAL_NUGET_REPO with the path to a folder on your computer (or local network) to publish locally-built packages
• See these instructions to enable local package sources
• build /t:pack will pack nuget packages and publish them to LOCAL_NUGET_REPO

Further instructions at https://github.com/sillsdev/libpalaso/wiki/Developing-with-locally-modified-nuget-packages