@tribe-nest/forge 3.26.0 → 3.29.0

package/src/i18n/CONVENTION.md

@@ -0,0 +1,184 @@
+# Forge i18n convention
+
+> **`de.json` is machine-authored and has NOT been reviewed by a native speaker.**
+> Treat every German string as provisional. The initiative doc names this as a
+> real risk: a fan reading awkward or wrong copy at checkout is a conversion
+> problem, not a cosmetic one. A native review has to happen before any tenant
+> ships a German storefront.
+
+This file is the rule. Eight agents are converting components in parallel, so
+the naming has to be mechanical enough that two people who never spoke produce
+the same key for the same string.
+
+Spec: [`docs/proposals/i18n-initiative.md`](../../../../docs/proposals/i18n-initiative.md),
+Workstream 2, P0 and P1.
+
+## The import line
+
+Every component under `src/ui/styled/` uses exactly this:
+
+```ts
+import { useForgeT } from "../../i18n";
+```
+
+One directory deeper (`src/ui/styled/chat/`, `styled/work/`, `styled/members/`,
+`styled/community/`) it is `"../../../i18n"`. The rule is: a relative path to
+`src/i18n`, never a package self-import, never the `@/` alias. Sites consume
+this package from source, so a self-import would resolve here and break there.
+
+Call it at the top of the component, beside the other hooks:
+
+```tsx
+export function CartSummary() {
+  const t = useForgeT();
+  return <button>{t("forge.cart.checkout")}</button>;
+}
+```
+
+`t` is a plain function, not an object. Do not destructure anything off it.
+
+## The key shape
+
+```
+forge.<component>.<slug>
+```
+
+Exactly three segments, all lowercase.
+
+| Segment | Rule |
+|---|---|
+| `forge.` | Mandatory on every key, no exceptions. It is the namespace that makes a collision with a tenant's own copy impossible. |
+| `<component>` | The component file's name in `snake_case`, minus the extension. `CartSummary.tsx` gives `cart_summary`. `AiAgentWidget.tsx` gives `ai_agent_widget`. |
+| `<slug>` | What the string is for, in `snake_case`, 1 to 4 words. |
+
+```
+forge.cart_summary.checkout
+forge.cart_summary.empty_title
+forge.event_card.sold_out
+forge.booking_form.submit_error
+```
+
+Keys are **flat strings containing dots**, not nested objects. `en.json` is one
+level deep:
+
+```json
+{
+  "forge.cart_summary.checkout": "Checkout",
+  "forge.cart_summary.empty_title": "Your cart is empty"
+}
+```
+
+Flat is deliberate. Eight agents appending to two shared JSON files produce
+line-level conflicts that git resolves; nested objects produce structural
+conflicts that it does not.
+
+### Naming the slug
+
+Name it after the **meaning**, never the rendered English, and never the
+position.
+
+```
+NO   forge.cart_summary.your_cart_is_empty     (renames when the copy is edited)
+NO   forge.cart_summary.text_2                 (says nothing)
+NO   forge.cart_summary.bottom_button          (says where, not what)
+YES  forge.cart_summary.empty_title
+YES  forge.cart_summary.checkout
+```
+
+Conventional slugs, so the same concept lands on the same word everywhere:
+`title`, `subtitle`, `description`, `empty_title`, `empty_body`, `submit`,
+`cancel`, `retry`, `loading`, `error`, `success`, `confirm_title`,
+`confirm_body`, `aria_close`.
+
+### Shared strings
+
+A string used by several components is **not** hoisted to a `forge.common.*`
+bucket by default. Duplicate it under each component's namespace. Shared keys
+look like savings and turn into the thing nobody can safely edit, because the
+edit lands in four screens at once.
+
+The single exception is `forge.common.*`, reserved for strings whose wording is
+a product decision rather than a component's copy, and that decision is already
+recorded elsewhere. Do not add to it during the conversion pass without saying
+so in the PR.
+
+## Interpolation
+
+`{var}` placeholders, filled from the second argument:
+
+```json
+{ "forge.order_summary.item_count": "{count} items" }
+```
+
+```tsx
+t("forge.order_summary.item_count", { count: items.length })
+```
+
+Rules:
+
+- Placeholder names are `snake_case` and describe the value (`{count}`,
+  `{artist_name}`, `{date}`), never `{0}` or `{value}`.
+- A placeholder with no matching var is left standing as `{count}`. It is not
+  blanked, so an unfilled slot is visible in review.
+- **Never concatenate.** `t("forge.x.hello") + " " + name` cannot be translated,
+  because German puts the pieces in a different order. Put the whole sentence in
+  one key with a placeholder.
+- Numbers, currency and dates are formatted by the existing Forge formatters,
+  then passed in as a var. Do not build them out of translated fragments.
+
+## What does NOT get a key
+
+- Machine values: ids, slugs, enum values, URLs, query keys, `data-*`
+  attributes, CSS class names, analytics event names.
+- Values that come from the API. A product title is the tenant's content, not
+  Forge's copy, and translating it is a different feature.
+- Developer diagnostics no visitor reads (a `console.warn`, a thrown
+  programming error).
+
+Everything a visitor can read does get a key, including `aria-label`,
+`placeholder`, `title` and `alt` text. Those are the ones the conversion pass
+misses.
+
+## Adding a string
+
+1. Add the key to `en.json` with the exact English the component renders today.
+   Do not improve the copy in the same change. A translation pass that also
+   rewords is unreviewable.
+2. Add the same key to `de.json`. Never leave it out: a key present in `en` and
+   absent in `de` falls back to English, which reads as a half-translated page
+   rather than as an error.
+3. Replace the literal with `t("...")`.
+
+Both files stay sorted by key, so a diff is a diff and not a reshuffle.
+
+## The fallback chain
+
+`t(key)` resolves in this order:
+
+1. the active locale's bundle,
+2. the English bundle,
+3. the key string itself.
+
+It never returns empty. A missing key renders as `forge.cart_summary.checkout`
+on the page, which is ugly on purpose: an untranslated string should be visible,
+not invisible.
+
+Outside a `<ForgeI18nProvider>` the hook returns a working English translator
+instead of throwing, so a component still renders standalone. This mirrors
+`useFunnelStep`, which returns a working no-op outside a `<Funnel>` for the same
+reason.
+
+## Locales
+
+`en` and `de` only, and `en` is the source language. `resolveForgeLocale`
+narrows anything a site passes ("de-DE", "DE", `undefined`, "fr") to one of the
+two, defaulting to `en`. Adding a third locale means a third JSON file and one
+entry in `FORGE_LOCALES`.
+
+## Bundled, not fetched
+
+The JSON ships inside the package and is imported synchronously. There is no
+network call, no loading state and no API surface for translations. A site
+therefore picks up new or corrected copy on its next Forge upgrade. That
+adoption lag is accepted, because the always-latest initiative removes it for
+every package at once. See "Why bundle-only is safe" in the initiative doc.

