@stacksjs/stx 0.2.37 → 0.2.39

package/dist/site-builder/i18n.d.ts

@@ -0,0 +1,75 @@
+import type { SiteConfig, SiteI18nOptions } from './types';
+export type { SiteI18nOptions };
+/**
+ * Resolve i18n config into the runtime shape used by the build.
+ *
+ * Translations are merged from two sources, in priority order:
+ *   1. `i18n.translations[<locale>]` — inline strings from `site.config.ts`
+ *   2. `<translationsDir>/<locale>.<format>` on disk — JSON or YAML files
+ *
+ * Inline strings win on key conflicts, so config-level overrides don't
+ * require editing the shared translation files. Missing locales/files
+ * are silently tolerated; the file loader returns `{}` for anything it
+ * can't read so the default locale's table can still serve as a
+ * fallback at translate-time.
+ */
+export declare function resolveI18n(site: SiteConfig, projectRoot?: string): ResolvedI18n | null;
+/**
+ * Translate a key for a locale, falling back to the default locale's
+ * value, then to the key itself. The fallback chain keeps prototypes
+ * shippable even when only a subset of strings is translated.
+ */
+export declare function translate(i18n: ResolvedI18n, locale: string, key: string): string;
+/**
+ * Replace `{t:key}` markers in HTML with the translated string for
+ * the given locale. The key syntax sidesteps stx's `{{ ... }}`
+ * templating (which evaluates as JS at build time and would render
+ * `t(...)` calls as empty when no `t` binding exists in scope).
+ *
+ * Keys may use letters, digits, `_`, `.`, `-`. Anything that doesn't
+ * match the pattern is left alone — runs after stx has finished its
+ * own templating pass.
+ */
+export declare function applyTranslations(html: string, i18n: ResolvedI18n, locale: string): string;
+/**
+ * URL path for a built page in the given locale.
+ *
+ * - `/` stays `/` for the default locale; for non-default locales it
+ *   becomes `/<code>/` (with the trailing slash). The slash matters
+ *   because most static hosts (S3+CloudFront, GitHub Pages, etc.)
+ *   only serve the directory's `index.html` when the URL ends in `/`
+ *   — `/de` 404s, `/de/` resolves. Linking with the slash avoids a
+ *   client-side redirect dance and lets SPA hops succeed without
+ *   falling back to a full page load.
+ * - `/about` becomes `/<code>/about` for non-default locales (no
+ *   trailing slash — those map to `<code>/about.html`).
+ * - `/404.html` keeps its filename and lives under the locale prefix.
+ */
+export declare function localizePath(path: string, locale: string, defaultLocale: string): string;
+/**
+ * Reverse of `localizePath`: strip a locale prefix off a path so we
+ * can compute the equivalent path in another locale.
+ */
+export declare function stripLocalePrefix(path: string, locales: string[]): { locale: string | null, path: string };
+/**
+ * `<link rel="alternate" hreflang>` block + `<link rel="canonical">`
+ * for the page being rendered. Search engines treat each as the
+ * authoritative copy for its locale.
+ */
+export declare function buildAlternateLinks(siteUrl: string, pagePath: string, i18n: ResolvedI18n): string;
+/**
+ * Inline script that wires up the language picker.
+ *
+ * Per-page logic: each `<button data-lang="…">` inside the configured
+ * picker selector navigates to the equivalent path in the chosen
+ * locale, using the locale list shipped in `window.__stxI18n`. Marks
+ * the active button with `aria-current="true"` for styling.
+ */
+export declare function buildLangPickerScript(i18n: ResolvedI18n, currentLocale: string): string;
+export declare interface ResolvedI18n {
+  locales: string[]
+  defaultLocale: string
+  labels: Record<string, string>
+  translations: Record<string, Record<string, string>>
+  pickerSelector: string
+}

package/dist/site-builder/index.d.ts

@@ -2,6 +2,7 @@ export type {
   BuildOptions,
   PageMeta,
   SiteConfig,
+  SiteI18nOptions,
   SiteRouterOptions,
   SiteSeo,
   SiteSocial,
@@ -13,3 +14,12 @@ export { generateSitemap, type SitemapEntry } from './sitemap';
 export { generateRobots } from './robots';
 export { injectRouterScript, type RouterOptions } from './router';
 export { injectThemeBootstrap, type ThemeOptions } from './theme';
+export {
+  applyTranslations,
+  buildAlternateLinks,
+  buildLangPickerScript,
+  localizePath,
+  resolveI18n,
+  stripLocalePrefix,
+  translate,
+} from './i18n';

package/dist/site-builder/types.d.ts

@@ -31,6 +31,16 @@ export declare interface SiteConfig {
   spa?: boolean
   router?: SiteRouterOptions
   theme?: false | SiteThemeOptions
+  i18n?: SiteI18nOptions
+}
+export declare interface SiteI18nOptions {
+  locales: string[]
+  labels?: Record<string, string>
+  defaultLocale?: string
+  translations?: Record<string, Record<string, string>>
+  translationsDir?: string | false
+  format?: 'json' | 'yaml' | 'yml'
+  pickerSelector?: string
 }
 export declare interface SiteThemeOptions {
   default?: 'dark' | 'light' | 'auto'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/stx",
   "type": "module",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "description": "A performant UI Framework. Powered by Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -121,7 +121,7 @@
     "@stacksjs/ts-craft": "^0.0.2",
     "bun-plugin-stx": "0.2.35",
     "bunfig": "^0.15.6",
-    "stx-router": "0.2.36",
+    "stx-router": "0.2.38",
     "ts-broadcasting": "^0.0.4",
     "ts-syntax-highlighter": "^0.2.1"
   }