feat: add built-in translations

conventions/Internationalization.md

@@ -21,7 +21,7 @@ For these properties, you should use the internal `getElementDir` helper to appl
 
 ## Translation (t9n)
 
-Previously, components provided Intl props (`intl<Prop>`) to allow users to pass string translations. While this is still supported, for backwards compatibility, our components have translations built-in.
+Previously, components provided Intl properties (`intl<Prop>`) to allow users to pass string translations. While this is still supported for backwards compatibility, our components also have translations built-in.
 
 The following section covers how to add built-in translation support to components.
 
@@ -34,19 +34,25 @@ This pattern enables components to support built-in translations. In order to su
    2. `messages_en.json` – locale-specific bundle (kept in sync with main one via scripts)
 2. Implement the `T9nComponent` interface
    1. The `onMessagesChange` method must be empty as it is wired up by the support utils.
-   2. The `onMessagesChange` method must also be configured with watchers for the messages properties as well as Intl props.
+   2. The `onMessagesChange` method must also be configured with watchers for the messages properties as well as `intl` props.
 3. Use the `setUpMessages` util in the component's `componentWillLoad` lifecycle methods. This must be awaited on to have an initial set of strings available before rendering.
 4. Use the `connectMessages`/`disconnectMessages` utils in the component's `connectedCallback`/`disconnectedCallback` lifecycle methods. This will set up and tear down supporting methods on the component.
 5. Add an appropriate E2E test by using the `t9n` common test helper.
+6. Components such as `input-date-picker` are neither localized nor `t9n` need to forward `intl` props into supporting components.
+   1. Add the `messageOverrides` property.
+   2. Mark `intl` properties as optional, and add a deprecation notice pointing to `messageOverrides` as the new solution.
+   3. Parse the `messageOverrides` along with `intl` properties into supporting components in render method.
+7. Internal components which support public components requires `t9n` properties only to forward the messages.
 
 #### Notes
 
 - This pattern depends on `LocalizedComponent` being implemented.
 - `connectLocalized` (from `LocalizedComponent`) must be called before `connectMessages`.
-- Although Intl props are supported, message overrides have the higher precedence.
-- If a message string has a matching Intl prop, its translation bundle message keys must match the same prop name without the `intl` prefix (e.g., `intlClose` -> `close`)
+- Although `intl` properties are supported, message overrides have the higher precedence.
+- If a message string has a matching `intl` prop, its translation bundle message keys must match the same prop name without the `intl` prefix (e.g., `intlClose` -> `close`)
 - You can also look at the interface and util documentation for additional info.
