Rephrase documentation

Author: Yusyuriv

README.md

@@ -1,8 +1,8 @@
 # Flow Launcher Localization Toolkit
 
-Localization toolkit for Flow Launcher and its plugins
+Localization toolkit for Flow Launcher and its plugins.
 
 Useful links:
 
 * [Flow Launcher localization toolkit guide](https://www.flowlauncher.com/docs/#/localization-toolkit)
-* [.Net plugin development guide](https://www.flowlauncher.com/docs/#/develop-dotnet-plugins)
+* [.NET plugin development guide](https://www.flowlauncher.com/docs/#/develop-dotnet-plugins)

localization-toolkit.md

@@ -1,90 +1,118 @@
-Localization toolkit is for Flow C# plugin developers to improve their localization experience.
+The Localization Toolkit helps Flow Launcher C# plugin developers make the localization process easier.
 
-## Initialization
+## Getting Started
 
-For C# Plugins, we need to install and reference [Flow.Launcher.Localization](www.nuget.org/packages/Flow.Launcher.Localization) by Nuget.
+For C# plugins, install and reference [Flow.Launcher.Localization](www.nuget.org/packages/Flow.Launcher.Localization) via NuGet.
 
-## Build properties
+## Build Properties
+
+These are properties you can configure in your `.csproj` file to customize the localization process. You can set them in the `<PropertyGroup>` section. For example, to set the `FLLUseDependencyInjection` property to `true`, add the following lines:
+
+```xml
+<PropertyGroup>
+    <FLLUseDependencyInjection>true</FLLUseDependencyInjection>
+</PropertyGroup>
+```
 
 ### `FLLUseDependencyInjection`
 
-Whether to use dependency injection to get `IPublicAPI` instance. Default by false.
-If set to `false`, the `Main` class that implements **[IPlugin](/API-Reference/Flow.Launcher.Plugin/IPlugin.md)** or **[IAsyncPlugin](/API-Reference/Flow.Launcher.Plugin/IAsyncPlugin.md)** must have a [PluginInitContext](/API-Reference/Flow.Launcher.Plugin/PluginInitContext.md) property which must be at least `internal static`.
+This flag specifies whether to use dependency injection to obtain an IPublicAPI instance. The default is `false`.
+- If set to `false`, the Main class (which must implement **[IPlugin](/API-Reference/Flow.Launcher.Plugin/IPlugin.md)** or **[IAsyncPlugin](/API-Reference/Flow.Launcher.Plugin/IAsyncPlugin.md)**)
+  must have a [PluginInitContext](/API-Reference/Flow.Launcher.Plugin/PluginInitContext.md) property that is at least `internal static`.
+- If set to `true`, you can access the `IPublicAPI` instance via `PublicApi.Instance` using dependency injection, and the Main class does not need to include a [PluginInitContext](/API-Reference/Flow.Launcher.Plugin/PluginInitContext.md) property.
+  (Note: This approach is not recommended for plugin projects at the moment since it limits compatibility to Flow Launcher 1.20.0 or later.)
 
-If set to `true`, we can access `IPublicAPI` instance from `PublicApi.Instance` in the project by dependency injection.
-And the `Main` class does not need to have a [PluginInitContext](/API-Reference/Flow.Launcher.Plugin/PluginInitContext.md) property.
-(Not recommended for plugin projects because this will make plugins only compatible with Flow 1.20.0 or higher)
 ## Usage
 
-### Main class
+### Main Class
 
-`Main` class must implement [IPluginI18n](/API-Reference/Flow.Launcher.Plugin/IPluginI18n.md).
+The Main class must implement [IPluginI18n](/API-Reference/Flow.Launcher.Plugin/IPluginI18n.md).
 
-If `FLLUseDependencyInjection` is set to `false`, `Main` class must have a [PluginInitContext](/API-Reference/Flow.Launcher.Plugin/PluginInitContext.md) property like:
+If `FLLUseDependencyInjection` is `false`, include a [PluginInitContext](/API-Reference/Flow.Launcher.Plugin/PluginInitContext.md) property, for example:
 
-```
-public class Main : IPlugin, IPluginI18n // Must implement IPluginI18n
+```csharp
+ // Must implement IPluginI18n
+public class Main : IPlugin, IPluginI18n
 {
-    internal static PluginInitContext Context { get; private set; } = null!; // At least internal static property
-    private static IPublicAPI API => Context.API;
-
-    ...
+    // Must be at least internal static
+    internal static PluginInitContext Context { get; private set; } = null!;
 }
 ```
 
-### Localized strings
+### Localized Strings
+
+You can simplify your code by replacing calls like:
+```csharp
+Context.API.GetTranslation("flowlauncher_plugin_localization_demo_plugin_name")
+```
+with:
+```csharp
+Localize.flowlauncher_plugin_localization_demo_plugin_name()
+```
 
-With this toolkit, we can replace `Context.API.GetTranslation("flowlauncher_plugin_localization_demo_plugin_name")` with `Localize.flowlauncher_plugin_localization_demo_plugin_name()`.
+If your localization string uses variables, it becomes even simpler! From this:
+```csharp
+string.Format(Context.API.GetTranslation("flowlauncher_plugin_localization_demo_value_with_keys"), firstName, lastName);
+```
+To this:
+```csharp
+Localize.flowlauncher_plugin_localization_demo_value_with_keys(firstName, lastName);
+```
 
-And we can also replace `string.Format(Context.API.GetTranslation("flowlauncher_plugin_localization_demo_plugin_used"), string.Empty, null, string.Empty)` with `Localize.flowlauncher_plugin_localization_demo_plugin_used(string.Empty, null, string.Empty)`.
+### Localized Enums
 
-### Localized enums
+For enum types (e.g., DemoEnum) that need localization in UI controls such as combo boxes, use the `EnumLocalize` attribute to enable localization. For each enum field:
+- Use `EnumLocalizeKey` to provide a custom localization key.
+- Use `EnumLocalizeValue` to provide a constant localization string.
 
-If you have enum types like `DemoEnum` that needs localization in displaying them on a combo box control. You can add `EnumLocalize` attribute to enable localization support.
-For all fields in this `EnumType`, if you want to specific one localization key for this field, you can use `EnumLocalizeKey` attribute; or if you want to specific one constant value for this field, you can use `EnumLocalizeValue` attribute.
+Example:
 
-```
+```csharp
 [EnumLocalize] // Enable localization support
 public enum DemoEnum
 {
-    [EnumLocalizeKey("localize_key_1")] // Specific localization key
+    // Specific localization key
+    [EnumLocalizeKey("localize_key_1")]
     Value1,
 
-    [EnumLocalizeValue("localize_value_2")] // Specific localization value
+    // Specific localization value
+    [EnumLocalizeValue("This is my enum value localization")]
     Value2,
 
-    [EnumLocalizeKey("localize_key_3")] // If key and value both exist, will prefer localization key
-    [EnumLocalizeValue("localize_value_3")]
+    // Key takes precedence if both are present
+    [EnumLocalizeKey("localize_key_3")]
+    [EnumLocalizeValue("Localization Value")]
     Value3,
 
-    [EnumLocalizeKey(nameof(Localize.flowlauncher_plugin_localization_demo_plugin_description))] // Use Localize class
+    // Using the Localize class. This way, you can't misspell localization keys, and if you rename
+    // them in your .xaml file, you won't forget to rename them here as well because the build will fail.
+    [EnumLocalizeKey(nameof(Localize.flowlauncher_plugin_localization_demo_plugin_description))]
     Value4,
 }
 ```
 
-Then you can get `DemoEnumData` class.
+Then, use the generated DemoEnumData class within your view model to bind to a combo box:
 
-In view model class which needs to display it on a combo box control, you can add two fields for binding `ItemSource` and `SelectedValue` like:
+```csharp
+// ComboBox ItemSource
+public List<DemoEnumData> AllDemoEnums { get; } = DemoEnumData.GetValues();
 
+// ComboBox SelectedValue
+public DemoEnum SelectedDemoEnum { get; set; }
 ```
-public List<DemoEnumData> AllDemoEnums { get; } = DemoEnumData.GetValues(); // ItemSource of ComboBox
 
-public DemoEnum SelectedDemoEnum { get; set; } // SelectedValue of ComboBox
-```
+In your XAML, bind as follows:
 
-```
+```xml
 <ComboBox
     DisplayMemberPath="Display"
     ItemsSource="{Binding AllDemoEnums}"
     SelectedValue="{Binding SelectedDemoEnum}"
     SelectedValuePath="Value" />
 ```
 
-If you want to update localization strings when culture info changes, you can call this function to update.
+To update localization strings when the language changes, you can call:
 
-```
-private void UpdateEnumDropdownLocalizations()
-{
-    DemoEnumData.UpdateLabels(AllDemoEnums);
-}
+```csharp
+DemoEnumData.UpdateLabels(AllDemoEnums);
 ```