[ACS-5629] enhanced way of providing translations (#8763)

* enhanced way providing translations

* update documentation

* update documentation

* test fixes

* try add missing module import

* inject i18n to core module to cause the setup

demo-shell/src/app/app.module.ts

@@ -24,11 +24,11 @@ import { BrowserAnimationsModule, NoopAnimationsModule } from '@angular/platform
 import { TranslateModule } from '@ngx-translate/core';
 import {
     AppConfigService,
-    TRANSLATION_PROVIDER,
     DebugAppConfigService,
     CoreModule,
     CoreAutomationService,
-    AuthModule
+    AuthModule,
+    provideTranslations
 } from '@alfresco/adf-core';
 import { ExtensionsModule } from '@alfresco/adf-extensions';
 import { AppComponent } from './app.component';
@@ -211,22 +211,8 @@ registerLocaleData(localeSv);
     ],
     providers: [
         { provide: AppConfigService, useClass: DebugAppConfigService }, // not use this service in production
-        {
+        provideTranslations('app', 'resources'),
-            provide: TRANSLATION_PROVIDER,
+        provideTranslations('lazy-loading', 'resources/lazy-loading'),
-            multi: true,
-            useValue: {
-                name: 'app',
-                source: 'resources'
-            }
-        },
-        {
-            provide: TRANSLATION_PROVIDER,
-            multi: true,
-            useValue: {
-                name: 'lazy-loading',
-                source: 'resources/lazy-loading'
-            }
-        },
         AppNotificationsService,
         {
             provide: APP_INITIALIZER,

docs/core/services/translation.service.md

@@ -79,16 +79,21 @@ general format of the path to this folder will be:
 If you wanted English and French translations then you would add
 `en.json` and `fr.json` files into the `i18n` folder and add your new keys:
 
-    // en.json
+**en.json**
 
-        ...
+```json
+{
     "WELCOME_MESSAGE": "Welcome!"
-        ...
+}
+```
 
-    // fr.json
+**fr.json**
-        ...
+
+```json
+{
     "WELCOME_MESSAGE": "Bienvenue !"
-        ...
+}
+```
 
 The files follow the same hierarchical key:value JSON format as the built-in translations.
 You can add new keys to your local files or redefine existing keys but the built-in definitions
@@ -106,57 +111,44 @@ look like the following:
 }
 ```
 
-To enable the new translations in your app, you also need to register them in your
+To enable the new translations in your app, you also need to register them in your `app.module.ts` file using `provideTranslations` api:
-`app.module.ts` file. Import `TRANSLATION_PROVIDER` and add the path of your
-translations folder to the `providers`:
 
 ```ts
-// Other imports...
+import { provideTranslations } from "@alfresco/adf-core";
-
-import { TRANSLATION_PROVIDER } from "@alfresco/adf-core";
-
-  ...
 
 @NgModule({
-  imports: [
-    ...
-  ],
-  declarations: [
-    ...
-  ],
     providers: [
-    {
+        provideTranslations('my-translations', 'assets/my-translations')
-      provide: TRANSLATION_PROVIDER,
+    ]
-      multi: true,
+})
-      useValue: {
+export class MyModule {}
-          name: 'my-translations',
-          source: 'assets/my-translations'
-      }
-  }
-  ...
 ```
 
 You can now use your new keys in your component:
 
 ```ts
-  ...
+export class MyComponent implements OnInit {
-ngOnInit() {
+    translateService = inject(TranslationService);
-    this.trans.use("fr");
+    translatedText = '';
 
-    this.trans.get("WELCOME_MESSAGE").subscribe(translation => {
+    ngOnInit() {
-      this.translatedText = translation;
+        this.translateService.use("fr");
-    });
+        this.translatedText = this.translateService.instant('WELCOME_MESSAGE');
+    }
 }
-  ...
 ```
 
-Note: the `source` property points to the web application root. Ensure you have
+Note: the `source` property points to the web application root.
-webpack correctly set up to copy all the i18n files at compile time.
+Do not forget to configure your Angular application to copy the newly created files to the build output, for example:
 
-```text
+**angular.json**
-index.html
+
-assets/ng2-alfresco-core/i18n/en.json
+```json
-...
+{
+    "glob": "**/*",
+    "input": "lib/core/src/lib/i18n",
+    "output": "/assets/adf-core/i18n"
+}
 ```
 
 You can register as many entries as you like.

lib/content-services/src/lib/content.module.ts

@@ -18,7 +18,7 @@
 import { CommonModule } from '@angular/common';
 import { NgModule, ModuleWithProviders, APP_INITIALIZER } from '@angular/core';
 import { FormsModule, ReactiveFormsModule } from '@angular/forms';
-import { CoreModule, TRANSLATION_PROVIDER, SearchTextModule } from '@alfresco/adf-core';
+import { CoreModule, SearchTextModule, provideTranslations } from '@alfresco/adf-core';
 
 import { MaterialModule } from './material.module';
 
@@ -89,14 +89,7 @@ import { CategoriesModule } from './category/category.module';
         CategoriesModule
     ],
     providers: [
-        {
+        provideTranslations('adf-content-services', 'assets/adf-content-services')
-            provide: TRANSLATION_PROVIDER,
-            multi: true,
-            useValue: {
-                name: 'adf-content-services',
-                source: 'assets/adf-content-services'
-            }
-        }
     ],
     exports: [
         ContentPipeModule,
@@ -134,14 +127,7 @@ export class ContentModule {
         return {
             ngModule: ContentModule,
             providers: [
-                {
+                provideTranslations('adf-content-services', 'assets/adf-content-services'),
-                    provide: TRANSLATION_PROVIDER,
-                    multi: true,
-                    useValue: {
-                        name: 'adf-content-services',
-                        source: 'assets/adf-content-services'
-                    }
-                },
                 {
                     provide: APP_INITIALIZER,
                     useFactory: versionCompatibilityFactory,

lib/core/src/lib/testing/core.story.module.ts

@@ -19,7 +19,7 @@ import { NgModule } from '@angular/core';
 import { CoreModule } from '../core.module';
 import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
 import { TranslateModule } from '@ngx-translate/core';
-import { TRANSLATION_PROVIDER } from '../translation/translation.service';
+import { provideTranslations } from '../translation/translation.service';
 
 @NgModule({
     imports: [
@@ -28,14 +28,7 @@ import { TRANSLATION_PROVIDER } from '../translation/translation.service';
         BrowserAnimationsModule
     ],
     providers: [
-        {
+        provideTranslations('adf-core', 'assets/adf-core')
-            provide: TRANSLATION_PROVIDER,
-            multi: true,
-            useValue: {
-                name: 'adf-core',
-                source: 'assets/adf-core'
-            }
-        }
     ]
 })
 export class CoreStoryModule { }

lib/core/src/lib/translation/translation.service.spec.ts

@@ -21,7 +21,7 @@ import { getTestBed, TestBed } from '@angular/core/testing';
 import { TranslateLoader, TranslateModule } from '@ngx-translate/core';
 
 import { TranslateLoaderService } from './translate-loader.service';
-import { TRANSLATION_PROVIDER, TranslationService } from './translation.service';
+import { provideTranslations, TranslationService } from './translation.service';
 import { AppConfigService } from '../app-config/app-config.service';
 import { AppConfigServiceMock } from '../common/mock/app-config.service.mock';
 import { AlfrescoApiService } from '../services/alfresco-api.service';
@@ -47,14 +47,7 @@ describe('TranslationService', () => {
             providers: [
                 { provide: AlfrescoApiService, useClass: AlfrescoApiServiceMock },
                 { provide: AppConfigService, useClass: AppConfigServiceMock },
-                {
+                provideTranslations('@alfresco/adf-core', 'assets/ng2-alfresco-core')
-                    provide: TRANSLATION_PROVIDER,
-                    multi: true,
-                    useValue: {
-                        name: '@alfresco/adf-core',
-                        source: 'assets/ng2-alfresco-core'
-                    }
-                }
             ]
         });
 

lib/core/src/lib/translation/translation.service.ts

@@ -28,6 +28,24 @@ export interface TranslationProvider {
     source: string;
 }
 
+/**
+ * Generate translation provider
+ *
+ * @param id Unique identifier
+ * @param path Path to translation files
+ * @returns Provider
+ */
+export function provideTranslations(id: string, path: string) {
+    return {
+        provide: TRANSLATION_PROVIDER,
+        multi: true,
+        useValue: {
+            name: id,
+            source: path
+        }
+    };
+}
+
 @Injectable({
     providedIn: 'root'
 })

lib/insights/src/lib/insights.module.ts

@@ -18,7 +18,7 @@
 import { CommonModule } from '@angular/common';
 import { NgModule, ModuleWithProviders } from '@angular/core';
 import { FormsModule, ReactiveFormsModule } from '@angular/forms';
-import { CoreModule, TRANSLATION_PROVIDER } from '@alfresco/adf-core';
+import { CoreModule, provideTranslations } from '@alfresco/adf-core';
 
 import { DiagramsModule } from './diagram/diagram.module';
 import { AnalyticsProcessModule } from './analytics-process/analytics-process.module';
@@ -45,14 +45,7 @@ export class InsightsModule {
         return {
             ngModule: InsightsModule,
             providers: [
-                {
+                provideTranslations('adf-insights', 'assets/adf-insights')
-                    provide: TRANSLATION_PROVIDER,
-                    multi: true,
-                    useValue: {
-                        name: 'adf-insights',
-                        source: 'assets/adf-insights'
-                    }
-                }
             ]
         };
     }

lib/process-services-cloud/src/lib/form/components/form-cloud.component.spec.ts

@@ -25,7 +25,7 @@ import {
     FormModel,
     FormOutcomeEvent,
     FormOutcomeModel, FormRenderingService, FormService,
-    TRANSLATION_PROVIDER, UploadWidgetContentLinkModel, WidgetVisibilityService
+    UploadWidgetContentLinkModel, WidgetVisibilityService, provideTranslations
 } from '@alfresco/adf-core';
 import { Node } from '@alfresco/js-api';
 import { ESCAPE } from '@angular/cdk/keycodes';
@@ -54,6 +54,7 @@ import { FormCloudRepresentation } from '../models/form-cloud-representation.mod
 import { FormCloudService } from '../services/form-cloud.service';
 import { CloudFormRenderingService } from './cloud-form-rendering.service';
 import { FormCloudComponent } from './form-cloud.component';
+import { ProcessServicesCloudModule } from '../../process-services-cloud.module';
 
 const mockOauth2Auth: any = {
     oauth2Auth: {
@@ -1152,17 +1153,11 @@ describe('Multilingual Form', () => {
             imports: [
                 NoopAnimationsModule,
                 TranslateModule.forRoot(),
-                CoreModule.forRoot()
+                CoreModule.forRoot(),
+                ProcessServicesCloudModule.forRoot()
             ],
             providers: [
-                {
+                provideTranslations('app', 'resources')
-                    provide: TRANSLATION_PROVIDER,
-                    multi: true,
-                    useValue: {
-                        name: 'app',
-                        source: 'resources'
-                    }
-                }
             ]
         });
         translateService = TestBed.inject(TranslateService);
@@ -1184,20 +1179,20 @@ describe('Multilingual Form', () => {
         formComponent.ngOnChanges({ appName: new SimpleChange(null, appName, true) });
         expect(formCloudService.getForm).toHaveBeenCalledWith(appName, formId, 1);
 
-        fixture.ngZone.run(() => translateService.use('fr'));
+        await translateService.use('fr').toPromise();
 
-        await fixture.whenStable();
         fixture.detectChanges();
+        await fixture.whenStable();
 
         expect(getLabelValue('textField')).toEqual('Champ de texte');
         expect(getLabelValue('fildUploadField')).toEqual('Téléchargement de fichiers');
         expect(getLabelValue('dateField')).toEqual('Champ de date (D-M-YYYY)');
         expect(getLabelValue('amountField')).toEqual('Champ Montant');
 
-        fixture.ngZone.run(() => translateService.use('en'));
+        await translateService.use('en').toPromise();
 
-        await fixture.whenStable();
         fixture.detectChanges();
+        await fixture.whenStable();
 
         expect(getLabelValue('textField')).toEqual('Text field');
         expect(getLabelValue('fildUploadField')).toEqual('File Upload');
@@ -1237,14 +1232,7 @@ describe('retrieve metadata on submit', () => {
                 FormCloudModule
             ],
             providers: [
-                {
+                provideTranslations('app', 'resources'),
-                    provide: TRANSLATION_PROVIDER,
-                    multi: true,
-                    useValue: {
-                        name: 'app',
-                        source: 'resources'
-                    }
-                },
                 {
                     provide: VersionCompatibilityService,
                     useValue: {}

lib/process-services-cloud/src/lib/process-services-cloud.module.ts

@@ -16,7 +16,7 @@
  */
 
 import { NgModule, ModuleWithProviders } from '@angular/core';
-import { TRANSLATION_PROVIDER, CoreModule, FormRenderingService } from '@alfresco/adf-core';
+import { CoreModule, FormRenderingService, provideTranslations } from '@alfresco/adf-core';
 import { AppListCloudModule } from './app/app-list-cloud.module';
 import { TaskCloudModule } from './task/task-cloud.module';
 import { ProcessCloudModule } from './process/process-cloud.module';
@@ -52,14 +52,7 @@ import { RichTextEditorModule } from './rich-text-editor/rich-text-editor.module
         RichTextEditorModule
     ],
     providers: [
-        {
+        provideTranslations('adf-process-services-cloud', 'assets/adf-process-services-cloud')
-            provide: TRANSLATION_PROVIDER,
-            multi: true,
-            useValue: {
-                name: 'adf-process-services-cloud',
-                source: 'assets/adf-process-services-cloud'
-            }
-        }
     ],
     exports: [
         AppListCloudModule,
@@ -81,14 +74,7 @@ export class ProcessServicesCloudModule {
         return {
             ngModule: ProcessServicesCloudModule,
             providers: [
-                {
+                provideTranslations('adf-process-services-cloud', 'assets/adf-process-services-cloud'),
-                    provide: TRANSLATION_PROVIDER,
-                    multi: true,
-                    useValue: {
-                        name: 'adf-process-services-cloud',
-                        source: 'assets/adf-process-services-cloud'
-                    }
-                },
                 { provide: PROCESS_FILTERS_SERVICE_TOKEN, useExisting: filterPreferenceServiceInstance ?? LocalPreferenceCloudService },
                 { provide: TASK_FILTERS_SERVICE_TOKEN, useExisting: filterPreferenceServiceInstance ?? LocalPreferenceCloudService },
                 { provide: PROCESS_LISTS_PREFERENCES_SERVICE_TOKEN, useExisting: listPreferenceServiceInstance ?? LocalPreferenceCloudService },

lib/process-services-cloud/src/lib/testing/process-services-cloud-story.module.ts

@@ -16,25 +16,20 @@
  */
 
 import { NgModule } from '@angular/core';
-import { CoreModule, TRANSLATION_PROVIDER } from '@alfresco/adf-core';
+import { CoreModule, provideTranslations } from '@alfresco/adf-core';
 import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
 import { TranslateModule } from '@ngx-translate/core';
+import { ProcessServicesCloudModule } from '../process-services-cloud.module';
 
 @NgModule({
     imports: [
+        BrowserAnimationsModule,
         TranslateModule.forRoot(),
         CoreModule.forRoot(),
-        BrowserAnimationsModule
+        ProcessServicesCloudModule.forRoot()
     ],
     providers: [
-        {
+        provideTranslations('adf-process-services-cloud', 'assets/adf-process-services-cloud')
-            provide: TRANSLATION_PROVIDER,
-            multi: true,
-            useValue: {
-                name: 'adf-process-services-cloud',
-                source: 'assets/adf-process-services-cloud'
-            }
-        }
     ]
 })
 export class ProcessServicesCloudStoryModule { }

lib/process-services/src/lib/process.module.ts

@@ -18,7 +18,7 @@
 import { CommonModule } from '@angular/common';
 import { NgModule, ModuleWithProviders } from '@angular/core';
 import { FormsModule, ReactiveFormsModule } from '@angular/forms';
-import { CoreModule, TRANSLATION_PROVIDER, FormRenderingService } from '@alfresco/adf-core';
+import { CoreModule, FormRenderingService, provideTranslations } from '@alfresco/adf-core';
 
 import { MaterialModule } from './material.module';
 
@@ -53,14 +53,7 @@ import { ProcessUserInfoModule } from './process-user-info/process-user-info.mod
         ProcessServicesPipeModule
     ],
     providers: [
-        {
+        provideTranslations('adf-process-services', 'assets/adf-process-services')
-            provide: TRANSLATION_PROVIDER,
-            multi: true,
-            useValue: {
-                name: 'adf-process-services',
-                source: 'assets/adf-process-services'
-            }
-        }
     ],
     exports: [
         CommonModule,
@@ -83,14 +76,7 @@ export class ProcessModule {
         return {
             ngModule: ProcessModule,
             providers: [
-                {
+                provideTranslations('adf-process-services', 'assets/adf-process-services'),
-                    provide: TRANSLATION_PROVIDER,
-                    multi: true,
-                    useValue: {
-                        name: 'adf-process-services',
-                        source: 'assets/adf-process-services'
-                    }
-                },
                 FormRenderingService,
                 { provide: FormRenderingService, useClass: ProcessFormRenderingService }
             ]