[NEW-FEATURE] Implement use of resx for translation of PLC strings (#144)

* Create draft PR for #143

* [ixr] multiple adjustments to allow use of resx in twin projects
- [breaking] the ixc now creates csproj files with names that comply with identifier requirements (due to resx generator using the project name by default to generate resources) files with name using '-' will now use instead '_' (e.g. ax-blazor-example.csproj will be ax_blazor_example.csproj).
- ixr when no parameter provided will use current directory (apax) as the source (-x) and will retrieve the information about the output project from 'AXSharp.config.json' file. Providing output paramters will not alter the content of config file.
- resource identifier creator was moved to AXSharp.Connector to share the same logic when creating and searching indentifiers.
- resource injection for the translator [wip]

* comiler now adds reference to assembly resources for plc string translation
- we create new class `PlcTranslator` for each assembly (twin project) that provides `Resources.PlcStringResources` as default resource for given assembly. All members that can contain data eligible for localizaions refernce the singleton of this 'PlcTranslator'.

* added missing expected files for testing to sc

* updates docfx to 2.64.0

* namespace removed from usings due to a problem in documentation generation

* adds infomation about parameterless execution of ixr

* multiple addition due localization
- adds translator to generated added properties of string type
- simplifies translator
- refactoring localization helper to AXSharp.Connector.Localization namespace

* adds documenation how-to localization

---------

Co-authored-by: PTKu <PTKu@users.noreply.github.com>

Author: PTKu

.config/dotnet-tools.json

@@ -9,7 +9,7 @@
       ]
     },
     "docfx": {
-      "version": "2.63.0",
+      "version": "2.64.0",
       "commands": [
         "docfx"
       ]

build-docs.ps1

@@ -1,3 +1,2 @@
-# run build
-dotnet run --project cake/Build.csproj -- $args --do-docs true
-exit $LASTEXITCODE;
+.\build.ps1
+dotnet docfx .\docfx\docfx.json

docfx/articles/connectors/README.md

@@ -309,6 +309,48 @@ HumanReadable property is the concatenation of AttributeName properties in the t
 
 HumanReadable from `TurnLightsOff` is `App.Settings.Lights off`
 
+
+## Controller string localization
+
+### Localizable string
+
+Any string or part of a string that is enclosed between `<#` and `#>` will be marked for translation. This feature will work with types `STRING` and `WSTRING` and with the added attributes of `string` type.
+
+
+*Example of the added attribute of string type*
+~~~
+{#ix-set:AttributeName = "<#Integer From PLC#>"}
+{#ix-set:AttributeName = "(A1)<#Horizontal cylinder#>"}
+~~~
+
+*Examples of STRING and WSTRING variables with*
+~~~
+VAR
+    someString : STRING;
+    someWString : WSTRING;
+END_VAR
+
+someString := '<#This woule be localized#> and this would stay as it is';
+
+
+someWString := "<#This woule be localized#> and this would stay as it is";
+~~~
+
+Connectors implement features that allow localizing of the texts (controller defined and added attributes of string type). For the localization to work the twin assembly must be provided with a resource file (*.resx). Resource files can be generated using [ixr tool](~/articles/ixr/IXR.md). You will need to add the resource file to your **Twin project** and set the resource code generation to *public*.
+
+![](../../images/ixd/howto_addresource.gif)
+
+The twin project will use the resource `[twin_project_namespace].Resources.PlcStringResources` type as the default resource for the PLC string translations.
+
+If there is no localization resource defined the twin assembly will not translate the string but will provide the original raw string cleaned from localization tokens. 
+
+It is possible to override the default resource using [`SetLocalizationResource`](~/api/AXSharp.Connector.Localizations.Translator.yml) method. The method for a given twin assembly is accessible via `[twin_project_default_namespace].PlcTranslator.Instance`.
+
+Example
+~~~C#
+ix_plc.PlcTranslator.Instance.SetLocalizationResource(typeof(myproject.ResourcesOverride.OverridePlcStringResources));
+~~~
+
 See also
 
 [Dummy Connector](Dummy.md)

docfx/articles/ixr/IXR.md

@@ -22,6 +22,11 @@ where:
 
 Localizable string are exported only from string attributes and pragmas of attribute name.
 
+`ixr` can be run without parameters from within an AX project folder. In that case it will use the settings from `ixc` `AXSharp.config.json` and emit the resource file into `.g\Resource\PlcStringResource.resx` file of the ax twin project.
+
+>[!NOTE]
+>More about implementing resx file into your project see [here](~/articles/connectors/README.md#controller-string-localization).
+
 ## Localizable string
 
 Localizable string must start with `<#` and end with `#>` tags.  

docfx/images/ixd/howto_addresource.gif

@@ -19,7 +19,7 @@
     <ProjectReference Include="..\..\..\..\AXSharp.connectors\src\AXSharp.Connector\AXSharp.Connector.csproj" />
     <ProjectReference Include="..\..\..\src\AXSharp.Presentation.Blazor.Controls\AXSharp.Presentation.Blazor.Controls.csproj" />
     <ProjectReference Include="..\..\..\src\AXSharp.Presentation.Blazor\AXSharp.Presentation.Blazor.csproj" />
-    <ProjectReference Include="..\ax-blazor-example\ix\ax-blazor-example.csproj" />
+    <ProjectReference Include="..\ax-blazor-example\ix\ax_blazor_example.csproj" />
 
   </ItemGroup>
 

src/AXSharp.blazor/tests/sandbox/ComponentsExamples/ComponentsExamples.csproj

@@ -1,32 +1,33 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 	<PropertyGroup>
-		<TargetFrameworks>net6.0;net7.0</TargetFrameworks>
+		<TargetFramework>net6.0</TargetFramework>
 		<ImplicitUsings>enable</ImplicitUsings>
 		<Nullable>enable</Nullable>
 	</PropertyGroup>
+
 	<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|net6.0|AnyCPU'">
-	  <NoWarn>1701;1702;1998</NoWarn>
+		<NoWarn>1701;1702;1998</NoWarn>
 	</PropertyGroup>
 	<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Release|net6.0|AnyCPU'">
-	  <NoWarn>1701;1702;1998</NoWarn>
+		<NoWarn>1701;1702;1998</NoWarn>
 	</PropertyGroup>
 	<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|net7.0|AnyCPU'">
-	  <NoWarn>1701;1702;1998</NoWarn>
+		<NoWarn>1701;1702;1998</NoWarn>
 	</PropertyGroup>
 	<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Release|net7.0|AnyCPU'">
-	  <NoWarn>1701;1702;1998</NoWarn>
+		<NoWarn>1701;1702;1998</NoWarn>
 	</PropertyGroup>
 
 	<ItemGroup>
-	  <ProjectReference Include="..\..\..\..\..\AXSharp.abstractions\src\AXSharp.Abstractions\AXSharp.Abstractions.csproj" />
-	  <ProjectReference Include="..\..\..\..\..\AXSharp.connectors\src\AXSharp.Connector\AXSharp.Connector.csproj" />
+		<ProjectReference Include="..\..\..\..\..\AXSharp.abstractions\src\AXSharp.Abstractions\AXSharp.Abstractions.csproj" />
+		<ProjectReference Include="..\..\..\..\..\AXSharp.connectors\src\AXSharp.Connector\AXSharp.Connector.csproj" />
 	</ItemGroup>
 
 	<ItemGroup>
 		<Compile Include=".g\**" />
 	</ItemGroup>
 
-	
+
 	<ItemGroup>
 		<Folder Include=".g\" />
 	</ItemGroup>

src/AXSharp.blazor/tests/sandbox/ax-blazor-example/ix/ax-blazor-example.csproj renamed to src/AXSharp.blazor/tests/sandbox/ax-blazor-example/ix/ax_blazor_example.csproj

@@ -23,5 +23,7 @@ public interface ITargetProject
     /// </summary>
     void ProvisionProjectStructure();
 
+    void GenerateResources();
+
     IEnumerable<IReference> LoadReferences();
 }

src/AXSharp.compiler/src/AXSharp.Compiler.Abstractions/TargetProject/ITargetProject.cs

@@ -130,7 +130,7 @@ public void Generate()
 
         TargetProject.ProvisionProjectStructure();
         GenerateMetadata(compilation);
-
+        TargetProject.GenerateResources();
         Log.Logger.Information($"Compilation of project '{AxProject.SrcFolder}' done.");
     }
 

src/AXSharp.compiler/src/AXSharp.Compiler/AXSharpProject.cs

@@ -49,7 +49,8 @@ public CsProject(AXSharpProject AXSharpProject)
     private static string MakeValidFileName(string name)
     {
         var fileName = name;
-        foreach (var c in Path.GetInvalidFileNameChars()) fileName = fileName.Replace(c, '_');
+        //foreach (var c in Path.GetInvalidFileNameChars()) fileName = fileName.Replace(c, '_');
+        fileName = MakeValidIdentifier(fileName);
 
         fileName = fileName.Replace('@', '_');
 
@@ -132,6 +133,39 @@ public void ProvisionProjectStructure()
         EnsureCsProjFile();
     }
 
+    public void GenerateResources()
+    { 
+        var a =  @$"
+using System.Reflection;
+using AXSharp.Connector.Localizations;
+
+namespace {this.ProjectRootNamespace}
+{{
+    public sealed class PlcTranslator : Translator
+    {{
+        private static readonly PlcTranslator instance = new PlcTranslator();
+
+        public static PlcTranslator Instance
+        {{
+            get
+            {{
+                return instance;
+            }}
+        }}
+
+        private PlcTranslator() 
+        {{
+            var defaultResourceType = Assembly.GetAssembly(typeof({this.ProjectRootNamespace}.PlcTranslator))
+                .GetType(""{this.ProjectRootNamespace}.Resources.PlcStringResources"");
+            this.SetLocalizationResource(defaultResourceType);
+        }}
+    }}
+}}";
+
+        using var swr = new StreamWriter(Path.Combine(this.AxSharpProject.OutputFolder, ".g", "PlcResources.g.cs"));
+        swr.Write(a);
+    }
+
 
     /// <inheritdoc />
     public string GetMetaDataFolder => Path.Combine(AxSharpProject.OutputFolder, ".meta");

src/AXSharp.compiler/src/AXSharp.Cs.Compiler/CsProject.cs

@@ -5,6 +5,7 @@
 // https://github.com/ix-ax/axsharp/blob/dev/LICENSE
 // Third party licenses: https://github.com/ix-ax/axsharp/blob/master/notices.md
 
+using System.Security.Cryptography.X509Certificates;
 using System.Text;
 using AX.ST.Semantic;
 using AX.ST.Semantic.Model.Declarations;
@@ -49,6 +50,8 @@ public void CreateFile(IFileSyntax fileSyntax, IxNodeVisitor visitor)
         AddToSource("using AXSharp.Connector;");
         AddToSource("using AXSharp.Connector.ValueTypes;");
         AddToSource("using System.Collections.Generic;");
+        AddToSource("using AXSharp.Connector.Localizations;");
+
         fileSyntax.Declarations.ToList().ForEach(p => p.Visit(visitor, this));
     }
 
@@ -280,10 +283,11 @@ private void CreateITwinObjectImplementation()
             $"public {typeof(ITwinObject).n()} GetParent() {{ return this.@Parent; }}" +
             "public string Symbol { get; protected set; }" +
             "private string _attributeName;" +
-            "public System.String AttributeName { get {return AXSharp.Localizations.LocalizationHelper.CleanUpLocalizationTokens(_attributeName); } set { _attributeName = value; } }" +
+            "public System.String AttributeName {  get => string.IsNullOrEmpty(_attributeName) ? SymbolTail : this.Translate(_attributeName).Interpolate(this); set => _attributeName = value; }" +
             "public string HumanReadable { get; set; }" +
             "protected System.String @SymbolTail { get; set;}" +
-            $"protected {typeof(ITwinObject).n()} @Parent {{ get; set; }}"
+            $"protected {typeof(ITwinObject).n()} @Parent {{ get; set; }}"+
+            $"public AXSharp.Connector.Localizations.Translator Interpreter => {Project.TargetProject.ProjectRootNamespace}.PlcTranslator.Instance;"
         );
     }
 

