Skip to content

Latest commit

 

History

History
161 lines (110 loc) · 6.85 KB

README.md

File metadata and controls

161 lines (110 loc) · 6.85 KB
Raw

Crowdin .NET MAUI SDK

The Crowdin .NET MAUI SDK is a fork of the Crowdin Xamarin Forms SDK delivers all new translations from Crowdin project to the application immediately. So there is no need to update the application via Store to get the new version with the localization.

Features

  • Load remote strings from Crowdin Over-The-Air Content Delivery Network
  • Built-in translations caching mechanism (enabled by default, can be disabled)
  • Network usage configuration (All, only Wi-Fi or Cellular, Forbidden)
  • Load static strings from the bundled RESX files (usable as fallback before the CDN strings loaded)

Requirements

  • .NET Standard 2.1 support
  • Xamarin Forms 5.0 or newer

Installation

Install via NuGet:

// Package Manager
Install-Package Crowdin.Xamarin.Forms -Version 0.1.0

// .Net CLI
dotnet add package Crowdin.Xamarin.Forms --version 0.1.0

// Package Reference
<PackageReference Include="Crowdin.Xamarin.Forms" Version="0.1.0" />

// Paket CLI
paket add Crowdin.Xamarin.Forms --version 0.1.0

Quick start

For applications using the XML resource localization files (RESX)

  1. Add Crowdin Distribution Hash before any modules initialization:

    DynamicResourcesLoader.GlobalOptions.DistributionHash = "{your_distribution_hash}";

  2. Load static strings from app resource files to use as fallback:

    DynamicResourcesLoader.LoadStaticStrings(Translations.ResourceManager, Current.Resources);

    The first argument is the source - ResourceManager of the generated class from resources group (Translations.resx and descendants). The second argument is the destination - ResourceDictionary where to place loaded strings:

    • Global: in Application.Current.Resources
    • Per-view: in ContentPage.Resources

  3. Load strings from Crowdin Distributions CDN:

    string langCode = DynamicResourcesLoader.CurrentCulture.TwoLetterISOLanguageName;
DynamicResourcesLoader.LoadCrowdinStrings($"Translations.{langCode}.resx", Current.Resources);

    The property CurrentCulture provides end-user OS locale by default. It can be overridden by the developer if needed.

    The method LoadCrowdinStrings is async and can be awaited if needed.

    In this example, the method is not “awaited” not to block the rendering of the user’s interface.

Configuration

The SDK provides developers two ways for resources loading configuration: global and per-request:

var options = new CrowdinOptions
{
    DistributionHash = "<your_distribution_hash>",
    NetworkPolicy = NetworkPolicy.OnlyWiFi,
    UseCache = true,
    FileName = "Translations.resx"
};

  • NetworkPolicy - for network restrictions

    • All - all network types allowed
    • OnlyWiFi or OnlyCellular - only needed type allowed
    • Forbidden

  • UseCache - turn on or off built-in translations caching mechanism.

For global configuration override default GlobalOptions:

DynamicResourcesLoader.GlobalOptions = options;

For per-request configuration pass options as the first parameter:

DynamicResourcesLoader.LoadCrowdinStrings(options, Current.Resources);

In a last way don't forget to add options.FileName value. Please note - for this example we used the 'Translations.resx' file name. This name should correspond to the file name in Crowdin.

Translations caching algorithm

Every time the method DynamicResourcesLoader.LoadCrowdinStrings is executed the module checks the conditions for obtaining resources, updating or creating a cache (if it does not exist).

  1. If the cache is disabled and the network is unavailable - exit;
  2. If the cache is disabled, the network is available - resources are downloaded directly from the Crowdin CDN every time;
  3. If the cache is enabled, not yet created, the network is not available - exit;
  4. If the cache is enabled, not yet created, the network is available - resources are downloaded from the CDN and stored in the cache;
  5. If the cache is enabled, created - the cache is used first. The following is executed in the background thread:
    • Check network availability. If not - exit;
    • Update Crowdin manifest with updated translation date;
    • Comparison of creation dates of cached and remote resources. If they are the same - exit;
    • Update resources from Crowdin CDN;

P.S. The network is considered unavailable even if the user has forbidden its use in the loader settings.

Contribution

If you want to contribute please read the Contributing guidelines.

Seeking Assistance

If you find any problems or would like to suggest a feature, please feel free to file an issue on Github at Issues Page.

Need help working with Crowdin Xamarin Forms SDK or have any questions? Contact Customer Success Service.

License

The Crowdin Xamarin Forms SDK is licensed under the MIT License.
See the LICENSE file distributed with this work for additional
information regarding copyright ownership.

Except as contained in the LICENSE file, the name(s) of the above copyright
holders shall not be used in advertising or otherwise to promote the sale,
use or other dealings in this Software without prior written authorization.