npm - @rimelight/i18n - Versions diffs - 0.0.3 → 0.0.5 - Mend

@rimelight/i18n 0.0.3 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +19 -0
package/package.json +31 -7
package/src/env.d.ts +13 -0
package/src/index.ts +46 -15
package/src/integration.ts +102 -33
package/src/middleware/kv.ts +1 -1
package/src/middleware/routing.ts +22 -9
package/src/middleware.ts +1 -1
package/src/runtime.ts +316 -0
package/src/utils.ts +3 -2
package/src/virtual.d.ts +9 -2

package/README.md ADDED Viewed

@@ -0,0 +1,19 @@
+# Rimelight Entertainment Workspace
+## Structure
+### Apps (`/packages`)
+- **`rimelight.com`**: The main company website.
+- **`starter.rimelight.com`**: Our standardized starter template for Astro websites.
+### Packages (`/packages`)
+- **`@rimelight/auth`**: Authentication and authorization utilities for the Rimelight ecosystem.
+- **`@rimelight/cli`**: The command line interface for managing Rimelight projects.
+- **`@rimelight/cms`**: Enterprise content management, block rendering, and wiki engine.
+- **`@rimelight/docs`**: Documentation components and utilities.
+- **`@rimelight/i18n`**: Internationalization and localization tools.
+- **`@rimelight/security`**: Astro security integration (CSP, SRI, and more).
+- **`@rimelight/seo`**: SEO utilities including sitemap, robots, and meta components.
+- **`@rimelight/ui`**: Our component library used in all our web projects.

package/package.json CHANGED Viewed

@@ -1,8 +1,20 @@
 {
   "name": "@rimelight/i18n",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "private": false,
-  "description": "Rimelight i18n — unified translation loader with optional KV backing",
+  "description": "Rimelight Entertainment's Internationalization Package",
+  "homepage": "https://rimelight.com/docs",
+  "bugs": {
+    "url": "https://github.com/Rimelight-Entertainment/rimelight/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Rimelight Entertainment"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rimelight-Entertainment/rimelight.git"
+  },
   "files": [
     "src"
   ],
@@ -11,23 +23,35 @@
     ".": "./src/index.ts",
     "./integration": "./src/integration.ts",
     "./middleware": "./src/middleware.ts",
+    "./runtime": "./src/runtime.ts",
     "./types": "./src/types.ts",
     "./utils": "./src/utils.ts"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "check": "node -e \"process.exit(0)\""
+    "check": "pnpm audit --audit-level=moderate && vp check --fix"
   },
   "dependencies": {
     "@nanostores/i18n": "1.3.3",
-    "astro-nanostores-i18n": "0.7.0",
-    "nanostores": "1.3.0"
+    "nanostores": "1.5.1"
+  },
+  "devDependencies": {
+    "@rimelight/config": "workspace:*",
+    "astro": "7.2.2",
+    "typescript": "6.0.3"
   },
   "peerDependencies": {
-    "astro": ">=6.0.0"
+    "astro": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "astro": {
       "optional": true
     }
-  }
+  },
+  "engines": {
+    "node": ">=26.7.0"
+  },
+  "packageManager": "pnpm@11.22.0"
 }

package/src/env.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+// Enables importing .astro components inside .ts files (e.g., email rendering)
+declare module "*.astro" {
+  export default {} as import("astro/runtime/server").AstroComponentFactory
+}
+declare module "astro:i18n" {
+  export function getRelativeLocaleUrl(locale: string, path?: string): string
+  export function getAbsoluteLocaleUrl(locale: string, path?: string): string
+}
+declare module "@rimelight/i18n:runtime" {
+  export * from "./runtime"
+}

package/src/index.ts CHANGED Viewed

@@ -3,63 +3,86 @@ import type { ComponentsJSON, KVNamespaceBinding } from "./types"
 import {
   useI18n as baseUseI18n,
   useI18nAsync as baseUseI18nAsync,
+  t,
   currentLocale,
   useFormat,
   clearCache,
   getI18nInstance,
   getFormatterInstance
-} from "astro-nanostores-i18n:runtime"
+} from "@rimelight/i18n:runtime"
 import type { Translations } from "@nanostores/i18n"