src/AXSharp.compiler/src/AXSharp.Cs.Compiler/Onliner/CsOnlinerSourceBuilder.cs

@@ -28,18 +28,12 @@ public override void AcceptVisitor(IAstVisitor visitor)
     {
         if (visitor is PragmaVisitor v)
         {
-            if (Type.ToUpperInvariant() == "STRING")
+            if (Type.ToUpperInvariant() == "STRING" || Type.ToUpperInvariant() == "WSTRING")
             {
                 v.Product = $"private {Type} _{Identifier};" +
                             $"\n{AccessQualifier} {Type} {Identifier} " +
                             $"{{ " +
-                            $"get" +
-                            $"{{ " +
-                            $"return AXSharp.Localizations.LocalizationHelper.CleanUpLocalizationTokens(_{Identifier}); " +
-                            $"}} " +
-                            $"set " +
-                            $"{{_{Identifier} = value;" +
-                            $"}} " +
+                            $"get => string.IsNullOrEmpty(_{Identifier}) ? SymbolTail : this.Translate(_{Identifier}).Interpolate(this); set => _{Identifier} = value; " +
                             $"}}";
             }
             else

src/AXSharp.compiler/src/AXSharp.Cs.Compiler/Pragmas/PragmaParser/Ast/AddedPropertyDeclarationAstNode.cs

@@ -3,6 +3,10 @@
     "ixc": {
       "commandName": "Project",
       "workingDirectory": "c:\\W\\Develop\\gh\\ix-ax\\statemachine\\"
+    },
+    "integration_plc": {
+      "commandName": "Project",
+      "workingDirectory": "c:\\W\\Develop\\gh\\ix-ax\\axsharp\\src\\sanbox\\integration\\ix-integration-plc\\"
     }
   }
 }

