WEBDEV-9226: Set up string extraction and publish locale data

README.md

@@ -303,6 +303,38 @@ For any styles that you won't be exposing to consumers via the story, you can pr
 </div>
 ```
 
+### 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.
+
+- Decorate any element that renders a `msg()` with `@localized()`, so it re-renders when the app switches language. That includes one rendering a getter that calls `msg()`, like `TranscriptEntryConfig.displayText`.
+- Don't resolve `msg()` ahead of render. At module scope or in a static field it's fixed at import, and as a property default it's fixed when the element is created. For a text property with a default, leave the property unset and fall back when rendering: `aria-label=${this.label ?? msg('Search')}`.
+
+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:
+
+```zsh
+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/elements/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.
+
+To merge it, an app spreads it under its own templates, app last so the app wins a conflict:
+
+```ts
+import { templates as elements } from '@internetarchive/elements/locales/es.js';
+import { templates as app } from './app-es';
+
+export const templates = { ...elements, ...app };
+```
+
+The XLIFF in `xliff/` is where translations are edited. It isn't published.
+
 ## Component Inventory
 
 To kickstart our library, we are going to take inventory of what already exists

eslint.config.mjs

@@ -62,7 +62,18 @@ export default [
     },
   },
   {
-    ignores: ['**/*.js', '**/*.mjs', '**/*.d.ts', '.claude/', '.wireit/'],
+    ignores: [
+      '**/*.js',
+      '**/*.mjs',
+      '**/*.d.ts',
+      '.claude/',
+      '.wireit/',
+      // Generated by `pnpm run strings:build`. Its eslint-disable comments go
+      // unused, so `eslint --fix` would strip them and leave the file out of
+      // step with what the build writes.
+      'src/locales/*.ts',
+      '!src/locales/*.test.ts',
+    ],
   },
   {
     files: ['**/*.test.ts'],

lit-localize.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://raw.githubusercontent.com/lit/lit/main/packages/localize-tools/config.schema.json",
+  "sourceLocale": "en",
+  "targetLocales": ["es"],
+  "tsConfig": "./tsconfig.json",
+  "inputFiles": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*-story.ts",
+    "!src/locales/**"
+  ],
+  "output": {
+    "outputDir": "src/locales",
+    "mode": "runtime"
+  },
+  "interchange": {
+    "format": "xliff",
+    "xliffDir": "./xliff"
+  }
+}

package.json

@@ -29,7 +29,9 @@
     "circular": "wireit",
     "prepare": "wireit",
     "test": "wireit",
-    "ghpages:build": "wireit"
+    "ghpages:build": "wireit",
+    "strings:extract": "wireit",
+    "strings:build": "wireit"
   },
   "dependencies": {
     "@internetarchive/ia-clearable-text-input": "^1.1.1",
@@ -43,6 +45,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.5",
     "@eslint/js": "^9.39.1",
+    "@lit/localize-tools": "^0.8.2",
     "@open-wc/testing-helpers": "^3.0.1",
     "@typescript-eslint/eslint-plugin": "^8.46.4",
     "@typescript-eslint/parser": "^8.46.4",
@@ -70,7 +73,8 @@
   },
   "exports": {
     "./*": "./dist/src/elements/*.js",
-    "./labs/*": "./dist/src/labs/*.js"
+    "./labs/*": "./dist/src/labs/*.js",
+    "./locales/*.js": "./dist/src/locales/*.js"
   },
   "files": [
     "README.md",
@@ -132,6 +136,24 @@
     },
     "ghpages:build": {
       "command": "vite build --config vite.config.ghpages.ts && touch ./ghpages/.nojekyll"
+    },
+    "strings:extract": {
+      "command": "lit-localize extract",
+      "files": [
+        "src/**/*.ts",
+        "lit-localize.json",
+        "tsconfig.json"
+      ]
+    },
+    "strings:build": {
+      "command": "node scripts/build-locales.mts && prettier --write \"src/locales/*.ts\"",
+      "files": [
+        "xliff/*.xlf",
+        "src/**/*.ts",
+        "!src/locales/*.ts",
+        "lit-localize.json",
+        "scripts/build-locales.mts"
+      ]
     }
   }
 }