From 824c7f1ef43ca3869eb18f24d2e44f38b11f7170 Mon Sep 17 00:00:00 2001 From: Ygg01 Date: Sun, 19 Nov 2023 01:45:48 +0100 Subject: [PATCH] V0.7.0 (#41) * Update changelogs * Update version numbers --- .../Linguini.Bundle.Test.csproj | 1 + Linguini.Bundle/Linguini.Bundle.csproj | 2 +- Linguini.Bundle/README.md | 41 +++++++++++- .../Linguini.Serialization.csproj | 2 +- Linguini.Shared/Linguini.Shared.csproj | 2 +- Linguini.Syntax/Linguini.Syntax.csproj | 2 +- README.md | 10 ++- changelog.md | 65 +++++++++++++++++++ 8 files changed, 119 insertions(+), 6 deletions(-) diff --git a/Linguini.Bundle.Test/Linguini.Bundle.Test.csproj b/Linguini.Bundle.Test/Linguini.Bundle.Test.csproj index 8d5e92a..1e2b8d8 100644 --- a/Linguini.Bundle.Test/Linguini.Bundle.Test.csproj +++ b/Linguini.Bundle.Test/Linguini.Bundle.Test.csproj @@ -5,6 +5,7 @@ enable netstandard2.1;net6.0 Library + 0.7.0 diff --git a/Linguini.Bundle/Linguini.Bundle.csproj b/Linguini.Bundle/Linguini.Bundle.csproj index 192c8db..e9222a9 100644 --- a/Linguini.Bundle/Linguini.Bundle.csproj +++ b/Linguini.Bundle/Linguini.Bundle.csproj @@ -18,7 +18,7 @@ It provides easy to use and extend system for describing translations. https://github.com/Ygg01/Linguini git - 0.6.1 + 0.7.0 netstandard2.1;net6.0 linguini.jpg README.md diff --git a/Linguini.Bundle/README.md b/Linguini.Bundle/README.md index 49c3e92..83717e8 100644 --- a/Linguini.Bundle/README.md +++ b/Linguini.Bundle/README.md @@ -1,2 +1,41 @@ Linguini Bundle ---- \ No newline at end of file +=== + +Construct a bundle +--- + +Linguini Bundle is the main API for accessing Fluent templates. It takes input, locale and useful localization +functions. + +First way is to construct is using a fluent/chainable API to create a bundle. + +```csharp +var bundle = LinguiniBuilder.Builder() + .CultureInfo(new CultureInfo("en")) + .AddResource("loc = Localization value") + .AddFunction("idfunc", (args, _) => args[0]); + .UncheckedBuild(); +``` + +Here we set `loc` value for English language and pass an `idfunc` that just returns the first argument passed. +By using `UncheckedBuild()` we get a guaranteed bundle, but any error will become an Exception. If we used `Build()` +the result would be a tuple of type `(FluentBundle, List)`. + +Another way to construct a bundle is to provide a `FluentBundleOption`. + +```csharp +var defaultBundle = new FluentBundleOption +{ + CultureInfo = new CultureInfo("en"), + Functions = + { + ["idfunc"] = (args, _) => args[0] + }, + // Note no resource added! +}; +var bundle = FluentBundle.FromBundleOptions(defaultBundleOpt); +bundle.AddResource("loc = Localization value", out _); +``` + +Both methods are nearly the same, but `FluentBundleOption` doesn't provide Resources. +They can be added vie `BundleOption`s `AddResource`. \ No newline at end of file diff --git a/Linguini.Serialization/Linguini.Serialization.csproj b/Linguini.Serialization/Linguini.Serialization.csproj index 78c08a5..5744fa7 100644 --- a/Linguini.Serialization/Linguini.Serialization.csproj +++ b/Linguini.Serialization/Linguini.Serialization.csproj @@ -1,7 +1,7 @@ - 0.6.0 + 0.7.0 net6.0 linguini.jpg README.md diff --git a/Linguini.Shared/Linguini.Shared.csproj b/Linguini.Shared/Linguini.Shared.csproj index 60970e4..2b86186 100644 --- a/Linguini.Shared/Linguini.Shared.csproj +++ b/Linguini.Shared/Linguini.Shared.csproj @@ -9,7 +9,7 @@ MIT OR Apache-2.0 fluent, i18n, internationalization, l10n, l20n, globalization, translation false - 0.6.0 + 0.7.0 netstandard2.1;net6.0 linguini.jpg README.md diff --git a/Linguini.Syntax/Linguini.Syntax.csproj b/Linguini.Syntax/Linguini.Syntax.csproj index be17ecf..89a02c9 100644 --- a/Linguini.Syntax/Linguini.Syntax.csproj +++ b/Linguini.Syntax/Linguini.Syntax.csproj @@ -12,7 +12,7 @@ https://github.com/Ygg01/Linguini git netstandard2.1;net6.0 - 0.6.1 + 0.7.0 README.md linguini.jpg diff --git a/README.md b/README.md index f03922a..686482a 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,15 @@ To install the [Fluent Bundle](https://www.nuget.org/packages/Linguini.Bundle/) ```dotnet add package Linguini.Bundle``` -You can also follow other NuGet installation instructions. +You can also follow other NuGet installation instructions. E.g. : + +```paket add Linguini.Bundle``` + +Or copy this code to your [PackageReference](https://learn.microsoft.com/en-gb/nuget/consume-packages/package-references-in-project-files) + +```xml + +``` # How to use it? diff --git a/changelog.md b/changelog.md index 7b5616b..476d276 100644 --- a/changelog.md +++ b/changelog.md @@ -106,3 +106,68 @@ version 0.6.0 version 0.6.1 ======== - Fixes errors when reading an empty line on Windows (reported by @JosefNemec) + +version 0.7.0 +======== +- Experimental features when `UseExperimental` flag is true: + - Dynamic Reference - ability to reference terms/message using `$$term_ref`. + After defining it in file like so: + ```fluent + # example.ftl + cat = {$number -> + *[one] Cat + [other] Cats + } + dog = {$number -> + *[one] Dog + [other] Dogs + } + attack-log = { $$attacker(number: $atk_num) } attacked {$$defender(number: $def_num)}. + ``` + It can be called like following: + ```csharp + var args = new Dictionary + { + ["attacker"] = (FluentReference)"cat", + ["defender"] = (FluentReference)"dog", + }; + Assert.True(bundle.TryGetMessage("attack-log", args, out _, out var message)); + Assert.AreEqual("Cat attacked Dog.", message); + ``` + - Dynamic Reference attributes - You can call an attribute of a dynamic reference. It will be resolved at runtime, so + make sure your term/message has the associated attribute. + Example: + ```fluent + # dyn_attr.ftl + -creature-elf = elf + .StartsWith = vowel + + you-see = You see { $$object.StartsWith -> + [vowel] an { $$object } + *[consonant] a { $$object } + }. + ``` + ```csharp + var args = new Dictionary + { + ["object"] = (FluentReference)"creature-elf", + }; + Assert.True(bundle.TryGetMessage("you-see", args, out _, out var message)); + Assert.AreEqual("You see an elf.", message); + ``` + + - Term passing - experimental feature allows users to override term arguments. + ```fluent + -ship = Ship + .gender = { $style -> + *[traditional] neuter + [chicago] feminine + } + ship-gender = { -ship.gender(style: $style) -> + *[masculine] He + [feminine] She + [neuter] It + } + ``` + Usually when style isn't passed, it would to default `-ship.gender()` i.e. `neuter`, which would set `ship-gender` selector to neuter i.e. `It`. + In above example if we set style variable to `chicago`, `-ship.gender()` it would evaluate `feminine`, so `ship-gender` would would evaluate to `She`.