-- The internal `messages` prop should be used as the source of truth for translations in rendering.
+- The internal `messages` property should be used as the source of truth for translations in rendering.
+- List of supported locales can be found on our [Localization support page](https://developers.arcgis.com/calcite-design-system/localization/#locale-support).
 
 ## Translated strings
 
@@ -57,7 +63,7 @@ In the future it will likely become necessary to provide string translations for
 - https://medium.com/stencil-tricks/implementing-internationalisation-i18n-with-stencil-5e6559554117 and https://codesandbox.io/s/43pmx55vo9
 - https://github.com/ionic-team/ionic-stencil-conference-app/issues/69
 
-Until we implement a `lang` facility and set up translations for all components, we have been allowing a small number of strings to be passed in as props. Props that represent translated strings should have the syntax: `text-label-x`, where `x` is the name for the string. For example, when providing a string from "Close", use the prop name `text-label-close`. In the component, these props should default to their English equivalent (this is useful for non-localized apps):
+Until we implement a `lang` facility and set up translations for all components, we have been allowing a small number of strings to be passed in as properties. Properties that represent translated strings should have the syntax: `text-label-x`, where `x` is the name for the string. For example, when providing a string from "Close", use the property name `text-label-close`. In the component, these properties should default to their English equivalent (this is useful for non-localized apps):
 
 ```
 @Prop() textLabelClose: string = 'Close';

src/components/action-bar/action-bar.e2e.ts

@@ -1,5 +1,5 @@
 import { newE2EPage } from "@stencil/core/testing";
-import { accessible, defaults, focusable, hidden, reflects, renders, slots } from "../../tests/commonTests";
+import { accessible, defaults, focusable, hidden, reflects, renders, slots, t9n } from "../../tests/commonTests";
 import { CSS, SLOTS } from "./resources";
 import { overflowActionsDebounceInMs } from "./utils";
 import { html } from "../../../support/formatting";
@@ -382,4 +382,6 @@ describe("calcite-action-bar", () => {
       expect(await page.findAll(slottedActionsSelector)).toHaveLength(2);
     });
   });
+
+  it("supports translation", () => t9n("calcite-action-bar"));
 });

src/components/action-bar/action-bar.stories.ts

@@ -9,7 +9,6 @@ import {
 import readme from "./readme.md";
 import { ATTRIBUTES } from "../../../.storybook/resources";
 import { html } from "../../../support/formatting";
-import { TEXT } from "./resources";
 import { storyFilters } from "../../../.storybook/helpers";
 
 export default {
@@ -41,22 +40,6 @@ const createAttributes: (options?: { exceptions: string[] }) => Attributes = ({
           return this;
         }
       },
-      {
-        name: "intl-expand",
-        commit(): Attribute {
-          this.value = text("intlExpand", TEXT.expand);
-          delete this.build;
-          return this;
-        }
-      },
-      {
-        name: "intl-collapse",
-        commit(): Attribute {
-          this.value = text("intlCollapse", TEXT.collapse);
-          delete this.build;
-          return this;
-        }
-      },
       {
         name: "position",
         commit(): Attribute {
@@ -178,3 +161,33 @@ export const withTooltip_NoTest = (): string =>
 withTooltip_NoTest.parameters = {
   chromatic: { disableSnapshot: true }
 };
+
+export const hebrewLocale_TestOnly = (): string => `<calcite-action-bar expanded lang="he">
+<calcite-action text="Information" icon="information"></calcite-action>
+<calcite-action text="Feedback" slot="bottom-actions" icon="mega-phone"></calcite-action>
+</calcite-action-bar>`;
+
+export const norwegianLocale_TestOnly = (): string => `<calcite-action-bar expanded lang="nb">
+<calcite-action text="Information" icon="information"></calcite-action>
+<calcite-action text="Feedback" slot="bottom-actions" icon="mega-phone"></calcite-action>
+</calcite-action-bar>`;
+
+export const FrenchLocale_TestOnly = (): string => `<calcite-action-bar expanded lang="fr">
+<calcite-action text="Information" icon="information"></calcite-action>
+<calcite-action text="Feedback" slot="bottom-actions" icon="mega-phone"></calcite-action>
+</calcite-action-bar>`;
+
+export const hongKongLocale_TestOnly = (): string => `<calcite-action-bar expanded lang="zh-HK">
+<calcite-action text="Information" icon="information"></calcite-action>
+<calcite-action text="Feedback" slot="bottom-actions" icon="mega-phone"></calcite-action>
+</calcite-action-bar>`;
+
+export const ukranianLocale_TestOnly = (): string => `<calcite-action-bar expanded lang="uk">
+<calcite-action text="Information" icon="information"></calcite-action>
+<calcite-action text="Feedback" slot="bottom-actions" icon="mega-phone"></calcite-action>
+</calcite-action-bar>`;
+
+export const bosnianLocale_TestOnly = (): string => `<calcite-action-bar expanded lang="bs">
+<calcite-action text="Information" icon="information"></calcite-action>
+<calcite-action text="Feedback" slot="bottom-actions" icon="mega-phone"></calcite-action>
+</calcite-action-bar>`;

src/components/action-bar/action-bar.tsx

@@ -8,11 +8,12 @@ import {
   Watch,
   h,
   VNode,
-  Method
+  Method,
+  State
 } from "@stencil/core";
 import { Position, Scale, Layout } from "../interfaces";
 import { ExpandToggle, toggleChildActionText } from "../functional/ExpandToggle";
-import { CSS, SLOTS, TEXT } from "./resources";
+import { CSS, SLOTS } from "./resources";
 import { getSlotted, focusElement } from "../../utils/dom";
 import {
   geActionDimensions,
@@ -28,6 +29,15 @@ import {
   disconnectConditionalSlotComponent,
   ConditionalSlotComponent
 } from "../../utils/conditionalSlot";
+import { connectLocalized, disconnectLocalized, LocalizedComponent } from "../../utils/locale";
+import {
+  connectMessages,
+  disconnectMessages,
+  setUpMessages,
+  T9nComponent,
+  updateMessages
+} from "../../utils/t9n";
+import { Messages } from "./assets/action-bar/t9n";
 import {
   setUpLoadableComponent,
   setComponentLoaded,
@@ -43,9 +53,12 @@ import {
 @Component({
   tag: "calcite-action-bar",
   styleUrl: "action-bar.scss",
-  shadow: true
+  shadow: true,
+  assetsDirs: ["assets"]
 })
-export class ActionBar implements ConditionalSlotComponent, LoadableComponent {
+export class ActionBar
+  implements ConditionalSlotComponent, LoadableComponent, LocalizedComponent, T9nComponent
+{
   // --------------------------------------------------------------------------
   //
   //  Properties
@@ -75,11 +88,15 @@ export class ActionBar implements ConditionalSlotComponent, LoadableComponent {
 
   /**
    * Specifies the label of the expand icon when the component is collapsed.
+   *
+   * @deprecated - translations are now built-in, if you need to override a string, please use `messageOverrides`
    */
   @Prop() intlExpand: string;
 
   /**
    * Specifies the label of the collapse icon when the component is expanded.
+   *
+   * @deprecated - translations are now built-in, if you need to override a string, please use `messageOverrides`
    */
   @Prop() intlCollapse: string;
 
@@ -110,6 +127,25 @@ export class ActionBar implements ConditionalSlotComponent, LoadableComponent {
    */
   @Prop({ reflect: true }) scale: Scale;
 
+  /**
+   * Made into a prop for testing purposes only
+   *
+   * @internal
+   */
+  @Prop({ mutable: true }) messages: Messages;
+
+  /**
+   * Use this property to override individual strings used by the component.
+   */
+  @Prop({ mutable: true }) messageOverrides: Partial<Messages>;
+
+  @Watch("intlCollapse")
+  @Watch("intlExpand")
+  @Watch("messageOverrides")
+  onMessagesChange(): void {
+    /* wired up by t9n util */
+  }
+
   // --------------------------------------------------------------------------
   //
   //  Events
@@ -139,16 +175,21 @@ export class ActionBar implements ConditionalSlotComponent, LoadableComponent {
 
   expandToggleEl: HTMLCalciteActionElement;
 
+  @State() effectiveLocale: string;
+
+  @Watch("effectiveLocale")
+  effectiveLocaleChange(): void {
+    updateMessages(this, this.effectiveLocale);
+  }
+
+  @State() defaultMessages: Messages;
+
   // --------------------------------------------------------------------------
   //
   //  Lifecycle
   //
   // --------------------------------------------------------------------------
 
-  componentWillLoad(): void {
-    setUpLoadableComponent(this);
-  }
-
   componentDidLoad(): void {
     setComponentLoaded(this);
     this.conditionallyOverflowActions();
@@ -157,6 +198,8 @@ export class ActionBar implements ConditionalSlotComponent, LoadableComponent {
   connectedCallback(): void {
     const { el, expanded } = this;
 
+    connectLocalized(this);
+    connectMessages(this);
     toggleChildActionText({ parent: el, expanded });
 
     this.mutationObserver?.observe(el, { childList: true, subtree: true });
@@ -169,10 +212,17 @@ export class ActionBar implements ConditionalSlotComponent, LoadableComponent {
     connectConditionalSlotComponent(this);
   }
 
+  async componentWillLoad(): Promise<void> {
+    setUpLoadableComponent(this);
+    await setUpMessages(this);
+  }
+
   disconnectedCallback(): void {
     this.mutationObserver?.disconnect();
     this.resizeObserver?.disconnect();
     disconnectConditionalSlotComponent(this);
+    disconnectLocalized(this);
+    disconnectMessages(this);
   }
 
   // --------------------------------------------------------------------------
@@ -290,28 +340,17 @@ export class ActionBar implements ConditionalSlotComponent, LoadableComponent {
   // --------------------------------------------------------------------------
 
   renderBottomActionGroup(): VNode {
-    const {
-      expanded,
-      expandDisabled,
-      intlExpand,
-      intlCollapse,
-      el,
-      position,
-      toggleExpand,
-      scale,
-      layout
-    } = this;
+    const { expanded, expandDisabled, el, position, toggleExpand, scale, layout, messages } = this;
 
     const tooltip = getSlotted(el, SLOTS.expandTooltip) as HTMLCalciteTooltipElement;
-    const expandLabel = intlExpand || TEXT.expand;
-    const collapseLabel = intlCollapse || TEXT.collapse;
 
     const expandToggleNode = !expandDisabled ? (
       <ExpandToggle
         el={el}
         expanded={expanded}
-        intlCollapse={collapseLabel}
-        intlExpand={expandLabel}
+        // rename intl properties for 1.0
+        intlCollapse={messages.collapse}
+        intlExpand={messages.expand}
         position={position}
         ref={this.setExpandToggleRef}
         scale={scale}

src/components/action-bar/resources.ts

@@ -6,8 +6,3 @@ export const SLOTS = {
   bottomActions: "bottom-actions",
   expandTooltip: "expand-tooltip"
 };
-
-export const TEXT = {
-  expand: "Expand",
-  collapse: "Collapse"
-};

src/components/action-group/action-group.e2e.ts

@@ -1,4 +1,4 @@
-import { accessible, hidden, renders, slots } from "../../tests/commonTests";
+import { accessible, hidden, renders, slots, t9n } from "../../tests/commonTests";
 import { newE2EPage } from "@stencil/core/testing";
 import { SLOTS } from "./resources";
 
@@ -28,4 +28,6 @@ describe("calcite-action-group", () => {
 
     expect(await menu.getProperty("scale")).toBe("l");
   });
+
+  it("support translation", () => t9n("calcite-action-group"));
 });

src/components/action-group/action-group.stories.ts

@@ -41,3 +41,39 @@ export const gridCenteringOfActionsInAGroup = (): string => html`
     </calcite-action-group>
   </div>
 `;
+
+export const arabicLocale_TestOnly = (): string => html`<div style="width:400px">
+  <calcite-action-group expanded lang="ar">
+    <calcite-dropdown slot="menu-actions"> </calcite-dropdown>
+  </calcite-action-group>
+</div>`;
+
+export const germanLocale_TestOnly = (): string => html`<div style="width:400px">
+  <calcite-action-group expanded lang="de">
+    <calcite-dropdown slot="menu-actions"> </calcite-dropdown>
+  </calcite-action-group>
+</div>`;
+
+export const norwegianLocale_TestOnly = (): string => html`<div style="width:400px">
+  <calcite-action-group expanded lang="no">
+    <calcite-dropdown slot="menu-actions"> </calcite-dropdown>
+  </calcite-action-group>
+</div>`;
+
+export const ChineseLocale_TestOnly = (): string => html`<div style="width:400px">
+  <calcite-action-group expanded lang="zh-CN">
+    <calcite-dropdown slot="menu-actions"> </calcite-dropdown>
+  </calcite-action-group>
+</div>`;
+
+export const GreekLocale_TestOnly = (): string => html`<div style="width:400px">
+  <calcite-action-group expanded lang="el">
+    <calcite-dropdown slot="menu-actions"> </calcite-dropdown>
+  </calcite-action-group>
+</div>`;
+
+export const TurkishLocale_TestOnly = (): string => html`<div style="width:400px">
+  <calcite-action-group expanded lang="tr">
+    <calcite-dropdown slot="menu-actions"> </calcite-dropdown>
+  </calcite-action-group>
+</div>`;