Supported Translations

[hishamco]

Welcome to oqtane.translations repo, this repo should have the supported cultures by Oqtane Framework, few notes I'd like to share with you:

• This respo should have all supported localization resources (Resx) per culture as the following:

Admin

|_    Files
      |_ Add.{culture}.resx

      |_ Details.{culture}.resx

      |_ Edit.{culture}.resx

      |_ Index.{culture}.resx

|_   Jobs

|_   ....

Controls

...

• The cultures are driven by the Oqtane community, so commitment to support all the cultures, but we could ship the cultures with >= 80% completed as NuGet packages if @sbwalker agree

• We could provide a resx template, so contributors can easily start work with them and complete thier translations

/cc @sbwalker @chlupac

[hishamco]

Also I'm thinking to develop a tool to extract the localization resources automatically from the Oqtane source and find away to run this tool on every commit, so any changes happen the resx will be updates, this of course will make the process easier

FYI I already did simalar tool for SimplCommerce also did some contribution for Orchard Core Extractor tool

[PavelVsl]

This will be difficult to maintain, a better solution would be 1 resx file per language (for example syncfusion does so). An extractor tool and an English source resx would be very helpful.

[hishamco]

This will be difficult to maintain, a better solution would be 1 resx file per language (for example syncfusion does so)

This how ASP.NET Core localization works, also don't forget the key could be duplicate across the components or modules, no worry I will try to provide a way to generate all RESX files, just what you want is to set a proper translations for it

[sbwalker]

@hishamco

I am trying to understand the flexibility / technical limitations of the Localization solution...

In the diagram below on the left it describes the flexibility which developers have in organizing their Oqtane projects... you can choose to have an assembly per module, or you can include multiple modules in the same assembly - it depends on how granular you want to be with your deployments.

On the right side I am identifying some different configurations for satellite assemblies which provide localized resources to the modules/assemblies on the left. Are all of these options valid?

[hishamco]

As you mentioned earlier multiple modules could be hosted within a single assembly or each one of them can be hosted in it's own assembly, if I understand you correctly:

1. Assembly1 contains:

   • Module1 (1 Language)

     • Arabic (ar)

2. Assembly2 contains

   • Module1 (Multiple Language)

     • Arabic (ar)

     • English (en)

     • French (fr)

   • Module 2

   • Module 3

While I didn't see Assembly3, Assembly4, Assembly5, Assembly6 so they will be not used (ignored)

Expected Satellite Assemblies:

1. ar

   • Assembly1.Module1.Client.resources.dll

   • Assembly1.Module1.Server.resources.dll

   • Assembly2.Module1.resources.dll

   • Assembly2.Module1.Client.resources.dll

2. en

   • Assembly2.Module1.Client.resources.dll

   • Assembly2.Module1.Server.resources.dll

3. fr

   • Assembly2.Module1.Client.resources.dll

   • Assembly1.Module1.Server.resources.dll

Similarlly if the satellite assemblies are copy from Assembly3, Assembly4, Assembly5 and Assembly6

So Module1 in both assemblies Assembly1 and Assembly2 should be localized, Module2 and Module3 shouldn't. The important thing that's mater to the localization is the Assembly name, and root namespace if it's set, that's why I told you before that we may need to change it in Module Creator if it's required to avoid the developer create a RootNamespaceAttribute

[sbwalker]

I am not sure if you understand my diagram. Assembly1 contains 1 module. Assembly2 contains 3 modules. Neither of these assemblies contain any localization resources.

So my question was related to creating the satellite assemblies which contain the localization resources for these modules. The boxes on the right describe a bunch of different scenarios and I was curious which are supported.

Based on your answer, it sounds like individual satellite assemblies must be created for each unique language and module combination? So for Assembly2 which contains 3 modules - if I wanted to support French and English then I would need to created 6 satellite assemblies?

[hishamco]

I am not sure if you understand my diagram. Assembly1 contains 1 module. Assembly2 contains 3 modules. Neither of these assemblies contain any localization resources.

I understand what you mean, but how the satallite assemblies will be created for the modules inside Assembly1 and Assembly2?!!

