refactor(*): New localization implementation. (#16034)

Author: skrustev

.github/CONTRIBUTING.md

@@ -94,20 +94,31 @@ There are several ways to localize components' string resources:
     1.1. Localize a given instance of component - each component which supports localization has input property `resourceStrings`. Setting a newly instantiated object to this property will localize only that given component's instance.
     1.2. Localize all resources for a component type - each component which supports localization has input property `resourceStrings`. To localize all instances of a given component in the application the following steps should be performed - get the value of the input property `resourceStrings` of the component to be localized; do not create a new instance but replace the existing strings within the object. By default all components of a given type in an application share one instance of the resource strings. Replacing a value in that instance affects all components of that type in the application.
     1.3. Localize all resources for all components - use global method `getCurrentResourceStrings` to get an object containing current resource strings for all components. To provide localized resources just pass an object of type `IResourceStrings` to the global method `changei18n`.
+    1.4 As of 21.1.x the localization has new implementation and you can use the new API `registerI18n` to register resource string for a component or all components for the whole app, as well as which locale it corresponds to. To localize a single component you will need to get is corresponding resource string keys using one of the available resources and provide only those keys.
 
 2. Using npm package:
 We've created new repository which will hold the resource strings for languages different than English:
 https://github.com/IgniteUI/igniteui-angular-i18n 
 
-**NOTE** The localization repo has been moved to live inside the `igniteui-angular` repository under `./projects/igniteui-angular-i18n`  
+**NOTE** The localization repo has been moved to live inside the `igniteui-angular` repository under `./projects/igniteui-angular-i18n`
+**NOTE** As of 21.1.x the localization resource strings have been moved to the [`igniteui-i18n`](https://github.com/IgniteUI/igniteui-i18n) repository under `projects/igniteui-i18n-resources`.
 
 A npm package should be published each time we release new version of Ignite UI for Angular. Its version should correspond to the version of the igniteui-angular npm package.
 One could localize an application by importing the corresponding localized resource strings from the localization package (`igniteui-angular-i18n`) and use the methods described in the previous bullet to localize the whole application or part of it.
-Example:
+
+**Example:**
+
 Inside app.module you can perform:
-_import { IgxResouceStringsJA } from ‘igniteui-angular-i18n’;_
-And then:
-_Changei18n(IgxResouceStringsJA);_
+```ts
+import { IgxResouceStringsJA } from ‘igniteui-angular-i18n’;
+changei18n(IgxResouceStringsJA);
+```
+
+**Example new API:**
+```ts
+import { ResouceStringsJA } from ‘igniteui-i18n-resources’;
+registerI18n(IgxResouceStringsJA, 'ja');
+```
 
 ### Resource strings keys naming convention
 Each key in the `IResourceStrings` (and `IGridResourceStrings`, `ITimePickerResourceStrings`, etc.) is prefixed with components' selector and followed by the resource string key. Having components' selectors as prefixes allows us to have same resource strings keys for more than one component.

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes for each version of this project will be documented in this file.
 
+## 21.1.0
+
+# Localization(i18n)
+
+- `IgxActionStrip`, `IgxBanner`, `IgxCalendar`, `IgxCarousel`, `IgxChip`, `IgxCombo`, `IgxDatePicker`, `IgxDateRangePicker`, `IgxGrid`, `IgxTreeGrid`, `IgxHierarchicalGrid`, `IgxPivotGrid`, `IgxInputs`, `IgxList`, `IgxPaginator`, `IgxQueryBuilder`, `IgxTimePicker`, `IgxTree`
+  - New `Intl` implementation for all currently supported components that format and render data like dates and numbers.
+  - New localization implementation for the currently supported languages for all components that have resource strings in the currently supported languages.
+  - New public localization API and package named `igniteui-i18n-resources` containing the new resources that are used in conjunction.
+  - Added API to toggle off Angular's default formatting completely in favor of the new `Intl` implementation. Otherwise `Intl` will be used when a locale is not defined for Angular to use.
+  - Old resources and API should still remain working and not experience any change in behavior, despite internally using the new localization as well.
+
 ## 21.0.0
 
 ### New Features
@@ -109,7 +120,6 @@ See the [Angular Package Format documentation](https://angular.io/guide/angular-
 ## 20.1.0
 
 ### New Features
-
 - `IgxGrid`, `IgxTreeGrid`, `IgxHierarchicalGrid`
     - Introduced a new cell merging feature that allows you to configure and merge cells in a column based on same data or other custom condition, into a single cell.
 

angular.json

@@ -328,7 +328,7 @@
               ],
               "outputHashing": "none",
               "optimization": true,
-              "externalDependencies": ["lit"]
+              "externalDependencies": ["lit", "igniteui-i18n-core"]
             },
             "development": {
               "optimization": false,

package-lock.json

@@ -76,6 +76,7 @@
     "dompurify": "^3.3.0",
     "express": "^5.2.1",
     "fflate": "^0.8.1",
+    "igniteui-i18n-core": "^1.0.1",
     "igniteui-theming": "^24.0.0",
     "igniteui-trial-watermark": "^3.1.0",
     "jspdf": "^3.0.4",
@@ -125,6 +126,7 @@
     "hammerjs": "^2.0.8",
     "ig-typedoc-theme": "^7.0.1",
     "igniteui-dockmanager": "^1.17.0",
+    "igniteui-i18n-resources": "1.0.1",
     "igniteui-sassdoc-theme": "^2.1.0",
     "igniteui-webcomponents": "^6.3.1",
     "jasmine": "^5.6.0",

package.json

@@ -8,7 +8,7 @@ const config = {
     minify: false, // temporary disabled due to Webpack issues https://github.com/webpack/webpack/issues/16262
     outfile: `${ROOT}/elements.js`,
     format: 'esm',
-    external: ['lit'],
+    external: ['lit', 'igniteui-i18n-core'],
     target: 'es2022',
     metafile: true,
     treeShaking: true

projects/igniteui-angular-elements/esbuild.mjs

@@ -5,6 +5,8 @@ import {
   IgxPivotGridComponent,
 } from "../../../igniteui-angular/grids/pivot-grid";
 import { IgxTreeGridComponent } from "../../../igniteui-angular/grids/tree-grid";
+import { IgxActionStripComponent } from "../../../igniteui-angular/action-strip/src/action-strip/action-strip.component";
+import { IgxActionStripToken } from "../../../igniteui-angular/core/src/grid-column-actions/token";
 import { IgxPaginatorComponent } from "../../../igniteui-angular/paginator/src/paginator/paginator.component";
 import { IgxPaginatorToken } from "../../../igniteui-angular/paginator/src/paginator/token";
 import { IgxColumnGroupComponent } from "../../../igniteui-angular/grids/core/src/columns/column-group.component";
@@ -22,8 +24,6 @@ import { IgxGridToolbarExporterComponent } from "../../../igniteui-angular/grids
 import { IgxGridToolbarHidingComponent } from "../../../igniteui-angular/grids/core/src/toolbar/grid-toolbar-hiding.component";
 import { IgxGridToolbarPinningComponent } from "../../../igniteui-angular/grids/core/src/toolbar/grid-toolbar-pinning.component";
 import { IgxRowIslandComponent } from "../../../igniteui-angular/grids/hierarchical-grid/src/row-island.component";
-import { IgxActionStripComponent } from "../../../igniteui-angular/action-strip/src/action-strip/action-strip.component";
-import { IgxActionStripToken } from "../../../igniteui-angular/core/src/grid-column-actions/token";
 import { IgxGridStateComponent } from "../lib/state.component";
 
 export const registerComponents = [

projects/igniteui-angular-elements/src/analyzer/elements.config.ts

@@ -1,3 +1,4 @@
+import { registerI18n, setCurrentI18n } from 'igniteui-i18n-core';
 import { ByLevelTreeGridMergeStrategy, ColumnPinningPosition, DefaultMergeStrategy, DefaultTreeGridMergeStrategy, FilteringExpressionsTree, FilteringExpressionsTreeType, FilteringLogic, HorizontalAlignment, IgxBooleanFilteringOperand, IgxDateFilteringOperand, IgxDateTimeFilteringOperand, IgxFilteringOperand, IgxNumberFilteringOperand, IgxStringFilteringOperand, IgxTimeFilteringOperand, NoopFilteringStrategy, NoopSortingStrategy, SortingDirection, VerticalAlignment } from 'igniteui-angular/core';
 import { DropPosition, GridPagingMode, IgxDateSummaryOperand, IgxNumberSummaryOperand, IgxPivotAggregate, IgxPivotDateAggregate, IgxPivotDateDimension, IgxPivotNumericAggregate, IgxPivotTimeAggregate, IgxSummaryOperand, IgxTimeSummaryOperand, NoopPivotDimensionsStrategy, PivotDimensionType, RowPinningPosition } from 'igniteui-angular/grids/core';
 
@@ -44,4 +45,8 @@ export {
     // overlay position settings (used in grids, paginator, toolbar)
     HorizontalAlignment,
     VerticalAlignment,
+
+    // i18n
+    registerI18n,
+    setCurrentI18n,
 }

projects/igniteui-angular-elements/src/public_api.ts

@@ -2,7 +2,7 @@ import { ClassProvider, createEnvironmentInjector, EnvironmentInjector, getPlatf
 import { BrowserModule, platformBrowser } from '@angular/platform-browser';
 import { provideAnimations } from '@angular/platform-browser/animations';
 import { IgxIconBroadcastService } from '../lib/icon.broadcast.service';
-import { ELEMENTS_TOKEN } from 'igniteui-angular/core';
+import { ELEMENTS_TOKEN , provideIgniteIntl} from 'igniteui-angular/core';
 
 /**
  * Top-level await (TLA) both requires higher ES target and currently has only partial support in ES build
@@ -36,7 +36,8 @@ const injector = createEnvironmentInjector([
     // Elements specific:
     provideAnimations(),
     { provide: ELEMENTS_TOKEN, useValue: true },
-    IgxIconBroadcastService
+    IgxIconBroadcastService,
+    provideIgniteIntl()
 ], platformInjector as EnvironmentInjector);
 
 export { injector };

projects/igniteui-angular-elements/src/utils/injector-ref.ts

@@ -22,5 +22,9 @@
   "bugs": {
     "url": "https://github.com/IgniteUI/igniteui-angular/issues"
   },
-  "homepage": "https://github.com/IgniteUI/igniteui-angular/projects/igniteui-angular-i18n#readme"
+  "homepage": "https://github.com/IgniteUI/igniteui-angular/projects/igniteui-angular-i18n#readme",
+  "dependencies": {
+    "igniteui-i18n-core": "^1.0.1",
+    "igniteui-i18n-resources": "^1.0.1"
+  }
 }