@rimelight/i18n 0.0.3 → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rimelight Entertainment
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/i18n",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": false,
   "description": "Rimelight i18n — unified translation loader with optional KV backing",
   "files": [
@@ -11,6 +11,7 @@
     ".": "./src/index.ts",
     "./integration": "./src/integration.ts",
     "./middleware": "./src/middleware.ts",
+    "./runtime": "./src/runtime.ts",
     "./types": "./src/types.ts",
     "./utils": "./src/utils.ts"
   },
@@ -19,8 +20,7 @@
   },
   "dependencies": {
     "@nanostores/i18n": "1.3.3",
-    "astro-nanostores-i18n": "0.7.0",
-    "nanostores": "1.3.0"
+    "nanostores": "1.4.0"
   },
   "peerDependencies": {
     "astro": ">=6.0.0"

package/src/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="astro/client" />

package/src/index.ts

@@ -8,7 +8,7 @@ import {
   clearCache,
   getI18nInstance,
   getFormatterInstance
-} from "astro-nanostores-i18n:runtime"
+} from "@rimelight/i18n:runtime"
 import type { Translations } from "@nanostores/i18n"
 
 export { currentLocale, useFormat, clearCache, getI18nInstance, getFormatterInstance }
@@ -110,3 +110,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

@@ -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 locale keys: "pt" → "pt-br" for nanostores compatibility
+  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 === "pt" ? "pt-br" : 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,
+         currentLocale, getI18nInstance, getFormatterInstance, clearCache }
+  from ${JSON.stringify(runtimeSpecifier)};
+${loaderImport}
+
+initializeI18n({
+  defaultLocale: ${JSON.stringify(defaultLocale)},
+  translations: ${JSON.stringify(normalisedTranslations)}${loaderOption}
+});
+
+export { useFormat, useI18n, useI18nAsync, 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,40 @@ 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 declare function useI18n<Body extends Translations>(componentName: string, baseTranslations: Body): Body;
+  export declare function useI18nAsync<Body extends Translations>(componentName: string, baseTranslations: Body): Promise<Body>;
+  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: [] }
@@ -105,12 +172,5 @@ export function rimelightI18n(options?: RimelightI18nOptions): any {
     }
   }
 
-  return [
-    nanostoresI18n({
-      translationLoader,
-      addMiddleware: false,
-      translations: nanostoresTranslations
-    }),
-    rimelightI18nCore
-  ]
+  return [rimelightI18nCore]
 }

package/src/middleware/kv.ts

@@ -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

@@ -10,13 +10,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 +28,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
     }
   }
 

package/src/middleware.ts

@@ -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

@@ -0,0 +1,149 @@
+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
+
+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
+  if (!i18nInstance) {
+    currentLocale.set(defaultLocale)
+    i18nInstance = createI18n(currentLocale, {
+      baseLocale: defaultLocale,
+      get: wrapLoader(get ?? (async (): Promise<ComponentsJSON> => ({}))),
+      cache: translations,
+      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()
+}
+
+/**
+ * Returns the translated strings for a component in the current locale. Falls back to
+ * `baseTranslations` for any key not present in the loaded locale.
+ */
+export function useI18n<Body extends Translations>(
+  componentName: string,
+  baseTranslations: Body
+): Body {
+  return getI18nInstance()(componentName, baseTranslations).get()
+}
+
+/**
+ * Async version of useI18n that waits for translations to finish loading. Required when using a
+ * dynamic translationLoader (e.g. KV-backed loading).
+ */
+export async function useI18nAsync<Body extends Translations>(
+  componentName: string,
+  baseTranslations: Body
+): Promise<Body> {
+  const i18n = getI18nInstance()
+  const store = i18n(componentName, baseTranslations)
+  const unsubscribe = store.listen(() => {})
+  await translationsLoading(i18n)
+  unsubscribe()
+  return store.get()
+}
+
+/**
+ * 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

@@ -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

@@ -1,8 +1,16 @@
-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.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const env: Record<string, any>
+}