package/src/i18n/_tests/translationKeys.spec.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+
+import en from "../en.json";
+import de from "../de.json";
+
+/**
+ * Every `forge.*` key a component references must exist in EVERY bundle.
+ *
+ * `translateForge` resolves a key through the active locale, then English, then
+ * the key string itself. That last step is deliberate (see CONVENTION.md, "The
+ * fallback chain"): a missing key must be visible rather than blank. But
+ * "visible" only helps if somebody looks. Nothing throws, nothing warns, and no
+ * component spec fails, so the failure mode of a typo is a fan reading
+ * `forge.cart.checkout` on a checkout button.
+ *
+ * The de-only half is quieter still. A key present in `en.json` and absent from
+ * `de.json` silently falls back to English, so a German storefront renders a
+ * page that is 90% German with an English button in the middle of it. There is
+ * no error anywhere. This spec is the only thing that reports it.
+ *
+ * ## Why the scanner matches string literals, not `t(` call sites
+ *
+ * The obvious scanner is `/t\(\s*"(forge\.[^"]+)"/`. It would miss most of the
+ * risk in this package, because Forge routinely reaches a key through a
+ * variable:
+ *
+ *     const TAB_LABELS = { orders: "forge.account_dashboard.tab_orders", ... };
+ *     tr(TAB_LABELS[tab])
+ *
+ *     t(isPaid ? "forge.bundle_confirmation.summary_paid" : "...summary_order")
+ *
+ * A key that reaches `t` through a lookup map or a ternary is exactly the key a
+ * rename breaks without tsc noticing, and it is exactly the key a call-site
+ * regex cannot see. So the scanner matches any `"forge.…"` string literal in
+ * the source, wherever it sits. It also makes the guard indifferent to what the
+ * translator is called at the call site: this package binds `useForgeT()` to
+ * `t`, `tr` and `translate` in different files, and a call-site regex would
+ * have to know all three.
+ *
+ * The cost is that a `forge.*` literal that is NOT a translation key would be
+ * flagged. Machine values never carry the `forge.` prefix (CONVENTION.md, "What
+ * does NOT get a key"), so that cost is theoretical, and a false positive here
+ * is a one-line fix while a false negative ships broken copy.
+ *
+ * `src/i18n/` itself is excluded from the walk: the `useForgeT` docblock shows
+ * `t("forge.cart.item_count", …)` as an EXAMPLE, and an example is not a usage.
+ * The bundles are imported directly rather than scanned for the same reason.
+ */
+
+/** `src`, two levels up from `src/i18n/_tests`. */
+const SRC = join(__dirname, "..", "..");
+
+/** The bundle files are flat `Record<string, string>` by convention. */
+const LOCALES: Record<string, Record<string, string>> = {
+  en: en as Record<string, string>,
+  de: de as Record<string, string>,
+};
+
+/** Any bundle key literal, wherever it appears. See the docblock above. */
+const KEY_LITERAL = /"(forge\.[a-zA-Z0-9_]+\.[a-zA-Z0-9_.]+)"/g;
+
+/** Forge interpolates single braces (`{count}`), not the `{{count}}` of i18next. */
+const PLACEHOLDER = /\{\s*([a-zA-Z0-9_]+)\s*\}/g;
+
+const walk = (dir: string, out: string[] = []): string[] => {
+  for (const entry of readdirSync(dir)) {
+    // `i18n` holds the bundles and the docblock example; `_tests` holds specs,
+    // which assert on rendered copy rather than on keys.
+    if (entry === "node_modules" || entry === "_tests" || entry === "i18n") continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else if (/\.tsx?$/.test(entry) && !/\.(spec|test|d)\.tsx?$/.test(entry)) out.push(full);
+  }
+  return out;
+};
+
+/** key -> the source files that name it, for a failure message worth reading. */
+const usedKeys = (): Map<string, string[]> => {
+  const found = new Map<string, string[]>();
+  for (const file of walk(SRC)) {
+    const text = readFileSync(file, "utf8");
+    for (const match of text.matchAll(KEY_LITERAL)) {
+      const key = match[1];
+      const where = found.get(key) ?? [];
+      where.push(file.replace(`${SRC}/`, ""));
+      found.set(key, where);
+    }
+  }
+  return found;
+};
+
+const placeholders = (value: unknown): string[] =>
+  typeof value === "string" ? [...value.matchAll(PLACEHOLDER)].map((m) => m[1]).sort() : [];
+
+describe("Forge i18n: every key a component uses exists in every bundle", () => {
+  const used = usedKeys();
+
+  it("finds a meaningful number of keys, so the scanner itself still works", () => {
+    // A regex that quietly stopped matching would make every assertion below
+    // pass vacuously. Pin a floor rather than an exact count, so adding copy
+    // does not fail the guard.
+    expect(used.size).toBeGreaterThan(500);
+  });
+
+  for (const [lang, bundle] of Object.entries(LOCALES)) {
+    it(`${lang}: no key used in src is missing from the bundle`, () => {
+      const missing = [...used.entries()]
+        .filter(([key]) => bundle[key] === undefined)
+        .map(([key, files]) => `${key}  <- ${[...new Set(files)].join(", ")}`);
+
+      expect(
+        missing,
+        `Missing ${lang} copy. translateForge would render the raw key to a visitor:\n${missing.join("\n")}`,
+      ).toEqual([]);
+    });
+  }
+
+  it("en.json and de.json carry the same key set", () => {
+    const enKeys = new Set(Object.keys(LOCALES.en));
+    for (const [lang, bundle] of Object.entries(LOCALES)) {
+      if (lang === "en") continue;
+      const missing = [...enKeys].filter((k) => bundle[k] === undefined);
+      const extra = Object.keys(bundle).filter((k) => !enKeys.has(k));
+
+      // Missing means a silent English fallback inside a translated page.
+      expect(missing, `${lang} is missing keys English has:\n${missing.join("\n")}`).toEqual([]);
+      // Extra means copy nobody can ever read, usually the residue of a rename
+      // applied to en.json alone.
+      expect(extra, `${lang} has keys English does not:\n${extra.join("\n")}`).toEqual([]);
+    }
+  });
+
+  it("no bundle disagrees with English about interpolation placeholders", () => {
+    // A `{count}` present in one locale and absent from another is a value that
+    // vanishes from the sentence for that locale only, and it renders as a
+    // grammatical sentence with the number missing, which reads as correct.
+    const mismatches: string[] = [];
+    for (const [lang, bundle] of Object.entries(LOCALES)) {
+      if (lang === "en") continue;
+      for (const [key, value] of Object.entries(LOCALES.en)) {
+        if (bundle[key] === undefined) continue;
+        const source = placeholders(value);
+        const target = placeholders(bundle[key]);
+        if (source.join(",") !== target.join(",")) {
+          mismatches.push(`${key}: en={${source.join(",")}} ${lang}={${target.join(",")}}`);
+        }
+      }
+    }
+    expect(mismatches, `Interpolation drift:\n${mismatches.join("\n")}`).toEqual([]);
+  });
+});