-export { currentLocale, useFormat, clearCache, getI18nInstance, getFormatterInstance }
+export { t, currentLocale, useFormat, clearCache, getI18nInstance, getFormatterInstance }
+export interface ComponentMessages {
+  [key: string]: string
+}
+export function useI18n(componentName: string): ComponentMessages
 export function useI18n<Body extends Translations>(
   componentName: string,
   baseTranslations: Body
-): Body
+): ComponentMessages & Body
+export function useI18n(
+  astro: { currentLocale?: string | undefined; params?: Record<string, any> } | undefined | null,
+  componentName: string
+): ComponentMessages
 export function useI18n<Body extends Translations>(
-  astro: { currentLocale?: string | undefined } | undefined | null,
+  astro: { currentLocale?: string | undefined; params?: Record<string, any> } | undefined | null,
   componentName: string,
   baseTranslations: Body
-): Body
-export function useI18n(arg1: any, arg2: any, arg3?: any): any {
+): ComponentMessages & Body
+export function useI18n(arg1: any, arg2?: any, arg3?: any): any {
   if (typeof arg1 === "string") {
     return baseUseI18n(arg1, arg2)
   } else {
-    const activeLocale = arg1?.currentLocale ?? "en"
-    currentLocale.set(activeLocale)
+    const locale = arg1?.currentLocale || arg1?.params?.locale
+    if (locale) {
+      currentLocale.set(locale)
+    }
     return baseUseI18n(arg2, arg3)
   }
 }
+export function useI18nAsync(componentName: string): Promise<Record<string, string>>
 export function useI18nAsync<Body extends Translations>(
   componentName: string,
   baseTranslations: Body
-): Promise<Body>
+): Promise<Record<string, string> & Body>
+export function useI18nAsync(
+  astro: { currentLocale?: string | undefined; params?: Record<string, any> } | undefined | null,
+  componentName: string
+): Promise<Record<string, string>>
 export function useI18nAsync<Body extends Translations>(
-  astro: { currentLocale?: string | undefined } | undefined | null,
+  astro: { currentLocale?: string | undefined; params?: Record<string, any> } | undefined | null,
   componentName: string,
   baseTranslations: Body
-): Promise<Body>
-export function useI18nAsync(arg1: any, arg2: any, arg3?: any): any {
+): Promise<Record<string, string> & Body>
+export function useI18nAsync(arg1: any, arg2?: any, arg3?: any): any {
   if (typeof arg1 === "string") {
     return baseUseI18nAsync(arg1, arg2)
   } else {
-    const activeLocale = arg1?.currentLocale ?? "en"
-    currentLocale.set(activeLocale)
+    const locale = arg1?.currentLocale || arg1?.params?.locale
+    if (locale) {
+      currentLocale.set(locale)
+    }
     return baseUseI18nAsync(arg2, arg3)
   }
 }
 import { getRelativeLocaleUrl as astroGetRelativeLocaleUrl } from "astro:i18n"
+export function getLocale(): string {
+  return currentLocale.get() || "en"
+}
 export function getRelativeLocaleUrl(path: string): string
 export function getRelativeLocaleUrl(locale: string, path: string): string
 export function getRelativeLocaleUrl(arg1: string, arg2?: string): string {
   if (arg2 !== undefined) {
     return astroGetRelativeLocaleUrl(arg1, arg2)
   } else {
-    const locale = currentLocale.get() || "en"
+    const locale = getLocale()
     return astroGetRelativeLocaleUrl(locale, arg1)
   }
 }
@@ -110,3 +133,11 @@ export function createTranslationLoader(
     return Object.assign({}, ...results)
   }
 }
+/**
+ * Returns the plural category (e.g. 'one', 'few', 'many', 'other') for a given number and locale
+ * using the native browser Intl.PluralRules API.
+ */
+export function getPluralCategory(count: number, locale: string = "en"): Intl.LDMLPluralRule {
+  return new Intl.PluralRules(locale).select(count)
+}