if I wanted to support French and English then I would need to created 6 satellite assemblies?

This is correct if you want to localize all the modules

[sbwalker]

So this diagram is the expected approach?

[sbwalker]

Note that the Oqtane framework itself is organized according to the lower portion of the diagram - it is a single assembly that contains many modules. So just to be 100% clear... there will be a separate satellite assembly for each language/module within the Oqtane framework assembly? So for French there would be ~30 satellite assemblies required?

[hishamco]

So for French there would be ~30 satellite assemblies required

If the localized files ~30 Resx files, we can go further and squash them into a single satellite, but it required some modification, I tried to stick with the default ASP.NET Core localization

[sbwalker]

I am not talking about RESX files. For example, in the Oqtane Framework there is a "Files" module which has 4 razor components, and a "Pages" module which has 3 razor components, etc... All of these are compiled into a single assembly. Now if I wanted to localize the Oqtane Framework into French, I was asking how many satellite assemblies would be required. From a convenience perspective it would be great if I could create a single satellite assembly for French. But it sounds like I would have to create >30 individual satellite assemblies - one for each module contained within the Oqtane Framework.

[hishamco]

I am not talking about RESX files

I think there's miss understood here Components No. Per Module = Resx files required for that module. as example If we have 20 modules and each one has 4 razor components, that means you require to have 20 * 4 = 80 RESX files, but at the end there will be a single satellite file Oqtane.Server.resources.dll

Hope it's clear now and sorry for missunderstod at the beginning

[sbwalker]

Its complicated to describe - which is why I created a diagram to visualize it. So just to clarify once again to ensure it is 100% clear, the diagram below shows that if you want to localize to French an assembly which contains 3 modules, you can create either individual satellite assemblies for each module OR you can create a single satellite assembly which contains the resources for all 3 modules. Oqtane will be able to handle both scenarios in terms of localizing the resources for the 3 modules into French. Correct?

[hishamco]

According to my knowledge if all the modules hosted in the same assembly the box on the right is valid, the box on the left is valid if each module in separated assembly, so Oqtane will be able to handle both cased

I can share repo as proof of concept

[hishamco]

FYI I added the default resources (English), I will start to localize another language to make sure that nothing breaks, you could start to localize your favorite language too

[hishamco]

@sbwalker I finished to document all the required steps needs for the translations, BTW can I blog on oqtane.org or this handled by you only?

[sbwalker]

@hishamco thank you for creating some initial instructions. I have a number of questions....

Note that the overarching theme for everything in Oqtane is that integrations with the framework should be as simple as possible and require minimal manual effort. And to ensure a seamless upgrade path, integrations should be cleanly separated from the framework and should interact with the framework via supported extensions points.

The instructions seem to indicate that the RESX files need to be manually copied by the user into a specific folder structure within the framework ( which is not clearly described using a screen shot ) and all of the files need to be manually renamed. It does not say anything about having to compile the RESX files... or the Oqtane framework itself... so I guess one would have to assume that at runtime the RESX files are automatically processed.

This process appears to be complicated and manual. And if it is true that no compilation is required then I am sure we can create a better approach for how to organize the files in the repo so that they can be overlaid over the framework with much less manual effort.

That being said, I raised questions earlier in this thread about the compilation and deployment of resources. I was expecting that it would be possible to compile RESX files into a satellite assembly - and that satellite assembly could then be deployed to the /bin in a single step to localize the environment. This is the approach which modules and themes utilize currently - the run-time deployment model is fundamental to the Oqtane development experience. So my question is whether or not this is possible with the current solution. And if it is possible ( which I assume it is based on your answers to my questions above ) then we need detailed instructions which enable translators to create satellite assemblies.

As a separate use case we also need instructions on how a developer would localize an external module - which was the primary use case for the localization solution.

[hishamco]

@sbwalker I will write a detailed answer later, regarding the renaming is necessary in case that OS default culture is different of that culture you need to support natural language

We may simply the process by agree with certain supported languages, then I can automate the process so the translators will focus on the translation process only

