josephmyers/l10nsharp

A .NET localization library for Windows Forms applications.

Overview

L10NSharp is a .NET localization library for Windows Forms applications. It collects strings which need localization when your application first runs and saves them in a translation memory file. It can also dynamically collect strings at runtime.

L10NSharp works with XLIFF files as translation memory.

How to use

L10NSharp is provided as a nuget package.

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

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. However, 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 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. It will automatically collect all the localizable strings on your form or control and its children.

Localizing Within the Application

L10NSharp provides a dialog for translating terms while running the application. The dialog can be launched by Alt-Shift-clicking a Windows Forms element.

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