@i18n-micro/astro 1.0.0 → 1.1.0

package/src/composer.ts

@@ -0,0 +1,210 @@
+import {
+  BaseI18n,
+  type TranslationCache,
+} from '@i18n-micro/core'
+import type {
+  Translations,
+  PluralFunc,
+} from '@i18n-micro/types'
+
+export interface AstroI18nOptions {
+  locale: string
+  fallbackLocale?: string
+  messages?: Record<string, Translations>
+  plural?: PluralFunc
+  missingWarn?: boolean
+  missingHandler?: (locale: string, key: string, routeName: string) => void
+  // NEW: Allow passing existing cache
+  _cache?: TranslationCache
+}
+
+export class AstroI18n extends BaseI18n {
+  private _locale: string
+  private _fallbackLocale: string
+  private _currentRoute: string
+
+  // Кэш для Core (без Vue реактивности)
+  public readonly cache: TranslationCache
+
+  // Сохраняем начальные переводы для восстановления после clearCache
+  private initialMessages: Record<string, Translations> = {}
+
+  constructor(options: AstroI18nOptions) {
+    // Если передан существующий кэш (от глобального инстанса), используем его.
+    // Иначе создаем новый.
+    const cache: TranslationCache = options._cache || {
+      generalLocaleCache: {},
+      routeLocaleCache: {},
+      dynamicTranslationsCaches: [],
+      serverTranslationCache: {},
+    }
+
+    // Call parent constructor with options
+    super({
+      cache,
+      plural: options.plural,
+      missingWarn: options.missingWarn,
+      missingHandler: options.missingHandler,
+    })
+
+    // Assign cache to public readonly property
+    this.cache = cache
+
+    this._locale = options.locale
+    this._fallbackLocale = options.fallbackLocale || options.locale
+    this._currentRoute = 'general'
+
+    // Загружаем начальные сообщения (только если это первичная инициализация или добавление новых)
+    if (options.messages) {
+      // Сохраняем начальные переводы для восстановления после clearCache
+      this.initialMessages = { ...options.messages }
+      for (const [lang, msgs] of Object.entries(options.messages)) {
+        this.helper.loadTranslations(lang, msgs)
+      }
+    }
+  }
+
+  /**
+   * Clone cache with shallow copy to prevent memory leaks
+   * Each request-scoped instance gets its own cache structure,
+   * but can read from the global cache (read-only access to existing translations)
+   */
+  private cloneCache(sourceCache: TranslationCache): TranslationCache {
+    // Helper to get value from RefLike or plain value
+    const getValue = <T>(refOrValue: T | { value: T }): T => {
+      return typeof refOrValue === 'object' && refOrValue !== null && 'value' in refOrValue
+        ? (refOrValue as { value: T }).value
+        : refOrValue as T
+    }
+
+    // Get actual values from cache (handling RefLike)
+    const generalCache = getValue(sourceCache.generalLocaleCache)
+    const routeCache = getValue(sourceCache.routeLocaleCache)
+    const dynamicCaches = getValue(sourceCache.dynamicTranslationsCaches)
+    const serverCache = getValue(sourceCache.serverTranslationCache)
+
+    // Create new cache structure with shallow copy of existing translations
+    // This allows read-only access to global translations while isolating writes
+    return {
+      generalLocaleCache: { ...generalCache },
+      routeLocaleCache: { ...routeCache },
+      dynamicTranslationsCaches: [...dynamicCaches],
+      serverTranslationCache: { ...serverCache },
+    }
+  }
+
+  /**
+   * Create a request-scoped instance with isolated cache
+   * Prevents memory leaks by isolating per-request translations from global cache
+   */
+  public clone(newLocale?: string): AstroI18n {
+    // Create isolated cache for this request to prevent memory leaks
+    // The new cache can read from global translations (shallow copy),
+    // but writes (addTranslations, addRouteTranslations) won't affect global cache
+    const isolatedCache = this.cloneCache(this.cache)
+
+    return new AstroI18n({
+      locale: newLocale || this._locale,
+      fallbackLocale: this._fallbackLocale,
+      plural: this.pluralFunc,
+      missingWarn: this.missingWarn,
+      missingHandler: this.missingHandler,
+      _cache: isolatedCache, // Изолированный кэш для предотвращения утечек памяти
+    })
+  }
+
+  // Геттер/Сеттер для локали
+  get locale(): string {
+    return this._locale
+  }
+
+  set locale(val: string) {
+    this._locale = val
+  }
+
+  // Геттер/Сеттер для fallback локали
+  get fallbackLocale(): string {
+    return this._fallbackLocale
+  }
+
+  set fallbackLocale(val: string) {
+    this._fallbackLocale = val
+  }
+
+  // Геттер/Сеттер для текущего роута
+  get currentRoute(): string {
+    return this._currentRoute
+  }
+
+  setRoute(routeName: string): void {
+    this._currentRoute = routeName
+  }
+
+  // --- Implementation of abstract methods ---
+
+  public getLocale(): string {
+    return this._locale
+  }
+
+  public getFallbackLocale(): string {
+    return this._fallbackLocale
+  }
+
+  public getRoute(): string {
+    return this._currentRoute
+  }
+
+  /**
+   * Get route-specific translations for a given locale and route
+   * This method encapsulates the cache key format, making it safe to use
+   * without direct cache access
+   */
+  public getRouteTranslations(locale: string, routeName: string): Translations | null {
+    const cacheKey = `${locale}:${routeName}`
+    const routeCache = this.cache.routeLocaleCache
+
+    // Cache is a plain object in AstroI18n (not Vue ref)
+    if (routeCache && typeof routeCache === 'object' && !Array.isArray(routeCache)) {
+      return (routeCache as Record<string, Translations>)[cacheKey] || null
+    }
+
+    return null
+  }
+
+  // Методы для добавления переводов
+  public addTranslations(locale: string, translations: Translations, merge: boolean = true): void {
+    super.loadTranslationsCore(locale, translations, merge)
+  }
+
+  public addRouteTranslations(
+    locale: string,
+    routeName: string,
+    translations: Translations,
+    merge: boolean = true,
+  ): void {
+    super.loadRouteTranslationsCore(locale, routeName, translations, merge)
+  }
+
+  public mergeTranslations(locale: string, routeName: string, translations: Translations): void {
+    this.helper.mergeTranslation(locale, routeName, translations, true)
+  }
+
+  public mergeGlobalTranslations(locale: string, translations: Translations): void {
+    this.helper.mergeGlobalTranslation(locale, translations, true)
+  }
+
+  public override clearCache(): void {
+    // Сохраняем начальные переводы перед очисткой
+    const initialMessages = { ...this.initialMessages }
+
+    // Очищаем кэш
+    super.clearCache()
+
+    // Восстанавливаем начальные переводы
+    if (Object.keys(initialMessages).length > 0) {
+      for (const [lang, msgs] of Object.entries(initialMessages)) {
+        this.helper.loadTranslations(lang, msgs)
+      }
+    }
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="astro/client" />
+
+import type { AstroI18n } from './composer'
+import type { Locale } from '@i18n-micro/types'
+import type { I18nRoutingStrategy } from './router/types'
+
+declare global {
+  namespace App {
+    interface Locals {
+      i18n: AstroI18n
+      locale: string
+      defaultLocale: string
+      locales: Locale[]
+      currentUrl: URL
+      routingStrategy?: I18nRoutingStrategy
+    }
+  }
+}
+
+export {}

package/src/index.ts

@@ -0,0 +1,59 @@
+// Import shim to ensure types are available
+import './env.d'
+
+// Main exports
+export { i18nIntegration, createI18n } from './integration'
+export { AstroI18n, type AstroI18nOptions } from './composer'
+export { createI18nMiddleware, detectLocale } from './middleware'
+export type { I18nMiddlewareOptions } from './middleware'
+
+// Utilities
+export {
+  useI18n,
+  getI18n,
+  getLocale,
+  getDefaultLocale,
+  getLocales,
+  useLocaleHead,
+  getI18nProps,
+} from './utils'
+export type { LocaleHeadOptions, LocaleHeadResult, I18nClientProps } from './utils'
+
+// Router abstraction
+export type { I18nRoutingStrategy } from './router/types'
+export { createAstroRouterAdapter } from './router/adapter'
+
+// Legacy routing utilities (deprecated, use routingStrategy instead)
+// Kept for backward compatibility
+export {
+  getRouteName,
+  getLocaleFromPath,
+  switchLocalePath,
+  localizePath,
+  removeLocaleFromPath,
+} from './routing'
+
+// Re-export types from @i18n-micro/types
+export type {
+  Translations,
+  Params,
+  PluralFunc,
+  Getter,
+  Locale,
+  LocaleCode,
+  CleanTranslation,
+} from '@i18n-micro/types'
+
+// Re-export utilities from core
+export { interpolate, FormatService, defaultPlural } from '@i18n-micro/core'
+
+// Export integration options type
+export type { I18nIntegrationOptions } from './integration'
+
+// Export translation loading utilities
+export {
+  loadTranslationsFromDir,
+  loadTranslationsIntoI18n,
+} from './load-translations'
+export type { LoadTranslationsOptions, LoadedTranslations } from './load-translations'
+// It's loaded directly by Astro via entrypoint in integration config

package/src/integration.ts

@@ -0,0 +1,120 @@
+import type { AstroIntegration, HookParameters } from 'astro'
+import { AstroI18n, type AstroI18nOptions } from './composer'
+import type { Locale, ModuleOptions, PluralFunc } from '@i18n-micro/types'
+import type { I18nRoutingStrategy } from './router/types'
+
+export interface I18nIntegrationOptions extends Omit<ModuleOptions, 'plural'> {
+  locale: string
+  fallbackLocale?: string
+  locales?: Locale[]
+  messages?: Record<string, Record<string, unknown>>
+  plural?: PluralFunc
+  missingWarn?: boolean
+  missingHandler?: (locale: string, key: string, routeName: string) => void
+  localeCookie?: string
+  autoDetect?: boolean
+  redirectToDefault?: boolean
+  translationDir?: string
+  routingStrategy?: I18nRoutingStrategy
+}
+
+let globalRoutingStrategy: I18nRoutingStrategy | null = null
+
+export function getGlobalRoutingStrategy(): I18nRoutingStrategy | null {
+  return globalRoutingStrategy
+}
+
+export function setGlobalRoutingStrategy(strategy: I18nRoutingStrategy | null): void {
+  globalRoutingStrategy = strategy
+}
+
+/**
+ * Astro Integration for i18n-micro
+ */
+export function i18nIntegration(options: I18nIntegrationOptions): AstroIntegration {
+  const {
+    locale: defaultLocale,
+    fallbackLocale,
+    translationDir,
+    routingStrategy,
+  } = options
+
+  globalRoutingStrategy = routingStrategy || null
+
+  return {
+    name: '@i18n-micro/astro',
+    hooks: {
+      // 1. Настройка Vite (Виртуальный модуль) происходит здесь
+      'astro:config:setup': (params) => {
+        const { updateConfig } = params as HookParameters<'astro:config:setup'>
+
+        const virtualModuleId = 'virtual:i18n-micro/config'
+        const resolvedVirtualModuleId = '\0' + virtualModuleId
+
+        const configData = {
+          defaultLocale,
+          fallbackLocale: fallbackLocale || defaultLocale,
+          locales: options.locales || [],
+          localeCodes: (options.locales || []).map(l => l.code),
+          translationDir: translationDir || null,
+          autoDetect: options.autoDetect ?? true,
+          redirectToDefault: options.redirectToDefault ?? false,
+          localeCookie: options.localeCookie || 'i18n-locale',
+          missingWarn: options.missingWarn ?? false,
+        }
+
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: 'vite-plugin-i18n-micro-config',
+                resolveId(id) {
+                  if (id === virtualModuleId) {
+                    return resolvedVirtualModuleId
+                  }
+                },
+                load(id) {
+                  if (id === resolvedVirtualModuleId) {
+                    return `export const config = ${JSON.stringify(configData)}`
+                  }
+                },
+              },
+            ],
+          },
+        })
+      },
+
+      // 2. Инъекция типов происходит здесь (согласно документации Astro)
+      'astro:config:done': (params) => {
+        const { injectTypes } = params as HookParameters<'astro:config:done'>
+
+        injectTypes({
+          filename: 'i18n-micro-env.d.ts',
+          content: `
+            /// <reference types="@i18n-micro/astro/env" />
+
+            declare module 'virtual:i18n-micro/config' {
+              export const config: {
+                defaultLocale: string;
+                fallbackLocale: string;
+                locales: import('@i18n-micro/types').Locale[];
+                localeCodes: string[];
+                translationDir: string | null;
+                autoDetect: boolean;
+                redirectToDefault: boolean;
+                localeCookie: string;
+                missingWarn: boolean;
+              }
+            }
+          `,
+        })
+      },
+    },
+  }
+}
+/**
+ * Create i18n instance (for manual setup)
+ */
+export function createI18n(options: AstroI18nOptions): AstroI18n {
+  return new AstroI18n(options)
+}