src/AXSharp.compiler/src/ixc/Properties/launchSettings.json

@@ -96,6 +96,7 @@
 	</ItemGroup>
 
 	<ItemGroup>
+	  <ProjectReference Include="..\..\..\AXSharp.connectors\src\AXSharp.Connector\AXSharp.Connector.csproj" />
 	  <ProjectReference Include="..\AXSharp.Compiler\AXSharp.Compiler.csproj" />
 	</ItemGroup>
 

src/AXSharp.compiler/src/ixr/AXSharp.ixr.csproj

@@ -23,33 +23,6 @@ public LocalizedStringWrapper()
             RegexOptions.Compiled | RegexOptions.IgnoreCase);
 
 
-        }
-
-        public string CreateId(string rawText)
-        { 
-            StringBuilder sb = new StringBuilder();
-            foreach (var c in rawText)
-            {
-                //try to find character in mappings
-                var mapchar = SymbolMappings.TryToGetValueByChar(c);
-                if(mapchar != null)
-                { 
-                    sb.Append(mapchar); 
-                }
-                //add only if is letter
-                else if (Char.IsLetter(c))
-                {
-                    sb.Append(c); 
-                }
-                else
-                {
-                     //unknown
-                    sb.Append('_'); 
-                }
-            }
-            return sb.ToString();
-    
-          
         }
 
         public bool IsValidId(string id) 

