Localization Changes

[sbwalker]

In order to solve some of the problems identified in #16 and incorporate feedback from the community who have attempted to create translations for Oqtane thus far, we will be making the following changes:

1. Default (neutral) resource files ( .resx ) will be maintained in the Oqtane.Framework repo in the Oqtane.Client\Resources location. We are making this change to ensure that there is always a 100% fully updated set of resource files which reflect the latest state of the framework. Since introducing localization support in Oqtane 2.0 there has been no process to ensure resource files stay up to date, and no "source of truth" for translators to refer to when maintaining language-specific resource files ( ie. when UI component files are added or removed, or when static text is added, modified, or removed from components ). As a result the language resources in this repo are in various stages of completion and are neither reliable nor consistent which means they are not providing value to users. This change means that going forward, all framework changes which affect the UI and require localization, need to have the associated .resx changes included.

2. Default (neutral) resource files ( *.resx ) are being updated to reflect the latest development branch code. This change is being done to ensure we have a solid baseline which includes all necessary files and localized text. This will become the "source of truth" that translators can use to create their language-specific translations. These resources will be included in the 2.2.0 release. Upon each official release the full set of default resources files will be merged into the English (en) folder in this repo to ensure it contains all of the resources for current official release.

3. Localization implemented within components will use static keys. This change is being made to ensure that language specific translations are not broken when static text messages are modified in UI components. The standard method for .NET Core localization was theoretically optimized to make software development easier; however it is a nightmare for translators because the key values are not static and often change - breaking the key lookup linkage. For example, logic such as Localizer["Please Enter All Fields And Ensure Passwords Match And Are Greater Than 5 Characters In Length"] may require a change to the message - which would break all existing resource files for other languages. This will be changed to Localizer.GetString("Message.PasswordValidation", "Please Enter All Fields And Ensure Passwords Match And Are Greater Than 5 Characters In Length") where "Message.PasswordValidation" is a static key that will never change and therefore can be relied upon by translators.

4. Repetitive terms will be managed in a SharedResources.resx file. This change is being made so that the exact same term does not need to be localized in many different resources files associated to components. Terms such as "Save", Cancel", "Delete" will be located in a single resource file. This will require a new service to be injected into razor components in some cases ie. @inject IStringLocalizer < SharedResources > SharedLocalizer to load the shared resource key.

5. Translators will include a readme file in their specific language folder in the oqtane.translations repo which contains metadata such as the author, Oqtane version it relates to, last update, etc... to allow consumers to quickly understand the state of language resources. Translators will also include some build artifacts for their language resources which allows a consumer to easily compile them and generate a Nuget package which can be uploaded to Nuget.org and/or installed into an Oqtane installation.

[hishamco]

I agree to use shared resources in the places that required, but regarding the English resources I don't think there's a need to produce them. ASP.NET Localization APIs will return the missing resource

BTW I added them in the repo in case someone want to create a new translation instead of using Oqtane.ResxExtractor tool, If I will go with this approach Oqtane.ResxExtractor need to run periodecly to make sure that English resource are up to date but again the translation maintainers need to check the newly added keys

Your thought?

[sbwalker]

I have already made the decision to include the default RESX files in the Oqtane.Framework repo - they will be merged today or tomorrow. I explained the rationale for why we need to make this change above. I appreciate the effort put into the ResXExtractor tool but I do not believe it is the right long term solution, as it is not capable of picking up all types static text currently, it is not intelligent enough to deal with logic or tokens within static text, it does not deal with static keys, it does not handle shared resources, etc... and we cannot be restricted by the limitations of such a tool which will need to be maintained on an ongoing basis. The better approach is to manage the default resources as a standard part of software development in the framework.

[hishamco]

No problem, the tool need to be updated like other OSS to handle all the cases, regarding providing English ressources which is the first time I see in ASP.NET Core application, I'm still asking myself:

• How the translation maintainer will know about the changes in the resources?
• Does they need to check the English resources periodically?
• How we can ensure that the new translation is enough to publish it as NuGet package

[sbwalker]

This gets back to the workflow topic #16 that I raised back in April... which is one of the drivers behind these changes...

• default resx files will be maintained as a standard part of development for the framework
• when a framework release happens, a translator needs an easy way to identify the differences between the new set of resx files for the release and the resx files for the previous release. We could force them to download multiple versions of the framework to obtain the default resx files for each verson - or we could store only these default resx files by version in some location ( such as this repo ) to make it easier ( we discussed this in another thread in this repo ).
• Once you have the 2 sets of default resx files, it is possible to use whatever file comparison tool is your preference ( ie. BeyondCompare, Araxis Merge, WinMerge, ResXManager, etc... ) to identify the differences between them.
• Once a translator can identify the differences, then they can make the necessary changes in their own language-specific resx files to bring them up to update.
• Translators will maintain their resx files at their own pace - some will keep them updated for every new Oqtane release - others will not. Which is why a README with metadata is important.
• It is the translators responsibility to ensure their translation is 100% complete for a release... if they publish a Nuget package which is incomplete, the community will certainly provide them with "feedback" ( ie. essentially by logging issues against that translation ).

[sbwalker]

Items 1-4 have been completed from the list above:

1. Default (neutral) resource files ( *.resx ) created in the Oqtane.Framework repo
2. Default (neutral) resource files ( *.resx ) updated to reflect the latest development branch code
3. Localization implemented within components use static keys.
4. Repetitive terms managed in a SharedResources.resx file.

The language specific resx files in this repo will need to be updated for the next release.

[sbwalker]

It is still not clear to me how translators and users are expected to use this repo to quickly and easily manage the resources for various versions of the framework.

For example if I am running Oqtane as a user how would I get the set of resx files for a specific language for a specific framework version?

And if I am a translator how would I see the differences in resx files between different framework versions?

It seems that many of these scenarios could be solved by maintaining the resx files in folders organized by version.

The ultimate goal is to make it as fast and simple as possible for the community to consume and maintain resources for Oqtane - so we need to come up with ways to improve this area.

[leigh-pointer]

No further action