package/src/load-translations.ts

@@ -0,0 +1,130 @@
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import type { Translations } from '@i18n-micro/types'
+
+/**
+ * WARNING: Node.js-only functions
+ *
+ * The functions in this file use Node.js filesystem APIs (node:fs) and will NOT work
+ * in Edge runtime environments (Cloudflare Workers, Vercel Edge, Deno Deploy, etc.).
+ *
+ * If you import this module in an Edge environment, the bundler will fail at build time
+ * because node:fs is not available. This is the intended behavior (Fail Fast).
+ *
+ * For Edge-compatible translation loading, use import.meta.glob in your middleware:
+ * const translations = import.meta.glob('/src/locales/*.json', { eager: true })
+ */
+
+/**
+ * Load translations from a directory structure
+ * Supports both flat structure (en.json, fr.json) and nested structure (pages/home/en.json)
+ */
+export interface LoadTranslationsOptions {
+  translationDir: string
+  rootDir?: string
+  disablePageLocales?: boolean
+}
+
+export interface LoadedTranslations {
+  general: Record<string, Translations>
+  routes: Record<string, Record<string, Translations>>
+}
+
+/**
+ * Load all translations from a directory
+ *
+ * WARNING: Node.js-only - This function uses node:fs and will NOT work in Edge runtime.
+ * If imported in Edge environment, bundler will fail at build time (Fail Fast).
+ * Use import.meta.glob for Edge-compatible loading.
+ */
+export function loadTranslationsFromDir(options: LoadTranslationsOptions): LoadedTranslations {
+  const { translationDir, rootDir = process.cwd(), disablePageLocales = false } = options
+  const fullTranslationDir = resolve(rootDir, translationDir)
+
+  if (!existsSync(fullTranslationDir)) {
+    console.warn(`[i18n] Translation directory not found: ${fullTranslationDir}`)
+    return { general: {}, routes: {} }
+  }
+
+  const general: Record<string, Translations> = {}
+  const routes: Record<string, Record<string, Translations>> = {}
+
+  /**
+   * Recursively load translation files
+   */
+  const loadFiles = (dir: string, routePrefix = ''): void => {
+    if (!existsSync(dir)) return
+
+    const entries = readdirSync(dir)
+    for (const entry of entries) {
+      const fullPath = join(dir, entry)
+      const stat = statSync(fullPath)
+
+      if (stat.isDirectory()) {
+        // If it's a 'pages' directory and page locales are enabled, treat as route-specific
+        if (entry === 'pages' && !disablePageLocales) {
+          loadFiles(fullPath, '')
+        }
+        else if (routePrefix || disablePageLocales) {
+          // Continue in general translations
+          loadFiles(fullPath, routePrefix)
+        }
+        else {
+          // This is a route directory (e.g., pages/home/)
+          loadFiles(fullPath, entry)
+        }
+      }
+      else if (entry.endsWith('.json')) {
+        const locale = entry.replace('.json', '')
+        try {
+          const content = readFileSync(fullPath, 'utf-8')
+          const translations = JSON.parse(content) as Translations
+
+          if (routePrefix && !disablePageLocales) {
+            // Route-specific translation
+            if (!routes[routePrefix]) {
+              routes[routePrefix] = {}
+            }
+            routes[routePrefix][locale] = translations
+          }
+          else {
+            // General translation
+            general[locale] = translations
+          }
+        }
+        catch (error) {
+          console.error(`[i18n] Failed to load translation file: ${fullPath}`, error)
+        }
+      }
+    }
+  }
+
+  loadFiles(fullTranslationDir)
+
+  return { general, routes }
+}
+
+/**
+ * Load translations and add them to an AstroI18n instance
+ *
+ * WARNING: Node.js-only - This function uses node:fs and will NOT work in Edge runtime.
+ * For Edge environments, use import.meta.glob to load translations at build time.
+ */
+export function loadTranslationsIntoI18n(
+  i18n: { addTranslations: (locale: string, translations: Translations, merge?: boolean) => void, addRouteTranslations: (locale: string, routeName: string, translations: Translations, merge?: boolean) => void },
+  options: LoadTranslationsOptions,
+): void {
+  const { general, routes } = loadTranslationsFromDir(options)
+
+  // Load general translations
+  for (const [locale, translations] of Object.entries(general)) {
+    i18n.addTranslations(locale, translations, false)
+  }
+
+  // Load route-specific translations
+  for (const [routeName, routeTranslations] of Object.entries(routes)) {
+    for (const [locale, translations] of Object.entries(routeTranslations)) {
+      i18n.addRouteTranslations(locale, routeName, translations, false)
+    }
+  }
+}