@salesforce/ui-bundle-template-feature-angular-language-switcher 12.5.4

package/LICENSE.txt

@@ -0,0 +1,82 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this
+software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were
+last updated on April 15, 2025, and constitute a legally binding
+agreement between you and Salesforce. If you do not agree to these Terms of
+Use, do not install or use the Software.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free
+copyright license to reproduce, prepare derivative works of, publicly
+display, publicly perform, sublicense, and distribute the Software and
+derivative works subject to these Terms. These Terms shall be included in
+all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce
+reserves all rights, title, and interest in and to all intellectual
+property subsisting in the Software. No rights are granted to you hereunder
+other than as expressly set forth herein. Users residing in countries on
+the United States Office of Foreign Assets Control sanction list, or which
+are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you
+are responsible. The Software may contain bugs, errors and
+incompatibilities and is made available on an AS IS basis without support,
+updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or
+discontinue, the Software (or any part thereof) with or without notice. You
+agree that Salesforce shall not be liable to you or to any third party for
+any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or
+proceeding made or brought against Salesforce by a third party arising out
+of or accruing from (a) your use of the Software, and (b) any application
+you develop with the Software that infringes any copyright, trademark,
+trade secret, trade dress, patent, or other intellectual property right of
+any person or defames any person or violates their rights of publicity or
+privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce
+from any damages, attorney fees, and costs finally awarded against
+Salesforce as a result of, or for any amounts paid by Salesforce under a
+settlement approved by you in writing of, a Claim Against Salesforce,
+provided Salesforce (x) promptly gives you written notice of the Claim
+Against Salesforce, (y) gives you sole control of the defense and
+settlement of the Claim Against Salesforce (except that you may not settle
+any Claim Against Salesforce unless it unconditionally releases Salesforce
+of all liability), and (z) gives you all reasonable assistance, at your
+expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT
+SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES,
+INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA,
+OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN
+CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU
+HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of
+the State of California, without regard to its conflicts of laws
+rules. Each party hereby consents to the exclusive jurisdiction of the
+state and federal courts located in San Francisco County, California to
+adjudicate any dispute arising out of or relating to these Terms of Use and
+the download, installation, and/or use of the Software. Except as expressly
+stated herein, these Terms of Use constitute the entire agreement between
+the parties, and supersede all prior and contemporaneous agreements,
+proposals, or representations, written or oral, concerning their subject
+matter. No modification, amendment, or waiver of any provision of these
+Terms of Use shall be effective unless it is by an update to these Terms of
+Use that Salesforce makes available, or is in writing and signed by the
+party against whom the modification, amendment, or waiver is to be
+asserted.
+
+Data Privacy: Salesforce may collect, process, and store device,
+system, and other information related to your use of the Software. This
+information includes, but is not limited to, IP address, user metrics, and
+other data ("Usage Data"). Salesforce may use Usage Data for analytics,
+product development, and marketing purposes. You acknowledge that files
+generated in conjunction with the Software may contain sensitive or
+confidential data, and you are solely responsible for anonymizing and
+protecting such data.

package/README.md

