@ultimat3/i18n 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# 🌍 @ultimat3/i18n
+
+**Golden rule: no user-facing string is written twice, and a missing one is loud.**
+Every string goes through `t()`. A key with no translation renders `⟦key⟧` — never blank,
+never the English fallback, never silence. Numbers, dates and money are **not** i18n
+strings: format those with `Intl` via [@ultimat3/money](../money) and [@ultimat3/time](../time).
+
+| Concern | Owner | Rule |
+|---|---|---|
+| Registration | `define-catalogs.ts` | `defineCatalogs()` — one call, at boot, per app |
+| Lookup + interpolation | `translator.ts` | `t(key, vars?)`, miss → `⟦key⟧` |
+| Catalog shape | `catalog.ts` | nested authoring → flat dot-keys |
+| Placeholders + plurals | `interpolate.ts` | `{var}`, CLDR categories via `Intl.PluralRules` |
+| Locale resolution | `locales.ts` | supported set, `normalizeLocale`, `negotiateLocale` |
+| Request locale | `context.ts` | resolved once, read from ALS — never passed by hand |
+| Enforcement | `extract.ts` | `x verify` fails on a missing key in a shipped locale |
+
+## Declare the catalogs, once
+
+`defineCatalogs` is the only way an app registers strings. Never call `registerCatalog` by hand.
+
+```ts
+// the app's own packages/i18n/src/index.ts — its whole i18n module
+import { defineCatalogs, type TranslationKey, type Translator, useI18n } from '@ultimat3/i18n';
+import en from '../catalogs/en.json';
+import es from '../catalogs/es.json';
+
+export const catalogs = defineCatalogs({ default: 'en', locales: { en, es } });
+
+export type AppCatalog = typeof en;
+export type AppKey = TranslationKey<AppCatalog>; // 'nav.home' | 'posts.likes' | …
+export const useT = (): Translator<AppCatalog> => useI18n<AppCatalog>();
+```
+
+| One call | Because |
+|---|---|
+| validates + flattens every locale before registering any | a malformed catalog fails the boot whole, never half |
+| registers the framework catalog first, the app's second | later wins, so app strings override framework strings |
+| `configureLocales({ supported, fallback })` | the locale set is declared once, not twice |
+| returns `{ default, locales, catalogs, keys() }` | the app's key space, for tests and tooling |
+
+A `default` outside `locales` is `X_LOCALE_UNSUPPORTED` — and a compile error before that.
+
+## Read a string
+
+```ts
+import { negotiateLocale, t } from '@ultimat3/i18n';
+
+// per-request: the HTTP layer resolves the locale once
+const locale = negotiateLocale(request.headers.get('accept-language')); // 'de'
+
+// anywhere downstream — no locale argument, ever
+t('pagination.showing', { from: 1, to: 20, total: 137 });
+t('pagination.result', { count: 1 });   // "1 result"
+t('pagination.result', { count: 9 });   // "9 results"
+t('nav.settings');                      // "⟦nav.settings⟧" — fix it or ship it broken, visibly
+```
+
+| Call | Returns | Use for |
+|---|---|---|
+| `t(key, vars?)` | `string` | one string, framework or app, untyped keys |
+| `useI18n<AppCatalog>()` | `Translator<AppCatalog>` | a component rendering several — unknown key is a build error |
+| `translatorFor(locale)` | `Translator` | an explicit locale: mail, a worker tick, a preview |
+
+`Translator` with no type argument keeps taking any `string`, which is what `@ultimat3/ui` and
+`@ultimat3/mail` are built against. `has()` and `raw()` stay permissive on purpose — a probe for
+a key that may not exist is what they are for.
+
+## Plurals are CLDR, not `n === 1`
+
+Author two forms with `key` / `key_plural`, or all forms a locale needs with
+`key_<category>` where category is `zero | one | two | few | many | other`.
+
+```json
+{ "files": { "n_one": "{count} plik", "n_few": "{count} pliki", "n_many": "{count} plików" } }
+```
+
+`t('files.n', { count: 3 })` → `3 pliki`, `{ count: 5 }` → `5 plików`. Selection runs
+through `Intl.PluralRules`, so Polish, Russian and Arabic work without a special case.
+
+Suffixes are underscores on the leaf, never a nested `{ one, other }` branch: the runtime probes
+`files.n_few`, and `TranslationKey` admits the stem `files.n` for exactly the same reason.
+
+## Catalogs
+
+Author nested and feature-namespaced; `defineCatalogs` flattens to dot-keys and rejects a
+non-string leaf with `X_CATALOG_INVALID`. Registration order is framework then app — later
+wins, which is how an app overrides `errors.notFound.title` without forking the framework.
+
+`src/catalogs/en.json` ships the framework's own strings: `errors.*`, `auth.*`,
+`pagination.*`, `admin.*`, `validation.*`, `common.*`, `time.cron.*`.
+
+## Enforcement
+
+`extractKeys()` scans source for `t('...')` calls; `auditCatalogs()` reports keys used,
+keys missing per locale, and keys defined but never used; `assertCatalogsComplete()` is
+the `x verify` gate.
+
+```
+X_CATALOG_MISSING_KEYS: catalog is incomplete
+  cause: packages/i18n/catalogs/es.json is missing 2 key(s) used in source: admin.nav.jobs, common.save
+  fix:   x i18n sync es
+```
+
+## Errors
+
+| Code | When |
+|---|---|
+| `X_LOCALE_UNSUPPORTED` | a tag outside the supported set was asserted, or a `defineCatalogs` default that is not one of its locales |
+| `X_CATALOG_MISSING_KEYS` | a shipped locale lacks a key the source uses |
+| `X_CATALOG_INVALID` | non-string leaf, bad key segment, or a dotted/nested collision |
+
+## Why it exists
+
+Retrofitting i18n means touching every string in the app. Structuring for many locales on
+day one costs nothing; the loud-miss rule is what keeps it honest once there are two.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ultimat3/i18n",
+  "version": "1.0.0",
+  "description": "Dependency-free translator, catalog flattening, locale negotiation and loud missing-key rendering",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/i18n"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0"
+  }
+}

