Skip to content

Simple and cross platform internationalization for Xamarin and .NET. The localization is similar to Ruby On Rails - http://guides.rubyonrails.org/i18n.html (Beta)

License

Notifications You must be signed in to change notification settings

pocheshire/friendly-locale

 
 

Repository files navigation

Friendly Locale(Beta)

website

Simple and cross platform internationalization for Xamarin and .NET. The localization is similar to Ruby On Rails.

Build Status

Features:

  • Cross platform;
  • No dependencies;
  • Yaml instead of Resx;
  • Support Remote Resources;
  • Support Assets Resources;
  • Support Embedded Resources.

Sample

Sample project screen

Yaml as the foundation

Yaml website

The library use YAML because it is easier for humans to read and write than other common data formats like XML or JSON.

The differences between yaml and resx

Unfriendly format on resx

<data name="FirstViewModel.Title" xml:space="preserve">
    <value>FirstViewModel Title</value>
</data>
<data name="FirstViewModel.Description" xml:space="preserve">
    <value>FirstViewModel Description</value>
</data>
<data name="FirstViewModel.SubmitTitle" xml:space="preserve">
    <value>SubmitTitle</value>
</data>
<data name="FirstViewModel.EmptyData.Title" xml:space="preserve">
    <value>FirstViewModel EmptyData Title</value>
</data>
<data name="FirstViewModel.EmptyData.Description" xml:space="preserve">
    <value>FirstViewModel EmptyData Description</value>
</data>
<data name="SecondViewModel.Title" xml:space="preserve">
    <value>SecondViewModel Title</value>
</data>
<data name="SecondViewModel.SubmitTitle" xml:space="preserve">
    <value>SubmitTitle</value>
</data>

This is easily written on the Yaml markup:

buttons: &BUTTONS
  SubmitTitle: "SubmitTitle"

FirstViewModel:
  Title: "FirstViewModel Title"
  Description: "FirstViewModel Description"
  <<: *BUTTONS
  EmptyData:
    Title: "FirstViewModel EmptyData Title"
    Description: "FirstViewModel EmptyData Description"
    
SecondViewModel:
  Title: "SecondViewModel Title"
  <<: *BUTTONS

Install

https://www.nuget.org/packages/FriendlyLocale

PM> Install-Package FriendlyLocale

To use, simply reference the nuget package in each of your platform projects.

  • You can not add to each platform if you use embedded resources from the assembly.

Setup

Embedded resources from Assembly

AssemblyContentConfig.cs

var assembly = this.GetType().GetTypeInfo().Assembly;
var assemblyConfig = new AssemblyContentConfig(assembly)
{
    ResourceFolder = "Locales"
};

FriendlyLocale.I18N.Initialize(assemblyConfig);

Assets resources

AssetsContentConfig.cs

var assetsConfig = new AssetsContentConfig
{
    ResourceFolder = "Locales"
};

FriendlyLocale.I18N.Initialize(assetsConfig);

Remote resources

RemoteContentConfig.cs

Offline mode is supported

OfflineContentConfig.cs

  • Assets file
var offlineConfig = OfflineContentConfig.FromAssets("en.yaml", "Locales");
  • Embedded resource
var assembly = this.GetType().GetTypeInfo().Assembly;
var offlineConfig = OfflineContentConfig.FromAssembly(assembly, "ru.yaml", "Locales");

And the final step of initialization

var remoteConfig = new RemoteContentConfig
{
    Locales =
    {
        {"ru", "https://any.com/ru.yaml"},
        {"en", "https://any.com/en.yaml"}
    }
};
// offlineConfig - optional
FriendlyLocale.I18N.Initialize(remoteConfig, offlineConfig);

Using

Change Locale

// basic
await FriendlyLocale.I18N.ChangeLocale("en");

// offline mode for remote
await FriendlyLocale.I18N.ChangeLocale("offline");

Change Locale with download progress

var progress = new Progress<float>();
progress.ProgressChanged += (s, e) =>
{
    Console.WriteLine($"Download progress: {e}");
};
await this.I18N.ChangeLocale("en", progress);

Translate

var value = FriendlyLocale.I18N.Instance.Translate("key");

// en.yaml:
//   key:
//     innerkey: "InnerValue"
//     more:
//       morekey: "MoreValue"
var innerValue = FriendlyLocale.I18N.Instance.Translate("key.innerkey"); // InnerValue
var moreValue = FriendlyLocale.I18N.Instance.Translate("key.more.morekey"); // MoreValue

Localization file syntax

More inforamtion on http://www.yaml.org/spec/1.2/spec.html.

Simple using

FirstViewModel:
  Title: "Title"
  Empty:
    Title: "Not found"
    TitleButton: "Refresh data"

Get the value:

var title = I18N.Instance.Translate("FirstViewModel.Title");
var emptyTitle = I18N.Instance.Translate("FirstViewModel.Empty.Title");
var emptyTitleButton = I18N.Instance.Translate("FirstViewModel.Empty.TitleButton");

Using Multiline

FirstViewModel:
  MultiDescription1: |
    MultiDescription: Lorem Ipsum is simply dummy text of the printing and typesetting industry. 
    Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, 
  MultiDescription2: >
    Lorem Ipsum is simply dummy text of the printing and typesetting industry. 
    Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, 

> - Folded style removes single newlines within the string (but adds one at the end, and converts double newlines to singles).

| - Literal style turns every newline within the string into a literal newline, and adds one at the end.

Get the value:

var multiDescription1 = I18N.Instance.Translate("FirstViewModel.MultiDescription1");
var multiDescription2 = I18N.Instance.Translate("FirstViewModel.MultiDescription2");

Using Anchor - Alias

More inforamtion on https://learnxinyminutes.com/docs/yaml/.

alias: &ALIAS
  AliasDescription: "AliasDescription"
  
FirstViewModel:
  <<: *ALIAS

Get the value:

var aliasDescription = I18N.Instance.Translate("FirstViewModel.AliasDescription");

Roadmap

  • Add more tests;
  • Automatic change of values when changing localization;
  • Detailed code documentation.

About

Simple and cross platform internationalization for Xamarin and .NET. The localization is similar to Ruby On Rails - http://guides.rubyonrails.org/i18n.html (Beta)

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • C# 100.0%