@@ -0,0 +1,193 @@
+# feature-angular-language-switcher
+
+A drop-in **language switcher** for **B2X** (public / Experience) Angular UI Bundles.
+
+Selecting a language rewrites the current URL so the chosen language becomes the
+**first path segment after `basePath`**, then reloads the page at that URL. A full
+reload lets the platform serve the correctly localized content — this feature owns
+_only_ the URL rewrite. It does not load translations, manage i18n state, or persist
+a preference.
+
+> **B2X only.** Do not add this feature to B2E (internal / `CustomApplication`) apps.
+> Those serve logged-in users whose language comes from their profile, and their
+> URLs have no language segment.
+
+## Usage
+
+Import `LanguageSwitcherComponent` and add it to the `imports` array in your
+component's `.ts` file (typically `app-layout.ts`), then place
+`<app-language-switcher />` in the corresponding `.html` template. It reads
+everything it needs from the URL and `SFDC_ENV`, so no inputs are required:
+
+**`app-layout.ts`**
+
+```typescript
+import { Component } from "@angular/core";
+import { LanguageSwitcherComponent } from ".../features/language-switcher";
+
+@Component({
+  selector: "app-layout",
+  standalone: true,
+  imports: [LanguageSwitcherComponent],
+  templateUrl: "./app-layout.html",
+})
+export class AppLayoutComponent {}
+```
+
+**`app-layout.html`**
+
+```html
+<nav>
+  <!-- ... -->
+  <app-language-switcher />
+</nav>
+```
+
+Optional inputs:
+
+- `label` — accessible label prefix for the dropdown trigger (default `"Language"`).
+
+The component renders as a **dropdown menu** (via `app-dropdown-menu`) with a globe
+icon, the current language label, and a chevron — not a plain `<select>`. It depends
+on the base app's shared `DropdownMenuImports` and `IconComponent` (inherited from
+`base-angular-app`), so those must be present in the app. The component uses
+`ChangeDetectionStrategy.OnPush` and Angular signals.
+
+> **Single-language sites render nothing.** When fewer than two languages are
+> configured in [`languages.ts`](#keeping-the-language-list-in-sync), the component
+> renders nothing — a one-option dropdown can't change anything, so showing it would
+> add an inert focus stop. The switcher appears only when there is a real choice to
+> make.
+
+## How the URL is rewritten
+
+Given `basePath` from `SFDC_ENV.basePath`, the leading path segment after it is
+handled by the chosen language:
+
+- **`DEFAULT_LANGUAGE`** is the implicit, un-prefixed language, so **no segment is
+  written**. An existing language segment is **removed** (`/shop/fr/page` →
+  `/shop/page`); a path with no language segment is left unchanged.
+- **Any other language** is **replaced** into an existing language segment (no
+  `/en-US/fr/page` stacking), or **inserted** when there is none.
+
+The rest of the path, the query string, and the hash are preserved.
+
+Locale codes use underscores (`en_US`), but the **URL path segment uses hyphens**
+(`en-US`). The switcher writes the hyphenated form and remaps it back to the
+underscore code when reading the current language from the URL.
+
+The table below assumes `DEFAULT_LANGUAGE = en_US`:
+
+| Before (`basePath = /shop`) | Pick    | After                       |
+| --------------------------- | ------- | --------------------------- |
+| `/shop/catalog?q=x#top`     | `fr`    | `/shop/fr/catalog?q=x#top`  |
+| `/shop/de-DE/catalog`       | `fr`    | `/shop/fr/catalog`          |
+| `/shop`                     | `fr`    | `/shop/fr`                  |
+| `/shop/fr/catalog?q=x#top`  | `en_US` | `/shop/catalog?q=x#top`     |
+| `/shop/catalog`             | `en_US` | `/shop/catalog` (unchanged) |
+
+Selecting the language that is already active is a no-op (no reload).
+
+## The current language
+
+Resolved in precedence order by `getCurrentLanguage()`:
+
+1. **`globalThis.SFDC_ENV.language`** — authoritative when the platform provides
+   it. The platform injects this in **hyphenated** form (e.g. `"en-US"`), so it is
+   remapped back to a locale code (`en_US`) before matching, exactly like the URL
+   segment.
+2. **The leading URL path segment after `basePath`**, remapped from hyphens back
+   to a locale code, when it is a supported language — so a direct hit on
+   `/shop/en-US/catalog` resolves to `en_US` even before the runtime populates
+   `SFDC_ENV.language`.
+3. **`DEFAULT_LANGUAGE`** — when neither of the above yields a supported code.
+
+Only codes present in `LANGUAGES` are honored; anything else falls through to the
+next step.
+
+> `SFDC_ENV` does not declare `language` in the platform types yet. This feature
+> ships an ambient augmentation (`src/types/globals.d.ts`) adding the optional
+> `language` field. The runtime populates it in dash form (e.g.
+> `"language":"en-US"`) — the platform converts the underscore locale code before
+> injecting it.
+
+## Local development
+
+On a deployed Experience site the platform injects `SFDC_ENV.language` and folds
+the active language into `SFDC_ENV.basePath` (e.g. `/shop/fr`), recomputing both
+from the URL on every load. The generic local Angular dev server does neither —
+`SFDC_ENV.language` is absent and `basePath` is always `/` — so the switcher
+can't route a non-default language locally (the reload 404s and labels never
+flip; only the default language works).
+
+This feature integrates with the **site** entry of
+`@salesforce/angular-plugin-ui-bundle`. Switch your `middleware/html.mjs` to import
+`createSiteHtmlMiddleware` and pass the supported `LANGUAGES`
+(a shipped `__examples__/html-middleware-site-example.ts` shows this):
+
+```ts
+// In your middleware/html.mjs, replace:
+//   import { createHtmlMiddleware } from "@salesforce/angular-plugin-ui-bundle";
+//   export default await createHtmlMiddleware();
+//
+// with:
+import { createSiteHtmlMiddleware } from "@salesforce/angular-plugin-ui-bundle";
+import { DEFAULT_LANGUAGE, LANGUAGES } from "../languages";
+
+export default await createSiteHtmlMiddleware({
+  languages: LANGUAGES.map((l) => l.code),
+  defaultLanguage: DEFAULT_LANGUAGE,
+});
+```
+
+The site middleware then, **for local dev only**, treats a leading URL segment that
+matches one of `LANGUAGES` as the active language — injecting `SFDC_ENV.language`
+and a matching `basePath`, and serving the language-prefixed path (SPA fallback).
+This mirrors production, so the switcher changes language live via URL + reload —
+**no server restart**.
+
+Then `npm run dev` and use the switcher normally: picking French navigates to
+`/fr`, Chinese to `/zh-CN`, and the default language drops the segment. This has
+**no effect on a deployed build**, and non-site bundles keep using the generic
+`@salesforce/angular-plugin-ui-bundle` import unchanged.
+
+## Keeping the language list in sync
+
+The supported languages are **hardcoded** in
+[`languages.ts`](./src/force-app/main/default/uiBundles/feature-angular-language-switcher/src/app/features/language-switcher/languages.ts)
+(`LANGUAGES` + `DEFAULT_LANGUAGE`). There is no runtime API to read
+`sfdc_cms__languageSettings` on a published site, so the list must be kept in sync
+**by hand** with the site's:
+
+```
+digitalExperiences/site/<siteName>/sfdc_cms__languageSettings/content.json
+```
+
+When the site's supported languages change, update `LANGUAGES` (and
+`DEFAULT_LANGUAGE`) to match.
+
+> **Unsupported languages are the app's responsibility.** The switcher only ever
+> writes codes from `LANGUAGES`, but nothing stops a URL from carrying a language
+> segment that is _not_ configured in `sfdc_cms__languageSettings` — a hand-typed
+> or stale link like `/shop/it-IT/catalog`, for example. The switcher does not
+> honor it (an unrecognized segment is not treated as a language, so
+> `getCurrentLanguage()` falls through to `DEFAULT_LANGUAGE`), but it also does not
+> strip or rewrite it — the segment stays in the URL and is served by the platform
+> and your Angular app like any other path. It is up to the app to handle such a URL
+> gracefully (e.g. redirect to a supported language or render a friendly
+> not-found state). If left unhandled, an unsupported language segment can surface
+> as a 404 / error page.
+
+## Public API
+
+| Export                      | Description                                                             |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `LanguageSwitcherComponent` | Standalone Angular component with dropdown menu trigger.                |
+| `getCurrentLanguage`        | Resolves the active language from `SFDC_ENV` with default fallback.     |
+| `buildLanguageUrl`          | Pure helper: inserts/replaces the leading language path segment.        |
+| `getLanguageFromUrl`        | Reads the language encoded in a URL's leading segment after `basePath`. |
+| `urlSegmentToCode`          | Converts a hyphenated URL segment back to a Salesforce locale code.     |
+| `LANGUAGES`                 | Typed list of supported languages (`{ code, label }`).                  |
+| `DEFAULT_LANGUAGE`          | Default language code.                                                  |
+| `LANGUAGE_CODES`            | `Set` of known codes for membership checks.                             |
+| `LanguageOption` _(type)_   | Interface for a single language entry (`{ code, label }`).              |

package/dist/.forceignore

@@ -0,0 +1,15 @@
+# List files or directories below to ignore them when running force:source:push, force:source:pull, and force:source:status
+# More information: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_exclude_source.htm
+#
+
+package.xml
+
+# LWC configuration files
+**/jsconfig.json
+**/.eslintrc.json
+
+# LWC Jest
+**/__tests__/**
+
+node_modules/
+.DS_Store

package/dist/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npm run precommit

package/dist/.prettierignore

@@ -0,0 +1,11 @@
+# List files or directories below to ignore them when running prettier
+# More information: https://prettier.io/docs/en/ignore.html
+#
+
+**/staticresources/**
+.localdevserver
+.sfdx
+.sf
+.vscode
+
+coverage/

package/dist/.prettierrc

@@ -0,0 +1,17 @@
+{
+  "trailingComma": "none",
+  "plugins": [
+    "prettier-plugin-apex",
+    "@prettier/plugin-xml"
+  ],
+  "overrides": [
+    {
+      "files": "**/lwc/**/*.html",
+      "options": { "parser": "lwc" }
+    },
+    {
+      "files": "*.{cmp,page,component}",
+      "options": { "parser": "html" }
+    }
+  ]
+}