src/AXSharp.compiler/src/ixr/LocalizedStringWrapper.cs

@@ -12,10 +12,10 @@ namespace AXSharp.ixc_doc
 {
     internal class Options : ICompilerOptions
     {
-        [Option('x', "source-project-folder", Required = true, HelpText = "Simatic-ax project folder")]
+        [Option('x', "source-project-folder", Required = false, HelpText = "Simatic-ax project folder")]
         public string? AxSourceProjectFolder { get; set; }
 
-        [Option('o', "output-project-folder", Required = true, HelpText = "Output project folder where compiler emits result.")]
+        [Option('o', "output-project-folder", Required = false, HelpText = "Output project folder where compiler emits result.")]
         public string? OutputProjectFolder { get; set; }
 
     }

src/AXSharp.compiler/src/ixr/Options.cs

@@ -20,16 +20,21 @@
 using static System.Net.Mime.MediaTypeNames;
 using System.Text.RegularExpressions;
 
+
 const string Logo =
-@"| \ / 
-=  =  
-| / \
+@"     ___      ___   ___    _  _   
+    /   \     \  \ /  /  _| || |_ 
+   /  ^  \     \  V  /  |_  __  _|
+  /  /_\  \     >   <    _| || |_ 
+ /  _____  \   /  .  \  |_  __  _|
+/__/     \__\ /__/ \__\   |_||_| 
 ";
 
 
 Console.WriteLine(Logo);
 LegalAcrobatics.LegalComplianceAcrobatics(new FileInfo(Assembly.GetExecutingAssembly().Location).Directory.FullName).Wait();
-Console.WriteLine("Ixr compiler - compile plc localized strings to resx dictonaries");
+Console.WriteLine("Ixr compiler - compiles plc localized strings resources to resx");
+Console.WriteLine($"Version: {GitVersionInformation.SemVer}");
 Parser.Default.ParseArguments<Options>(args)
             .WithParsed(o =>
             {
@@ -54,8 +59,20 @@
 
 void Generate(Options o)
 {
-    var axProject = new AxProject(o.AxSourceProjectFolder);
+    var axProjectFolder = string.IsNullOrEmpty(o.AxSourceProjectFolder)
+        ? Environment.CurrentDirectory
+        : o.AxSourceProjectFolder;
+
+    var axProject = new AxProject(axProjectFolder);
+    var axProjectConfig =
+        AXSharpConfig.RetrieveIxConfig(Path.Combine(axProject.ProjectFolder, AXSharpConfig.CONFIG_FILE_NAME));
+
+    (string folder, string file) output = string.IsNullOrEmpty(axProjectConfig.OutputProjectFolder)
+        ? (string.Empty, o.OutputProjectFolder)
+        : (Path.GetFullPath(Path.Combine(axProject.ProjectFolder, axProjectConfig.OutputProjectFolder, "Resources")), "PlcStringResources.resx");
+
     Console.WriteLine($"Compiling project {axProject.ProjectInfo.Name}...");
+
     var projectSources = axProject.Sources.Select(p => (parseTree: STParser.ParseTextAsync(p).Result, source: p));
 
     var syntaxTrees = projectSources.Select(p => p.parseTree);
@@ -65,13 +82,13 @@ void Generate(Options o)
     //iterate all syntax trees from project
     foreach (var syntaxTree in syntaxTrees)
     {
-        IterateSyntaxTreeForStringLiterals(syntaxTree.GetRoot(),lw, Path.GetRelativePath(o.AxSourceProjectFolder, syntaxTree.Filename));
+        IterateSyntaxTreeForStringLiterals(syntaxTree.GetRoot(),lw, Path.GetRelativePath(axProjectFolder, syntaxTree.Filename));
 
-        IterateSyntaxTreeForPragmas(syntaxTree.GetRoot(), lw, Path.GetRelativePath(o.AxSourceProjectFolder, syntaxTree.Filename));
+        IterateSyntaxTreeForPragmas(syntaxTree.GetRoot(), lw, Path.GetRelativePath(axProjectFolder, syntaxTree.Filename));
     }
 
     //add resources from dictionary to resx file
-    ResxManager.AddResourcesFromDictionary(o.OutputProjectFolder, lw.LocalizedStringsDictionary);
+    ResxManager.AddResourcesFromDictionary(output.folder, output.file, lw.LocalizedStringsDictionary);
 }
 
 void IterateSyntaxTreeForStringLiterals(ISyntaxNode root, LocalizedStringWrapper lw, string fileName)
@@ -115,7 +132,7 @@ void AddToDictionaryIfLocalizedString(ISyntaxToken token, LocalizedStringWrapper
             var rawText = lw.GetRawTextFromLocalizedString(localizedString);
 
             //create id
-            var id = lw.CreateId(rawText);
+            var id = AXSharp.Connector.Localizations.LocalizationHelper.CreateId(rawText);
 
             //check if identifier is valid
             if(lw.IsValidId(id))