package/src/integration.ts CHANGED Viewed

@@ -1,4 +1,3 @@
-import nanostoresI18n from "astro-nanostores-i18n"
 import type { AstroIntegration } from "astro"
 import fs from "node:fs"
 import path from "node:path"
@@ -10,23 +9,38 @@ export interface RimelightI18nOptions {
   translationLoader?: string
 }
-export function rimelightI18n(options?: RimelightI18nOptions): any {
+export function rimelightI18n(options?: RimelightI18nOptions): AstroIntegration[] {
   const validateExtraction = options?.validateExtraction ?? true
   const translations = options?.translations
   const kvBinding = options?.kvBinding ?? "TRANSLATIONS_KV"
-  const translationLoader = options?.translationLoader ?? "./src/i18n/loader.ts"
+  const translationLoader = options?.translationLoader
-  const nanostoresTranslations: Record<string, any> = {}
+  // Normalise translations passed in options
+  const normalisedTranslations: Record<string, any> = {}
   if (translations) {
     for (const [locale, val] of Object.entries(translations)) {
-      if (locale === "pt") {
-        nanostoresTranslations["pt-br"] = val
-      } else {
-        nanostoresTranslations[locale] = val
-      }
+      normalisedTranslations[locale] = val
     }
   }
+  // ---------- Vite virtual module: @rimelight/i18n:runtime ----------
+  // This replicates what astro-nanostores-i18n integration.js used to do:
+  // it creates a virtual module that calls initializeI18n() once at module
+  // evaluation time and re-exports all runtime helpers.
+  const VIRTUAL_MODULE_ID = "@rimelight/i18n:runtime"
+  const RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID
+  // Use the package export specifier so Vite resolves it through normal
+  // module resolution rather than an absolute filesystem path.
+  const runtimeSpecifier = "@rimelight/i18n/runtime"
+  const loaderImport = translationLoader
+    ? `import translationLoader from ${JSON.stringify(translationLoader)};`
+    : ""
+  const loaderOption = translationLoader ? ", get: translationLoader" : ""
+  // ----------------------------------------------------------------
   const rimelightI18nCore: AstroIntegration = {
     name: "@rimelight/i18n",
     hooks: {
@@ -34,22 +48,50 @@ export function rimelightI18n(options?: RimelightI18nOptions): any {
         const locales = config.i18n?.locales ?? ["en"]
         const defaultLocale = config.i18n?.defaultLocale ?? "en"
+        const virtualModuleContent = `\
+import { initializeI18n, useFormat, useI18n, useI18nAsync, t,
+         currentLocale, getI18nInstance, getFormatterInstance, clearCache }
+  from ${JSON.stringify(runtimeSpecifier)};
+${loaderImport}
+initializeI18n({
+  defaultLocale: ${JSON.stringify(defaultLocale)},
+  translations: ${JSON.stringify(normalisedTranslations)}${loaderOption}
+});
+export { useFormat, useI18n, useI18nAsync, t, currentLocale,
+         getI18nInstance, getFormatterInstance, clearCache };
+`
         addMiddleware({
           entrypoint: "@rimelight/i18n/middleware",
           order: "pre"
         })
         updateConfig({
           vite: {
             ssr: {
               noExternal: ["@rimelight/i18n"]
             },
             plugins: [
+              // Virtual module: @rimelight/i18n:runtime
+              {
+                name: "vite-plugin-rimelight-i18n-runtime",
+                resolveId(id) {
+                  if (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_MODULE_ID
+                  return null
+                },
+                load(id) {
+                  if (id === RESOLVED_VIRTUAL_MODULE_ID) return virtualModuleContent
+                  return null
+                }
+              },
+              // Virtual module: virtual:rimelight-i18n-config (locale metadata)
               {
                 name: "vite-plugin-rimelight-i18n-config",
                 resolveId(id) {
-                  if (id === "virtual:rimelight-i18n-config") {
-                    return "\0" + id
-                  }
+                  if (id === "virtual:rimelight-i18n-config") return "\0" + id
+                  return null
                 },
                 load(id) {
                   if (id === "\0virtual:rimelight-i18n-config") {
@@ -58,15 +100,46 @@ export function rimelightI18n(options?: RimelightI18nOptions): any {
                       export const defaultLocale = ${JSON.stringify(defaultLocale)};
                     `
                   }
+                  return null
                 }
               }
             ]
           }
         })
         if (validateExtraction) {
           logger.info("i18n extraction validation active")
         }
       },
+      "astro:config:done": ({ injectTypes }) => {
+        // Inject ambient type declarations for the virtual module so TypeScript
+        // and editor tooling know the shape of @rimelight/i18n:runtime.
+        injectTypes({
+          filename: "rimelight-i18n.d.ts",
+          content: `\
+declare module "@rimelight/i18n:runtime" {
+  import type { Translations } from '@nanostores/i18n';
+  export type { InitializeI18nOptions } from '@rimelight/i18n/runtime';
+  export const currentLocale: import('nanostores').PreinitializedWritableAtom<string> & object;
+  export declare function initializeI18n(options: import('@rimelight/i18n/runtime').InitializeI18nOptions): void;
+  export declare function useFormat(): import('@nanostores/i18n').Formatter;
+  export type ComponentMessages = Record<string, string>;
+  export declare function useI18n(componentName: string): ComponentMessages;
+  export declare function useI18n<Body extends Translations>(componentName: string, baseTranslations: Body): ComponentMessages & Body;
+  export declare function useI18nAsync(componentName: string): Promise<Record<string, string>>;
+  export declare function useI18nAsync<Body extends Translations>(componentName: string, baseTranslations: Body): Promise<Record<string, string> & Body>;
+  export declare function t(key: string, params?: Record<string, any>): string;
+  export declare function t(astro: { currentLocale?: string | undefined; params?: Record<string, any> } | undefined | null, key: string, params?: Record<string, any>): string;
+  export declare function getLocale(): string;
+  export declare function getI18nInstance(): ReturnType<typeof import('@nanostores/i18n').createI18n>;
+  export declare function getFormatterInstance(): ReturnType<typeof import('@nanostores/i18n').formatter>;
+  export declare function clearCache(locale?: string): void;
+}
+`
+        })
+      },
       "astro:build:done": async ({ logger }) => {
         if (translations) {
           const seedData: { keys: { key: string; value: string }[] } = { keys: [] }
@@ -84,19 +157,22 @@ export function rimelightI18n(options?: RimelightI18nOptions): any {
           fs.writeFileSync(seedFile, JSON.stringify(seedData, null, 2))
           logger.info(`translations seed file written to ${seedFile}`)
-          try {
-            const { execSync } = await import("node:child_process")
-            execSync(`npx wrangler kv:bulk put --binding "${kvBinding}" "${seedFile}"`, {
-              stdio: "pipe",
-              timeout: 30_000
-            })
-            logger.info(`KV "${kvBinding}" seeded with translations`)
-          } catch {
-            logger.warn(
-              `could not seed KV automatically — run ` +
-                `"npx wrangler kv:bulk put --binding "${kvBinding}" "${seedFile}"" ` +
-                `to seed translations into KV`
-            )
+          const autoSeed = process.env.WRANGLER_SEED_KV === "true" || process.env.CI === "true"
+          if (autoSeed) {
+            try {
+              const { execSync } = await import("node:child_process")
+              execSync(`npx wrangler kv:bulk put --binding "${kvBinding}" "${seedFile}"`, {
+                stdio: "pipe",
+                timeout: 30_000
+              })
+              logger.info(`KV "${kvBinding}" seeded with translations`)
+            } catch {
+              logger.warn(
+                `could not seed KV automatically — run ` +
+                  `"npx wrangler kv:bulk put --binding "${kvBinding}" "${seedFile}"" ` +
+                  `to seed translations into KV`
+              )
+            }
           }
         } else {
           logger.info("i18n build complete (no translations to seed)")
@@ -105,12 +181,5 @@ export function rimelightI18n(options?: RimelightI18nOptions): any {
     }
   }
-  return [
-    nanostoresI18n({
-      translationLoader,
-      addMiddleware: false,
-      translations: nanostoresTranslations
-    }),
-    rimelightI18nCore
-  ]
+  return [rimelightI18nCore]
 }

package/src/middleware/kv.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 import { setKVBinding } from "../index"
 import { env } from "cloudflare:workers"
-export const onRequest = async (context: any, next: any) => {
+export const onRequest = async (_context: unknown, next: () => Promise<Response>) => {
   const kv = Reflect.get(env, "TRANSLATIONS_KV")
   if (kv) {
     setKVBinding(kv)

package/src/middleware/routing.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import { locales, defaultLocale } from "virtual:rimelight-i18n-config"
+import { currentLocale } from "../runtime"
 const SUPPORTED_LOCALES = new Set(locales)
 const DEFAULT_LOCALE = defaultLocale
@@ -10,13 +11,14 @@ function getPreferredLocale(acceptLanguage: string | null): string {
     .split(",")
     .map((lang) => {
       const parts = lang.split(";")
-      const code = parts[0].trim().toLowerCase()
-      const base = code.split("-")[0]
+      const code = (parts[0] ?? "").trim().toLowerCase()
+      const base = code.split("-")[0] ?? ""
       let q = 1.0
-      if (parts[1]) {
-        const qMatch = parts[1].match(/q=([0-9.]+)/)
+      const qualityPart = parts[1]
+      if (qualityPart) {
+        const qMatch = qualityPart.match(/q=([0-9.]+)/)
         if (qMatch) {
-          q = parseFloat(qMatch[1])
+          q = parseFloat(qMatch[1] ?? "1")
         }
       }
       return { code, base, q }
@@ -27,8 +29,9 @@ function getPreferredLocale(acceptLanguage: string | null): string {
     if (SUPPORTED_LOCALES.has(item.code)) {
       return item.code
     }
-    if (SUPPORTED_LOCALES.has(item.base)) {
-      return item.base
+    const base: string = item.base
+    if (SUPPORTED_LOCALES.has(base)) {
+      return base
     }
   }
@@ -39,6 +42,17 @@ export const i18n = async (context: any, next: any) => {
   const url = new URL(context.request.url)
   const pathname = url.pathname
+  // Extract active locale from request context
+  const paramLocale = context.params?.locale
+  const firstSegment = pathname.split("/").find(Boolean)
+  const activeLocale =
+    (paramLocale && SUPPORTED_LOCALES.has(paramLocale) ? paramLocale : null) ||
+    (firstSegment && SUPPORTED_LOCALES.has(firstSegment) ? firstSegment : null) ||
+    context.currentLocale ||
+    DEFAULT_LOCALE
+  currentLocale.set(activeLocale)
   // Only handle GET/HEAD requests
   if (context.request.method !== "GET" && context.request.method !== "HEAD") {
     return next()
@@ -50,8 +64,6 @@ export const i18n = async (context: any, next: any) => {
   }
   // Check if pathname starts with a supported locale prefix
-  const firstSegment = pathname.split("/").find(Boolean)
   if (firstSegment && SUPPORTED_LOCALES.has(firstSegment)) {
     return next()
   }
@@ -59,6 +71,7 @@ export const i18n = async (context: any, next: any) => {
   // Redirect to the preferred locale
   const acceptLanguage = context.request.headers.get("accept-language")
   const locale = getPreferredLocale(acceptLanguage)
+  currentLocale.set(locale)
   const targetPath = `/${locale}${pathname}${url.search}`
   return context.redirect(targetPath, 302)

package/src/middleware.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 import { env } from "cloudflare:workers"
 import { setKVBinding } from "./index"
-export const onRequest = async (context: any, next: any) => {
+export const onRequest = async (_context: unknown, next: () => Promise<Response>) => {
   const kv = Reflect.get(env, "TRANSLATIONS_KV")
   if (kv) {
     setKVBinding(kv)

package/src/runtime.ts ADDED Viewed

@@ -0,0 +1,316 @@
+import { createI18n, formatter, translationsLoading } from "@nanostores/i18n"
+import type {
+  TranslationLoader,
+  Translations,
+  I18n,
+  Components,
+  ComponentsJSON
+} from "@nanostores/i18n"
+import { atom } from "nanostores"
+/**
+ * A reactive store containing the current locale code. Set by middleware on each request, or
+ * manually via `currentLocale.set(locale)`.
+ */
+export const currentLocale = atom("")
+type I18nInstance = I18n
+type FormatterInstance = ReturnType<typeof formatter>
+let i18nInstance: I18nInstance | undefined
+let formatterInstance: FormatterInstance | undefined
+let baseLocaleDefault: string = "en"
+let rawTranslationsDict: Record<string, Components> = {}
+function throwNotInitialized(): never {
+  throw new Error("i18n not initialized. Call initializeI18n first.")
+}
+/**
+ * Wraps a TranslationLoader so that the returned object is guaranteed to contain a key for every
+ * requested component.
+ *
+ * The nanostores i18n library uses the keys of the object returned from `get` to clear its internal
+ * "requested" set. If a requested component is missing from the result (e.g. because the backend
+ * has no translations for it in the given locale yet), the internal loading atom is never set back
+ * to `false`, which causes useI18nAsync / translationsLoading to hang forever.
+ *
+ * This wrapper normalises the loader output so missing components are filled in with empty
+ * translation objects, falling back to the base translations defined at the call site.
+ */
+function wrapLoader(loader: TranslationLoader): TranslationLoader {
+  return async (code, components): Promise<ComponentsJSON> => {
+    const raw = await loader(code, components)
+    const normalised: ComponentsJSON = Array.isArray(raw)
+      ? Object.assign({} as ComponentsJSON, ...raw)
+      : { ...raw }
+    for (const component of components) {
+      if (!(component in normalised)) normalised[component] = {}
+    }
+    return normalised
+  }
+}
+export interface InitializeI18nOptions {
+  /**
+   * The default locale code (e.g. 'en').
+   */
+  defaultLocale: string
+  /**
+   * Pre-loaded translations keyed by locale then component.
+   */
+  translations: Record<string, Components>
+  /**
+   * Optional dynamic loader called when a locale is not in cache.
+   */
+  get?: TranslationLoader
+}
+/**
+ * Initializes the i18n system. Must be called once before any other i18n functions are used (the
+ * integration virtual module does this automatically).
+ */
+export function initializeI18n(options: InitializeI18nOptions): void {
+  const { defaultLocale, translations, get } = options
+  baseLocaleDefault = defaultLocale
+  rawTranslationsDict = translations || {}
+  if (!i18nInstance) {
+    currentLocale.set(defaultLocale)
+    // Convert plain JSON dictionaries to nanostores atoms expected by nanostores/i18n cache
+    const formattedCache: Record<string, Components> = {}
+    for (const [locale, components] of Object.entries(translations)) {
+      formattedCache[locale] = {}
+      for (const [compName, compBody] of Object.entries(components)) {
+        let bodyObj: Record<string, string> = {}
+        if (isStringRecord(compBody)) {
+          bodyObj = compBody
+        } else if (isStoreWithGet(compBody)) {
+          const res: unknown = compBody.get()
+          if (isStringRecord(res)) {
+            bodyObj = res
+          }
+        }
+        formattedCache[locale][compName] = atom(bodyObj)
+      }
+    }
+    i18nInstance = createI18n(currentLocale, {
+      baseLocale: defaultLocale,
+      get: wrapLoader(get ?? (async (): Promise<ComponentsJSON> => ({}))),
+      cache: formattedCache,
+      isSSR: true
+    })
+  }
+  formatterInstance = formatter(currentLocale)
+}
+/**
+ * Returns the underlying nanostores/i18n instance. Throws if not initialized.
+ */
+export function getI18nInstance(): I18nInstance {
+  if (!i18nInstance) throwNotInitialized()
+  return i18nInstance
+}
+/**
+ * Returns the formatter instance. Throws if not initialized.
+ */
+export function getFormatterInstance(): FormatterInstance {
+  if (!formatterInstance) throwNotInitialized()
+  return formatterInstance
+}
+/**
+ * Returns a Formatter object for the current locale with methods for formatting numbers, dates, and
+ * relative times using the native Intl API.
+ */
+export function useFormat(): ReturnType<FormatterInstance["get"]> {
+  return getFormatterInstance().get()
+}
+/**
+ * Helper to safely extract raw translation JSON object from cache regardless of whether it is an
+ * atom or object. Checks exact locale code (e.g. 'zh-CN'), base language code (e.g. 'zh'), and
+ * default locale fallback.
+ */
+interface StoreWithGet {
+  get: () => unknown
+}
+function isStoreWithGet(obj: unknown): obj is StoreWithGet {
+  if (typeof obj !== "object" || obj === null) return false
+  const getFn = Reflect.get(obj, "get")
+  return typeof getFn === "function"
+}
+function isStringRecord(obj: unknown): obj is Record<string, string> {
+  return typeof obj === "object" && obj !== null
+}
+function getCachedComponent(
+  locale: string,
+  componentName: string
+): Record<string, string> | undefined {
+  const normalizedLocale = locale.toLowerCase()
+  const baseLanguage = normalizedLocale.split("-")[0] ?? normalizedLocale
+  const candidates = [locale, normalizedLocale, baseLanguage, baseLocaleDefault]
+  for (const code of candidates) {
+    const rawComp: unknown = rawTranslationsDict[code]?.[componentName]
+    if (isStoreWithGet(rawComp)) {
+      const res: unknown = rawComp.get()
+      if (isStringRecord(res)) return res
+    } else if (isStringRecord(rawComp)) {
+      return rawComp
+    }
+  }
+  if (!i18nInstance) return undefined
+  for (const code of candidates) {
+    const rawComp: unknown = i18nInstance.cache[code]?.[componentName]
+    if (isStoreWithGet(rawComp)) {
+      const res: unknown = rawComp.get()
+      if (isStringRecord(res)) return res
+    } else if (isStringRecord(rawComp)) {
+      return rawComp
+    }
+  }
+  return undefined
+}
+/**
+ * Returns the translated strings for a component in the current locale. Falls back to defaultLocale
+ * loaded translations or `baseTranslations` if provided.
+ */
+export interface ComponentMessages {
+  [key: string]: string
+}
+export function useI18n(componentName: string): ComponentMessages
+export function useI18n<Body extends Translations>(
+  componentName: string,
+  baseTranslations: Body
+): ComponentMessages & Body
+export function useI18n(componentName: string, baseTranslations?: Translations): ComponentMessages {
+  const i18n = getI18nInstance()
+  const activeLocale = currentLocale.get() || baseLocaleDefault
+  const fallbackDict: Record<string, string> = isStringRecord(baseTranslations)
+    ? baseTranslations
+    : {}
+  const baseDict =
+    getCachedComponent(activeLocale, componentName) ??
+    getCachedComponent(baseLocaleDefault, componentName) ??
+    fallbackDict
+  const store = i18n(componentName, baseDict)
+  const targetObj = store.get()
+  return new Proxy(targetObj, {
+    get(target: Record<string, string>, prop: string | symbol): string {
+      if (typeof prop === "symbol" || prop in Object.prototype) {
+        const val: unknown = Reflect.get(target, prop)
+        return typeof val === "string" ? val : ""
+      }
+      const val = target[prop] ?? baseDict[prop]
+      return val ?? prop
+    }
+  })
+}
+/**
+ * Async version of useI18n that waits for translations to finish loading.
+ */
+export async function useI18nAsync(componentName: string): Promise<ComponentMessages>
+export async function useI18nAsync<Body extends Translations>(
+  componentName: string,
+  baseTranslations: Body
+): Promise<ComponentMessages & Body>
+export async function useI18nAsync(
+  componentName: string,
+  baseTranslations?: Translations
+): Promise<ComponentMessages> {
+  const i18n = getI18nInstance()
+  const activeLocale = currentLocale.get() || baseLocaleDefault
+  const cachedActive = getCachedComponent(activeLocale, componentName)
+  const cachedDefault = getCachedComponent(baseLocaleDefault, componentName)
+  let baseDict: Record<string, string> = cachedActive ?? cachedDefault ?? {}
+  if (!cachedActive && !cachedDefault && isStringRecord(baseTranslations)) {
+    baseDict = baseTranslations
+  }
+  const store = i18n(componentName, baseDict)
+  const unsubscribe = store.listen(() => {})
+  await translationsLoading(i18n)
+  unsubscribe()
+  return store.get()
+}
+/**
+ * Translates a single string key using dot-notation (e.g. `t("page_home.section_hero_title")`).
+ */
+export function t(key: string, params?: Record<string, any>): string
+export function t(
+  astro: { currentLocale?: string | undefined; params?: Record<string, any> } | undefined | null,
+  key: string,
+  params?: Record<string, any>
+): string
+export function t(arg1: any, arg2?: any, arg3?: any): string {
+  let key: string
+  let params: Record<string, any> | undefined
+  if (typeof arg1 === "string") {
+    key = arg1
+    params = arg2
+  } else {
+    const locale = arg1?.currentLocale || arg1?.params?.locale
+    if (locale) {
+      currentLocale.set(locale)
+    }
+    key = arg2
+    params = arg3
+  }
+  const dotIndex = key.indexOf(".")
+  if (dotIndex === -1) {
+    return key
+  }
+  const componentName = key.slice(0, dotIndex)
+  const keyName = key.slice(dotIndex + 1)
+  const activeLocale = currentLocale.get() || baseLocaleDefault
+  const componentDict =
+    getCachedComponent(activeLocale, componentName) ??
+    getCachedComponent(baseLocaleDefault, componentName) ??
+    {}
+  const value = componentDict[keyName] ?? key
+  if (typeof value === "function") {
+    return (value as Function)(params)
+  }
+  if (params && typeof value === "string") {
+    return value.replace(/\{(\w+)\}/g, (_, k) => String(params[k] ?? `{${k}}`))
+  }
+  return value
+}
+/**
+ * Clears the translation cache.
+ *
+ * @param locale - If provided, clears only that locale's cache. Otherwise clears all.
+ */
+export function clearCache(locale?: string): void {
+  if (!i18nInstance) throwNotInitialized()
+  const cache = i18nInstance.cache
+  if (locale) {
+    cache[locale] = {}
+  } else {
+    for (const key in cache) cache[key] = {}
+  }
+}

package/src/utils.ts CHANGED Viewed

@@ -19,13 +19,14 @@ export function unflatten(flat: FlattenedTranslations): ComponentsJSON {
   for (const [key, value] of Object.entries(flat)) {
     const parts = key.split(".")
     if (parts.length < 2) continue
-    const component = parts[0]
+    const component: string = parts[0] ?? ""
+    if (!component) continue
     const translationKey = parts.slice(1).join(".")
     if (!(component in result)) {
       result[component] = {}
     }
-    result[component][translationKey] = value
+    result[component]![translationKey] = value
   }
   return result
 }

package/src/virtual.d.ts CHANGED Viewed

@@ -1,8 +1,15 @@
-declare module "astro-nanostores-i18n:runtime" {
-  export * from "astro-nanostores-i18n/runtime"
+declare module "@rimelight/i18n:runtime" {
+  export * from "@rimelight/i18n/runtime"
 }
 declare module "virtual:rimelight-i18n-config" {
   export const locales: string[]
   export const defaultLocale: string
 }
+declare module "cloudflare:workers" {
+  /**
+   * Ambient Cloudflare Workers env — populated at runtime by the CF runtime.
+   */
+  export const env: Record<string, any>
+}