package/src/catalog.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Catalog shape only: nested authoring (`{ nav: { home: 'Home' } }`) → flat dot-key
+ * lookup (`nav.home`), plus merging framework strings under app strings.
+ */
+/** What authors write, and what `catalogs/<locale>.json` contains. */
+export type NestedCatalog = {
+    readonly [key: string]: string | NestedCatalog;
+};
+/** What the translator consumes: flat dot-keys → template strings. */
+export type Catalog = Readonly<Record<string, string>>;
+/**
+ * Depth-first flatten. Throws `X_CATALOG_INVALID` on a non-string leaf (arrays and
+ * numbers are the two mistakes translators actually make) or a duplicate flat key.
+ */
+export declare function flattenCatalog(source: NestedCatalog, prefix?: string): Catalog;
+/** Validate an untrusted value (a parsed JSON file) as a nested catalog. */
+export declare function parseNestedCatalog(value: unknown, path?: string): NestedCatalog;
+/** Parse + flatten in one step — the loader every catalog file goes through. */
+export declare function loadCatalog(value: unknown, prefix?: string): Catalog;
+/**
+ * Later catalogs win. Call order is framework strings first, app strings last, so an
+ * app can override `errors.notFound.title` without forking the framework catalog.
+ */
+export declare function mergeCatalogs(...catalogs: readonly Catalog[]): Catalog;
+export declare function catalogKeys(catalog: Catalog): string[];
+/** Keys present in `base` but absent from `target` — the extractor's diff primitive. */
+export declare function missingFrom(base: Catalog, target: Catalog): string[];
+//# sourceMappingURL=catalog.d.ts.map

package/src/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["catalog.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAA;CAAE,CAAC;AAE/E,sEAAsE;AACtE,MAAM,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAIvD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,SAAK,GAAG,OAAO,CAI1E;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAK,GAAG,aAAa,CAa3E;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,OAAO,CAEhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAStE;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAEtD;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAEpE"}

package/src/catalog.js

