Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/codingseb/localization

A suite to localize C# and WPF projects easily based on file format you choose.
https://github.com/codingseb/localization

csharp json language localization localize localizer markup translate translation wpf xaml yaml

Last synced: about 2 hours ago
JSON representation

A suite to localize C# and WPF projects easily based on file format you choose.

Awesome Lists containing this project

README 

        
# Localization 

A suit of libs to localize C# and WPF projects easily based on file format you choose.



__Replace the archived [TranslateMe](https://github.com/codingseb/TranslateMe) lib__



|Nuget|Version|

|---|---|

|CodingSeb.Localization|[![NuGet Status](http://img.shields.io/nuget/v/CodingSeb.Localization.svg?style=flat&max-age=86400)](https://www.nuget.org/packages/CodingSeb.Localization/)|

|CodingSeb.Localization.JsonFileLoader|[![NuGet Status](http://img.shields.io/nuget/v/CodingSeb.Localization.JsonFileLoader.svg?style=flat&max-age=86400)](https://www.nuget.org/packages/CodingSeb.Localization.JsonFileLoader/)|

|CodingSeb.Localization.YamlFileLoader|[![NuGet Status](http://img.shields.io/nuget/v/CodingSeb.Localization.YamlFileLoader.svg?style=flat&max-age=86400)](https://www.nuget.org/packages/CodingSeb.Localization.YamlFileLoader/)|

|CodingSeb.Localization.WPF|[![NuGet Status](http://img.shields.io/nuget/v/CodingSeb.Localization.WPF.svg?style=flat&max-age=86400)](https://www.nuget.org/packages/CodingSeb.Localization.WPF/)|

|CodingSebLocalization.Fody|[![NuGet Status](http://img.shields.io/nuget/v/CodingSebLocalization.Fody.svg?style=flat&max-age=86400)](https://www.nuget.org/packages/CodingSebLocalization.Fody/)|



## The differents parts of the project

The library is composed of 4 parts :  



  1. The part "Core" : Nuget "CodingSeb.Localization" Contains the dictionnary of all translations for a "TextId" in C#.  

	

  2. A part "FileLoader" : Allow to open a type of file that contains translations to load in the dictionnary of the "Core" part.  

  

  3. The part to translate (localize) XAML (WPF) "CodingSeb.Localization.WPF". Provide `Tr` and `MultiTr` markups and some converters to use in Bindings. It use the "Core" in backend.  

  

  4. The part to translate ViewModel (`INotifyPropertyChanged`). Provide `Localize` attribute to put on ViewModel properties that are localized



## Installation



### With Nuget



__For Simple C# projects__

```

PM> Install-Package CodingSeb.Localization.JsonFileLoader

```  

or

```

PM> Install-Package CodingSeb.Localization.YamlFileLoader

```  

or

```

PM> Install-Package CodingSeb.Localization

``` 

and implement your own [FileLoader](#implement-your-own-file-format).



__For WPF projects__  

Add this :

```

PM> Install-Package CodingSeb.Localization.WPF

```

and

```

PM> Install-Package CodingSebLocalization.Fody

```



## Use it in C# :



__To localize a text__



```csharp

using CodingSeb.Localization

/// ...



// To translate a text in the current language

// Loc.Tr("TextId");

Loc.Tr("SayHello");

// To show a default text if the text is not localized in the current language

// Loc.Tr("TextId", "DefaultText")

Loc.Tr("SayHello", "Not localized");

// To Translate a text in fixed language

// Loc.Tr("TextId","DefaultText" "LanguageId");

Loc.Tr("SayHello", null, "fr");



```



__To Change the current language__

```csharp

Loc.Instance.CurrentLanguage = "en";

Loc.Instance.CurrentLanguage = "fr";

Loc.Instance.CurrentLanguage = "es";

// ...

// To get availables languages

Collection languages = Loc.AvailableLanguages;

```



### Use it In XAML (WPF) :

(no xmlns needed Tr Markup is available as soon as CodingSeb.Localization.WPF is in project's references)



__Simple localization with the Markup `Tr`__

```xml



```



_In general use XML escape to escape special characters. For single quote use ```[apos]``` to escape. XML escape does'nt work in this case for inline Tr markup. Or use the following format :_



```xml



  

    

  



```



__To Translate with Bindings__



```xml



    

    

    

    

    



    

    

    

    

    



   



    

    

    

    

    

    



    

    

    

        

            

	        

                    

                    

		

            

        

    

    

    

        

            

                

                

            

        

    



```



__To concatenate some translations__

```xml



    

        

            

            

	    

        

    



    

    

    

```



*Remark : By default the translation made in the XAML are automatically updated when current language changed.*  

*In templates (`DataTemplate`, `ControlTemplate`) Bindings with TrConverters do not update when language change. Prefer to use `Tr` Markup with bindings in templates*



__To Change the current language from the xaml__



```xml



```



### Use it In ViewModel (Fody) :



You can use the Property attibute `Localize` to automatically generate the PropertyChanged event for the property when CurrentLanguageChanged.



```c#

public class LocalizedWithFodyClass : INotifyPropertyChanged

{

    [Localize]

    public string TestProperty => Loc.Tr("TestLabel");



    [Localize(nameof(TextIdInAttribute))]

    public string TextIdInAttribute { get; set; }



    // ...



    public event PropertyChangedEventHandler PropertyChanged;



    public void NotifyPropertyChanged(string propertyName)

    {

        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));

    }

}

```



The specific code is injected at compile time thanks to [Fody](https://github.com/Fody/Fody).

It is compatible with [PropertyChanged.Fody](https://github.com/Fody/PropertyChanged) or other similar fody addins like [ReactiveUI.Fody](https://github.com/kswoll/ReactiveUI.Fody). Just ensure that CodingSebLocalization is defined after in the `FodyWeavers.xml` file.



```xml



  

  

  

  

  	



```



## OK But... ...How I define my translations ?

### JsonFileLoader

With the default JsonFileLoader, Translations are defined in JSON files with the extension "*.loc.json".



Here an example :



```json

{

  "LanguageName": {

    "en": "English",

    "es": "Español",

    "fr": "Français"

  },

  "[Localization.Examples.MainWindow].lblCurrentLanguage[Label].Content": {

    "en": "Current language",

    "es": "Lenguaje actual",

    "fr": "Langue courrante"

  },

  "[Localization.Examples.MainWindow].lblHelloInCurrentLanguage[Label].Content": {

    "en": "Hello",

    "es": "Hola",

    "fr": "Bonjour"

  },

  "HelloInCurrentLanguage": {

    "en": "Hello in the current language",

    "es": "Hola en la lengua actual",

    "fr": "Bonjour dans la langue actuelle"

  },

  "[Localization.Examples.MainWindow].lblHelloInCurrentLanguage[Label].ToolTip": {

    "en": "In english",

    "es": "En español",

    "fr": "En français"

  }

}

```



It's also possible to create a hierarchy :



```json

{

    "AppName": {

        "MainMenu": {

          "FileMenuItem": {

            "Header": {

              "en": "_File",

              "fr": "_Fichier"

            },

            "NewMenuItem": {

              "Header": {

                "en": "_New",

                "fr": "_Nouveau"

              }

            },

            "OpenMenuItem": {

              "Header": {

                "en": "_Open",

                "fr": "_Ouvrir"

              }

            },

            "..."

        }

    }

}

```



To use like this : 



```csharp

Loc.Tr("AppName.MainMenu.FileMenuItem.Header");

Loc.Tr("AppName.MainMenu.FileMenuItem.NewMenuItem.Header");

Loc.Tr("AppName.MainMenu.FileMenuItem.OpenMenuItem.Header");

```



or like this in XAML :

```xml



    

        

        

        



``` 



And to load these files :



```csharp

using CodingSeb.Localization.Loaders;

// You need first to add the specific fileLoader 

LocalizationLoader.Instance.FileLanguageLoaders.Add(new JsonFileLoader());



// ...



// And then you can add your localization file

LocalizationLoader.Instance.AddFile(@"PathToTheFile\Example1.loc.json");

// or load directly a directory with multiple "*.loc.json" files.

LocalizationLoader.Instance.AddDirectory(@"PathToTheDirectory");

```



So you can change the text of your app or translate it in a new language without recompile all your application.



```csharp

// or you can also load a translation by code (textId, languageId, value)

LocalizationLoader.Instance.AddTranslation("SayHello", "en", "Hello" );

LocalizationLoader.Instance.AddTranslation("SayHello", "es", "Hola" );

LocalizationLoader.Instance.AddTranslation("SayHello", "fr", "Bonjour" );

```



### YamlFileLoader

For Yaml format of localization files "*.loc.yaml" it's working the same way as the Json



### Implement your own file format

If you want to support an other format than json or yaml, you can create your custom FileLanguageLoader.

Simply create a class that implement the ILocalizationFileLoader interface and add an instance of your class in the LocalizationLoader :



```csharp

LocalizationLoader.Instance.FileLanguageLoaders.Add(new YouCustomClassImplementingILocalizationFileLoader());

```



## Find Missing Translations

You can activate an option to be notify when a translation is missing. 



```csharp

// with all TextId and LanguageId that are missing when you trying to translate them.

Loc.LogOutMissingTranslations = true;

Loc.MissingTranslationFound += Loc_MissingTranslationFound;

```



If you want to log it automatically in a json file you can also use the class `JsonMissingTranslationsLogger` in the "CodingSeb.Localization.JsonFileLoader" package.



```csharp

JsonMissingTranslationsLogger.EnableLog();

```



## Tr and WPF Styles

The `Tr`markup is usable in Styles. but if a Trigger is used the `Tr` markup only works if used in static mode : `