@internetarchive/collection-browser 4.8.0 → 4.8.1-webdev-9227.2

package/README.md

@@ -45,6 +45,39 @@ To automatically fix many linting errors, run
 pnpm run format
 ```
 
+## Localization
+
+Wrap user-facing text in `msg()` from `@lit/localize`, inside `render()` or a getter it calls. The first argument has to be a literal: a string, `` str`...${x}` `` when it has an expression, or `` html`...` `` when it has markup. A `msg()` that runs at module scope or in a static field resolves once at import, so it never changes language. A string that has to live outside `render()` goes in a getter, static or not, so it's read at render time.
+
+Every component that renders a `msg()` string, directly or through a helper, needs `@localized()` from `@lit/localize`. Without it the component doesn't re-render when the app switches locale.
+
+This package never calls `configureLocalization`. `@lit/localize` can only be configured once per page, so the app owns that call and loads one bundle holding its own messages and ours. We publish our translations for the app to merge in:
+
+```bash
+pnpm run strings:extract   # add new msg() strings to xliff/<locale>.xlf
+# translate the empty <target>s in xliff/<locale>.xlf
+pnpm run strings:build     # write src/locales/<locale>.ts
+```
+
+Commit all three: the XLIFF, the generated module and the source change.
+
+### What gets published
+
+`@internetarchive/collection-browser/locales/<locale>.js` exports `templates`, the same shape `lit-localize build` writes in runtime mode: an object keyed by message id (a hash of the English source) whose values are what `loadLocale` returns. It only holds messages that have a translation. A message with no translation is left out instead of falling back to English, so merging it can never override another package's or the app's translation of the same text.
+
+That path is a stub in `locales/` at the package root that re-exports `dist/src/locales/<locale>.js`. The package has no `exports` map, so a deep import resolves to a real file, and adding a map would break every other deep import. A new locale needs its own pair of stubs (`.js` and `.d.ts`).
+
+To merge it, an app spreads it under its own templates, app last so the app wins a conflict:
+
+```ts
+import { templates as collectionBrowser } from '@internetarchive/collection-browser/locales/es.js';
+import { templates as app } from './app-es';
+
+export const templates = { ...collectionBrowser, ...app };
+```
+
+The XLIFF in `xliff/` is where translations are edited. It isn't published.
+
 ## Tooling configs
 
 For most of the tools, the configuration is in the `package.json` to reduce the amount of files in your project.

package/dist/src/collection-browser.d.ts

@@ -172,7 +172,8 @@ export declare class CollectionBrowser extends LitElement implements InfiniteScr
      * `LayoutType` for available options. Has no effect on list display modes.
      */
     tileLayoutType: LayoutType;
-    manageViewLabel: string;
+    /** Label for the manage bar. Defaults to the manage bar's own localized label. */
+    manageViewLabel?: string;
     /** Whether to replace the default sort options with a slot for customization (default: false) */
     enableSortOptionsSlot: boolean;
     /** Whether to expose a slot for a smart results carousel above the full results */

package/dist/src/collection-browser.js

@@ -3,7 +3,7 @@ import { __decorate } from "tslib";
 import { html, css, LitElement, nothing, } from 'lit';
 import { customElement, property, query, state } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
-import { msg } from '@lit/localize';
+import { localized, msg } from '@lit/localize';
 import { SearchType, } from '@internetarchive/search-service';
 import '@internetarchive/infinite-scroller';
 import { SortField, getDefaultSelectedFacets, sortOptionFromAPIString, SORT_OPTIONS, defaultProfileElementSorts, defaultFacetDisplayOrder, tvFacetDisplayOrder, defaultSortAvailability, favoritesSortAvailability, tvSortAvailability, } from './models';
@@ -131,7 +131,6 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
          * `LayoutType` for available options. Has no effect on list display modes.
          */
         this.tileLayoutType = 'default';
-        this.manageViewLabel = 'Select items to remove';
         /** Whether to replace the default sort options with a slot for customization (default: false) */
         this.enableSortOptionsSlot = false;
         /** Whether to expose a slot for a smart results carousel above the full results */
@@ -610,12 +609,12 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
         const shouldShowSearching = this.searchResultsLoading || this.totalResults === undefined;
         const classes = classMap({ filtered: this.hasActiveFilters });
         const resultsCount = this.totalResults?.toLocaleString();
-        const resultsLabel = this.totalResults === 1 ? 'Result' : 'Results';
+        const resultsLabel = this.totalResults === 1 ? msg('Result') : msg('Results');
         // Added data-testid for Playwright testing
         return html `
       <div id="results-total" class=${classes} data-testid="results-total">
         <span id="big-results-count">
-          ${shouldShowSearching ? html `Searching&hellip;` : resultsCount}
+          ${shouldShowSearching ? msg('Searching…') : resultsCount}
         </span>
         <span id="big-results-label">
           ${shouldShowSearching ? nothing : resultsLabel}
@@ -664,7 +663,7 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
         return html `<infinite-scroller
       class=${this.infiniteScrollerClasses}
       itemCount=${this.placeholderType ? 0 : nothing}
-      ariaLandmarkLabel="Search results"
+      ariaLandmarkLabel=${msg('Search results')}
       .estimatedCellHeight=${this.estimatedTileHeight}
       .minBufferMarginCells=${this.pageSize}
       .cellProvider=${this}
@@ -1270,7 +1269,7 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
             'clear-filters-btn': true,
             mobile,
         });
-        const buttonText = mobile ? 'Clear all' : 'Clear all filters';
+        const buttonText = mobile ? msg('Clear all') : msg('Clear all filters');
         return html `
       <div class="clear-filters-btn-row">
         ${mobile
@@ -2820,7 +2819,8 @@ __decorate([
     query('infinite-scroller')
 ], CollectionBrowser.prototype, "infiniteScroller", void 0);
 CollectionBrowser = CollectionBrowser_1 = __decorate([
-    customElement('collection-browser')
+    customElement('collection-browser'),
+    localized()
 ], CollectionBrowser);
 export { CollectionBrowser };
 //# sourceMappingURL=collection-browser.js.map