@@ -0,0 +1,81 @@
+/**
+ * Catalog shape only: nested authoring (`{ nav: { home: 'Home' } }`) → flat dot-key
+ * lookup (`nav.home`), plus merging framework strings under app strings.
+ */
+import { catalogInvalid } from './errors';
+const KEY_SEGMENT = /^[A-Za-z0-9_-]+$/;
+/**
+ * Depth-first flatten. Throws `X_CATALOG_INVALID` on a non-string leaf (arrays and
+ * numbers are the two mistakes translators actually make) or a duplicate flat key.
+ */
+export function flattenCatalog(source, prefix = '') {
+    const flat = {};
+    walk(source, prefix, flat);
+    return flat;
+}
+/** Validate an untrusted value (a parsed JSON file) as a nested catalog. */
+export function parseNestedCatalog(value, path = '') {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw catalogInvalid(path || '<root>', `expected an object, got ${describe(value)}`);
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const childPath = path === '' ? key : `${path}.${key}`;
+        if (!KEY_SEGMENT.test(key)) {
+            throw catalogInvalid(childPath, 'key segments must match /^[A-Za-z0-9_-]+$/');
+        }
+        if (typeof child === 'string')
+            continue;
+        parseNestedCatalog(child, childPath);
+    }
+    return value;
+}
+/** Parse + flatten in one step — the loader every catalog file goes through. */
+export function loadCatalog(value, prefix = '') {
+    return flattenCatalog(parseNestedCatalog(value), prefix);
+}
+/**
+ * Later catalogs win. Call order is framework strings first, app strings last, so an
+ * app can override `errors.notFound.title` without forking the framework catalog.
+ */
+export function mergeCatalogs(...catalogs) {
+    const merged = {};
+    for (const catalog of catalogs) {
+        for (const key of Object.keys(catalog)) {
+            const value = catalog[key];
+            if (value !== undefined)
+                merged[key] = value;
+        }
+    }
+    return merged;
+}
+export function catalogKeys(catalog) {
+    return Object.keys(catalog).sort();
+}
+/** Keys present in `base` but absent from `target` — the extractor's diff primitive. */
+export function missingFrom(base, target) {
+    return catalogKeys(base).filter((key) => !Object.hasOwn(target, key));
+}
+function walk(node, prefix, out) {
+    for (const [key, value] of Object.entries(node)) {
+        const path = prefix === '' ? key : `${prefix}.${key}`;
+        if (typeof value === 'string') {
+            if (Object.hasOwn(out, path)) {
+                throw catalogInvalid(path, 'duplicate key — a nested branch and a dotted key collide');
+            }
+            out[path] = value;
+            continue;
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            throw catalogInvalid(path, `expected a string or an object, got ${describe(value)}`);
+        }
+        walk(value, path, out);
+    }
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return `a ${typeof value}`;
+}
+//# sourceMappingURL=catalog.js.map

package/src/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["catalog.ts"],"names":[],"mappings":"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"}

package/src/catalog.ts

