feat(platform-browser): add withI18nSupport() in developer preview (#…

…55130)

Expose withI18nSupport() as a hydration feature to enable i18n hydration

PR Close #55130

adev/src/content/guide/hydration.md

@@ -128,9 +128,22 @@ Keep in mind that adding the `ngSkipHydration` attribute to your root applicatio
 
 ## I18N
 
-We don't yet support internationalization with hydration, but support is coming.
-Currently, Angular would skip hydration for components that use i18n blocks, effectively
-re-rendering those components from scratch.
+HELPFUL: Support for internationalization with hydration is currently in [developer preview](/guide/releases#developer-preview). By default, Angular will skip hydration for components that use i18n blocks, effectively re-rendering those components from scratch.
+
+To enable hydration for i18n blocks, you can add [`withI18nSupport`](/api/platform-browser/withI18nSupport) to your `provideClientHydration` call.
+
+```typescript
+import {
+  bootstrapApplication,
+  provideClientHydration,
+  withI18nSupport,
+} from '@angular/platform-browser';
+...
+
+bootstrapApplication(AppComponent, {
+  providers: [provideClientHydration(withI18nSupport())]
+});
+```
 
 ## Third Party Libraries with DOM Manipulation
 

goldens/public-api/platform-browser/index.md

@@ -157,6 +157,8 @@ export enum HydrationFeatureKind {
     // (undocumented)
     HttpTransferCacheOptions = 1,
     // (undocumented)
+    I18nSupport = 2,
+    // (undocumented)
     NoHttpTransferCache = 0
 }
 
@@ -258,6 +260,9 @@ export const VERSION: Version;
 // @public
 export function withHttpTransferCacheOptions(options: HttpTransferCacheOptions): HydrationFeature<HydrationFeatureKind.HttpTransferCacheOptions>;
 
+// @public
+export function withI18nSupport(): HydrationFeature<HydrationFeatureKind.I18nSupport>;
+
 // @public
 export function withNoHttpTransferCache(): HydrationFeature<HydrationFeatureKind.NoHttpTransferCache>;
 

packages/core/src/core_private_export.ts

@@ -25,7 +25,7 @@ export {INJECTOR_SCOPE as ɵINJECTOR_SCOPE} from './di/scope';
 export {XSS_SECURITY_URL as ɵXSS_SECURITY_URL} from './error_details_base_url';
 export {formatRuntimeError as ɵformatRuntimeError, RuntimeError as ɵRuntimeError, RuntimeErrorCode as ɵRuntimeErrorCode} from './errors';
 export {annotateForHydration as ɵannotateForHydration} from './hydration/annotate';
-export {withDomHydration as ɵwithDomHydration, withI18nHydration as ɵwithI18nHydration} from './hydration/api';
+export {withDomHydration as ɵwithDomHydration, withI18nSupport as ɵwithI18nSupport} from './hydration/api';
 export {IS_HYDRATION_DOM_REUSE_ENABLED as ɵIS_HYDRATION_DOM_REUSE_ENABLED} from './hydration/tokens';
 export {HydratedNode as ɵHydratedNode, HydrationInfo as ɵHydrationInfo, readHydrationInfo as ɵreadHydrationInfo, SSR_CONTENT_INTEGRITY_MARKER as ɵSSR_CONTENT_INTEGRITY_MARKER} from './hydration/utils';
 export {CurrencyIndex as ɵCurrencyIndex, ExtraLocaleDataIndex as ɵExtraLocaleDataIndex, findLocaleData as ɵfindLocaleData, getLocaleCurrencyCode as ɵgetLocaleCurrencyCode, getLocalePluralCase as ɵgetLocalePluralCase, LocaleDataIndex as ɵLocaleDataIndex, registerLocaleData as ɵregisterLocaleData, unregisterAllLocaleData as ɵunregisterLocaleData} from './i18n/locale_data_api';

packages/core/src/hydration/api.ts

@@ -8,7 +8,7 @@
 
 import {APP_BOOTSTRAP_LISTENER, ApplicationRef, whenStable} from '../application/application_ref';
 import {Console} from '../console';
-import {ENVIRONMENT_INITIALIZER, EnvironmentProviders, Injector, makeEnvironmentProviders} from '../di';
+import {ENVIRONMENT_INITIALIZER, EnvironmentProviders, Injector, makeEnvironmentProviders, Provider} from '../di';
 import {inject} from '../di/injector_compatibility';
 import {formatRuntimeError, RuntimeError, RuntimeErrorCode} from '../errors';
 import {enableLocateOrCreateContainerRefImpl} from '../linker/view_container_ref';
@@ -80,7 +80,7 @@ function enableHydrationRuntimeSupport() {
 /**
  * Brings the necessary i18n hydration code in tree-shakable manner.
  * Similar to `enableHydrationRuntimeSupport`, the code is only
- * present when `withI18nHydration` is invoked.
+ * present when `withI18nSupport` is invoked.
  */
 function enableI18nHydrationRuntimeSupport() {
   if (!isI18nHydrationRuntimeSupportEnabled) {
@@ -171,7 +171,9 @@ export function withDomHydration(): EnvironmentProviders {
     {
       provide: ENVIRONMENT_INITIALIZER,
       useValue: () => {
-        setIsI18nHydrationSupportEnabled(isI18nHydrationEnabled());
+        // i18n support is enabled by calling withI18nSupport(), but there's
+        // no way to turn it off (e.g. for tests), so we turn it off by default.
+        setIsI18nHydrationSupportEnabled(false);
 
         // Since this function is used across both server and client,
         // make sure that the runtime code is only added when invoked
@@ -230,8 +232,8 @@ export function withDomHydration(): EnvironmentProviders {
  * Returns a set of providers required to setup support for i18n hydration.
  * Requires hydration to be enabled separately.
  */
-export function withI18nHydration(): EnvironmentProviders {
-  return makeEnvironmentProviders([
+export function withI18nSupport(): Provider[] {
+  return [
     {
       provide: IS_I18N_HYDRATION_ENABLED,
       useValue: true,
@@ -240,10 +242,12 @@ export function withI18nHydration(): EnvironmentProviders {
       provide: ENVIRONMENT_INITIALIZER,
       useValue: () => {
         enableI18nHydrationRuntimeSupport();
+        setIsI18nHydrationSupportEnabled(true);
+        performanceMarkFeature('NgI18nHydration');
       },
       multi: true,
     },
-  ]);
+  ];
 }
 
 /**

packages/core/test/bundling/hydration/bundle.golden_symbols.json

@@ -218,9 +218,6 @@
   {
     "name": "IS_HYDRATION_DOM_REUSE_ENABLED"
   },
-  {
-    "name": "IS_I18N_HYDRATION_ENABLED"
-  },
   {
     "name": "InjectFlags"
   },

packages/platform-browser/src/hydration.ts

@@ -7,7 +7,7 @@
  */
 
 import {HttpTransferCacheOptions, ɵwithHttpTransferCache} from '@angular/common/http';
-import {ENVIRONMENT_INITIALIZER, EnvironmentProviders, inject, makeEnvironmentProviders, NgZone, Provider, ɵConsole as Console, ɵformatRuntimeError as formatRuntimeError, ɵwithDomHydration as withDomHydration,} from '@angular/core';
+import {ENVIRONMENT_INITIALIZER, EnvironmentProviders, inject, makeEnvironmentProviders, NgZone, Provider, ɵConsole as Console, ɵformatRuntimeError as formatRuntimeError, ɵwithDomHydration as withDomHydration, ɵwithI18nSupport} from '@angular/core';
 
 import {RuntimeErrorCode} from './errors';
 
@@ -20,6 +20,7 @@ import {RuntimeErrorCode} from './errors';
 export enum HydrationFeatureKind {
   NoHttpTransferCache,
   HttpTransferCacheOptions,
+  I18nSupport,
 }
 
 /**
@@ -70,6 +71,16 @@ export function withHttpTransferCacheOptions(
       HydrationFeatureKind.HttpTransferCacheOptions, ɵwithHttpTransferCache(options));
 }
 
+/**
+ * Enables support for hydrating i18n blocks.
+ *
+ * @developerPreview
+ * @publicApi
+ */
+export function withI18nSupport(): HydrationFeature<HydrationFeatureKind.I18nSupport> {
+  return hydrationFeature(HydrationFeatureKind.I18nSupport, ɵwithI18nSupport());
+}
+
 /**
  * Returns an `ENVIRONMENT_INITIALIZER` token setup with a function
  * that verifies whether compatible ZoneJS was used in an application

packages/platform-browser/src/platform-browser.ts

@@ -78,7 +78,7 @@ export {REMOVE_STYLES_ON_COMPONENT_DESTROY} from './dom/dom_renderer';
 export {EVENT_MANAGER_PLUGINS, EventManager, EventManagerPlugin} from './dom/events/event_manager';
 export {HAMMER_GESTURE_CONFIG, HAMMER_LOADER, HammerGestureConfig, HammerLoader, HammerModule} from './dom/events/hammer_gestures';
 export {DomSanitizer, SafeHtml, SafeResourceUrl, SafeScript, SafeStyle, SafeUrl, SafeValue} from './security/dom_sanitization_service';
-export {HydrationFeature, provideClientHydration, HydrationFeatureKind, withHttpTransferCacheOptions, withNoHttpTransferCache} from './hydration';
+export {HydrationFeature, HydrationFeatureKind, provideClientHydration, withHttpTransferCacheOptions, withI18nSupport, withNoHttpTransferCache} from './hydration';
 
 export * from './private_export';
 export {VERSION} from './version';