This also may improved by publishing a NuGet packages and modify Oqtane project tasks to copy the translations in the right place

I think we need to think from many perspectives: Developer and Translator

[sbwalker]

Yes there are a number of different user personas who will need instructions that are applicable to their use case. The main thing I would like to confirm is that it is possible to compile RESX files into resources DLLs, and that these DLLs can be deployed independently into the Oqtane /bin and will be available ( as long as those cultures were manually added to the appsettings.json as well )?

[hishamco]

I think so, but this need to compile RESX files before, this way the .resources.dll need to be added to final app

IMHO we can make this repo as source of the localization resource then provide a better and easy way to deploy these resources

[sbwalker]

I agree that this repo should be the place where framework resources are maintained. However those framework resources are not useful unless there are clear instructions on how to integrate them. If you look at the original post in oqtane/oqtane.framework#749 you will see:

As per the Oqtane philosophy, the solution should leverage standard Microsoft approaches as much as possible. It should also leverage encapsulation in terms of minimizing the number of individual assets which need to be deployed. And to ensure a consistent development experience, static localization should follow the same pattern for the core framework as it does for external modules.

[sbwalker]

Here is a use case to consider....

I am a developer using Oqtane. I use it as a framework - so I do not have the Oqtane source code in my development environment. I develop external modules, themes, etc... to create my custom application. Now I would like to support a different language in my application ie. French. How would I integrate only the French resources into my application for the specific version of Oqtane I am utilizing?

One possible answer is that I go to the Translations repo and I clone the resources. I find the location where the French framework resources are stored which are specific to my framework version. I compile those resources into satellite assemblies. I deploy those satellite assemblies to the /bin in my application. I add the culture to appsettings.json. Finished.

[sbwalker]

Nuget would be an enhancement - but you still need the satellite assemblies before you can create a Nuget package. I suggested the use case above because it is the most basic scenario - it is foundational - and once we know that it works then it is possible to pursue other enhancements. Focus on the basics first.

[hishamco]

I will try to create some RESX files for Arabic and compile them, then I will try to use the satellite assemblies in the Oqtane source first, but I have a question, those assemblies need to be located into a culture directory, is this will be a manual process? That's why I suggested NuGet package, because we know what we are doing, we will place all the satellite assemblies in the right culture folder

Your thought?!!

[sbwalker]

If you read my use case above you will see that I said "I do not have the Oqtane source code in my development environment" - which is a very common scenario for developers using Oqtane as a framework. So there is no Package Manager available to pull down a Nuget package. So this solution will not work. This is why I am suggesting that we focus on how to create a satellite assembly from RESX files and how to manually deploy it to Oqtane to make it functional.

[sbwalker]

You don't necessarily need to create a full set of Arabic files. All you need to do is customize some text in the English files so it is slightly different than the default values in the app.

[hishamco]

"I do not have the Oqtane source code in my development environment"

I understand this that you don't have Oqtane Framework source, but you reference its packages, if your intend is the app is are deployed that will another use case

I will try to add this in the use cases that I need to test

[hishamco]

Agreed, but this is how RESX works, the remaining is essential because the default culture is only provided in this repo, once other languages started the process will become easier.

One more thing it could simply the process is the tool can handle generate appropriate naming and copying for generated resources, this way one command from within the CLI will handle this

I can start a new branch in Oqtane.ResxExtractor then you could check the experience yourself if you agreed on the principle

[sbwalker]

Before adding any automation via the Extractor tool can we please get the manual process established and working first?

[hishamco]

I already tested in both runtimes before I wrote them

[sbwalker]

Are you saying that satellite assemblies cannot be created and deployed independently to Oqtane? I believe other products in the .NET ecosystem provide support for this.

[hishamco]

Are you saying that satellite assemblies cannot be created and deployed independently to Oqtane?

I didn't said that it could be created and deployed but they need to be compiled first

[hishamco]

Can we accelerate the process by chatting via Gitter if you don't mind

[sbwalker]

I can open Gitter - I am just not sure if I will be able to be any more responsive, as I have back-to-back work meetings I have to attend for the next 7 hours.