@@ -0,0 +1,132 @@
+/**
+ * Catalog shape only: nested authoring (`{ nav: { home: 'Home' } }`) → flat dot-key
+ * lookup (`nav.home`), plus merging framework strings under app strings.
+ */
+
+import { catalogInvalid } from './errors';
+
+/** What authors write, and what `catalogs/<locale>.json` contains. */
+export type NestedCatalog = { readonly [key: string]: string | NestedCatalog };
+
+/** What the translator consumes: flat dot-keys → template strings. */
+export type Catalog = Readonly<Record<string, string>>;
+
+const KEY_SEGMENT = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Depth-first flatten. Throws `X_CATALOG_INVALID` on a non-string leaf (arrays and
+ * numbers are the two mistakes translators actually make) or a duplicate flat key.
+ */
+export function flattenCatalog(source: NestedCatalog, prefix = ''): Catalog {
+  const flat: Record<string, string> = {};
+  walk(source, prefix, flat);
+  return flat;
+}
+
+/** Validate an untrusted value (a parsed JSON file) as a nested catalog. */
+export function parseNestedCatalog(value: unknown, path = ''): NestedCatalog {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw catalogInvalid(path || '<root>', `expected an object, got ${describe(value)}`);
+  }
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    const childPath = path === '' ? key : `${path}.${key}`;
+    if (!KEY_SEGMENT.test(key)) {
+      throw catalogInvalid(childPath, 'key segments must match /^[A-Za-z0-9_-]+$/');
+    }
+    if (typeof child === 'string') continue;
+    parseNestedCatalog(child, childPath);
+  }
+  return value as NestedCatalog;
+}
+
+/** Parse + flatten in one step — the loader every catalog file goes through. */
+export function loadCatalog(value: unknown, prefix = ''): Catalog {
+  return flattenCatalog(parseNestedCatalog(value), prefix);
+}
+
+/**
+ * `flattenCatalog`'s inverse: the authored shape a flat catalog is written back to disk as.
+ * A tool that writes `{ "nav.home": "Home" }` produces a file `parseNestedCatalog` then refuses —
+ * a dot is not a key segment — so anything that reads a catalog, edits it and writes it back has
+ * to come through here or it round-trips into `X_CATALOG_INVALID`.
+ *
+ * A key that would nest under a leaf (`nav` and `nav.home` in the same catalog) is the same
+ * branch/leaf collision `flattenCatalog` refuses in the other direction, reported as such.
+ *
+ * Every node is `Object.create(null)`, never `{}`, because a catalog is untrusted input read off
+ * disk: on a normal object `node['__proto__']` resolves to `Object.prototype` instead of reading
+ * as absent, so the key `__proto__.polluted` would walk into the prototype and write to it. A
+ * null-prototype node makes `__proto__` an ordinary segment — it nests and serializes like any
+ * other, and nothing outside this catalog can be reached from a key.
+ */
+export function nestCatalog(catalog: Catalog): NestedCatalog {
+  const root = Object.create(null) as Record<string, unknown>;
+  for (const key of catalogKeys(catalog)) {
+    const value = catalog[key];
+    if (value === undefined) continue;
+    const segments = key.split('.');
+    const leaf = segments.pop();
+    if (leaf === undefined) continue;
+    let node = root;
+    for (const segment of segments) {
+      const child = node[segment];
+      if (child === undefined) node[segment] = Object.create(null);
+      else if (typeof child !== 'object') {
+        throw catalogInvalid(key, 'duplicate key — a nested branch and a dotted key collide');
+      }
+      node = node[segment] as Record<string, unknown>;
+    }
+    if (typeof node[leaf] === 'object') {
+      throw catalogInvalid(key, 'duplicate key — a nested branch and a dotted key collide');
+    }
+    node[leaf] = value;
+  }
+  return root as NestedCatalog;
+}
+
+/**
+ * Later catalogs win. Call order is framework strings first, app strings last, so an
+ * app can override `errors.notFound.title` without forking the framework catalog.
+ */
+export function mergeCatalogs(...catalogs: readonly Catalog[]): Catalog {
+  const merged: Record<string, string> = {};
+  for (const catalog of catalogs) {
+    for (const key of Object.keys(catalog)) {
+      const value = catalog[key];
+      if (value !== undefined) merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+export function catalogKeys(catalog: Catalog): string[] {
+  return Object.keys(catalog).sort();
+}
+
+/** Keys present in `base` but absent from `target` — the extractor's diff primitive. */
+export function missingFrom(base: Catalog, target: Catalog): string[] {
+  return catalogKeys(base).filter((key) => !Object.hasOwn(target, key));
+}
+
+function walk(node: NestedCatalog, prefix: string, out: Record<string, string>): void {
+  for (const [key, value] of Object.entries(node)) {
+    const path = prefix === '' ? key : `${prefix}.${key}`;
+    if (typeof value === 'string') {
+      if (Object.hasOwn(out, path)) {
+        throw catalogInvalid(path, 'duplicate key — a nested branch and a dotted key collide');
+      }
+      out[path] = value;
+      continue;
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      throw catalogInvalid(path, `expected a string or an object, got ${describe(value)}`);
+    }
+    walk(value, path, out);
+  }
+}
+
+function describe(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `a ${typeof value}`;
+}

package/src/catalogs/en.json

@@ -0,0 +1,212 @@
+{
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "delete": "Delete",
+    "edit": "Edit",
+    "create": "Create",
+    "search": "Search",
+    "filter": "Filter",
+    "close": "Close",
+    "retry": "Try again",
+    "loading": "Loading…",
+    "empty": "Nothing here yet.",
+    "confirm": "Are you sure?",
+    "yes": "Yes",
+    "no": "No",
+    "copy": "Copy",
+    "copied": "Copied",
+    "signedInAs": "Signed in as {email}"
+  },
+  "errors": {
+    "notFound": {
+      "title": "Page not found",
+      "body": "We looked for {path} and came up empty.",
+      "action": "Back to safety"
+    },
+    "forbidden": {
+      "title": "Not allowed",
+      "body": "Your account can't do this. Ask an admin for the {permission} permission.",
+      "action": "Back"
+    },
+    "unauthorized": {
+      "title": "Please sign in",
+      "body": "This page needs an account.",
+      "action": "Sign in"
+    },
+    "serverError": {
+      "title": "Something broke on our side",
+      "body": "The error was recorded as {traceId}.",
+      "action": "Reload"
+    },
+    "offline": {
+      "title": "You're offline",
+      "body": "Changes are saved locally and will sync when you reconnect.",
+      "action": "Retry now"
+    },
+    "rateLimited": {
+      "title": "Too many requests",
+      "body": "Try again in {seconds} seconds.",
+      "action": "Wait"
+    },
+    "validation": {
+      "title": "Check the highlighted fields",
+      "count": "{count} field needs attention",
+      "count_plural": "{count} fields need attention"
+    }
+  },
+  "validation": {
+    "required": "Required",
+    "tooShort": "Use at least {min} characters",
+    "tooLong": "Use at most {max} characters",
+    "notEmail": "Enter a valid email address",
+    "notUrl": "Enter a valid URL",
+    "notNumber": "Enter a number",
+    "outOfRange": "Enter a value between {min} and {max}",
+    "mismatch": "Values don't match"
+  },
+  "auth": {
+    "signIn": {
+      "title": "Sign in",
+      "submit": "Sign in",
+      "email": "Email",
+      "password": "Password",
+      "forgot": "Forgot your password?",
+      "noAccount": "Don't have an account?",
+      "createAccount": "Create one",
+      "magicLink": "Email me a sign-in link",
+      "failed": "That email and password don't match."
+    },
+    "signUp": {
+      "title": "Create your account",
+      "submit": "Create account",
+      "name": "Name",
+      "haveAccount": "Already have an account?",
+      "terms": "By continuing you agree to the {termsLink}.",
+      "taken": "That email is already registered."
+    },
+    "resetPassword": {
+      "title": "Reset your password",
+      "submit": "Send reset link",
+      "sent": "Check {email} for a reset link.",
+      "newPassword": "New password",
+      "expired": "That link expired. Request a new one."
+    },
+    "verifyEmail": {
+      "title": "Verify your email",
+      "body": "We sent a code to {email}.",
+      "submit": "Verify",
+      "resend": "Resend code"
+    },
+    "twoFactor": {
+      "title": "Two-factor code",
+      "body": "Enter the 6-digit code from your authenticator app.",
+      "submit": "Verify",
+      "recovery": "Use a recovery code"
+    },
+    "signOut": "Sign out",
+    "session": {
+      "expired": "Your session expired. Sign in again.",
+      "current": "This device"
+    }
+  },
+  "pagination": {
+    "previous": "Previous",
+    "next": "Next",
+    "first": "First",
+    "last": "Last",
+    "page": "Page {page} of {pages}",
+    "showing": "Showing {from}–{to} of {total}",
+    "perPage": "{count} per page",
+    "result": "{count} result",
+    "result_plural": "{count} results",
+    "loadMore": "Load more",
+    "noMore": "That's everything."
+  },
+  "admin": {
+    "nav": {
+      "dashboard": "Dashboard",
+      "entities": "Data",
+      "actions": "Actions",
+      "jobs": "Jobs",
+      "tasks": "Schedules",
+      "queries": "Queries",
+      "policies": "Policies",
+      "users": "Users",
+      "settings": "Settings",
+      "logs": "Logs",
+      "traces": "Traces",
+      "migrations": "Migrations"
+    },
+    "dashboard": {
+      "title": "Dashboard",
+      "health": "Health",
+      "throughput": "Requests per minute",
+      "errorRate": "Error rate",
+      "latency": "p95 latency",
+      "queueDepth": "Queue depth",
+      "activeUsers": "Active users",
+      "since": "since {when}"
+    },
+    "jobs": {
+      "title": "Jobs",
+      "queued": "Queued",
+      "running": "Running",
+      "succeeded": "Succeeded",
+      "failed": "Failed",
+      "retrying": "Retrying",
+      "cancelled": "Cancelled",
+      "attempt": "Attempt {attempt} of {attempts}",
+      "nextRun": "Next run {when}",
+      "retryNow": "Retry now",
+      "cancel": "Cancel job",
+      "step": "Step {name}",
+      "pending": "{count} job waiting",
+      "pending_plural": "{count} jobs waiting"
+    },
+    "tasks": {
+      "title": "Schedules",
+      "cron": "Cron",
+      "timezone": "Timezone",
+      "lastRun": "Last run",
+      "nextRun": "Next run",
+      "runNow": "Run now",
+      "pause": "Pause",
+      "resume": "Resume"
+    },
+    "entities": {
+      "title": "Data",
+      "rows": "{count} row",
+      "rows_plural": "{count} rows",
+      "newRecord": "New {entity}",
+      "deleteRecord": "Delete this {entity}?",
+      "noResults": "No {entity} matched that filter."
+    },
+    "table": {
+      "sortAscending": "Sort ascending",
+      "sortDescending": "Sort descending",
+      "columns": "Columns",
+      "selected": "{count} selected",
+      "selectAll": "Select all",
+      "clearSelection": "Clear selection"
+    }
+  },
+  "time": {
+    "cron": {
+      "everyMinute": "every minute",
+      "everyNMinutes": "every {n} minutes",
+      "everyHour": "every hour",
+      "everyNHours": "every {n} hours",
+      "at": "at {time}",
+      "onDaysOfMonth": "on day {days}",
+      "onWeekdays": "on {days}",
+      "inMonths": "in {months}",
+      "everyDay": "every day",
+      "and": "and",
+      "invalid": "not a valid cron expression"
+    },
+    "relative": {
+      "now": "just now"
+    }
+  }
+}