@edgekits/astro-i18n 0.1.7 → 0.2.0

package/src/types.ts

@@ -1,123 +1,23 @@
 /**
- * Public types of the package and the config validator. Pure: no virtual modules,
- * no `cloudflare:workers`, so the consumer's `astro.config` and the CLI can import it
- * under plain Node.
+ * The core's public types and config helpers, re-exported for this package's entries
+ * (root, `./config`, `./runtime`), plus what only Astro needs: the `App.Locals` the
+ * middleware fills. `I18nLocales` is the core's interface: augmenting it through either
+ * entry (the integration's injected `locales.d.ts`) merges into that one declaration.
  */
-
-// `countryCode` is what the switcher's `flag` component receives; without it the item
-// shows the name alone.
-export type I18nLanguage = { countryCode?: string; name: string }
-
-export type I18nConfig = {
-  // The only source of truth for languages: the keys are the locales.
-  languages: Record<string, I18nLanguage>
-  defaultLocale: string
-  // The lang cookie the middleware keeps in sync with the URL locale.
-  cookie: { name: string; maxAge: number }
-  // Prefix of every translation KV key and the host of every edge-cache URL.
-  keyPrefix: string
-  missingTranslationBanner: boolean
-  routing: 'prefix'
-  // Where the CLI writes `fallbacks.generated.ts` and `runtime-constants.ts`,
-  // relative to the project root.
-  generatedDir?: string
-  // Where the CLI reads `<locale>/<namespace>.json`, relative to the project root.
-  localesDir?: string
-  // Geo-IP step of the middleware's locale fallback: ISO 3166-1 alpha-2 country code
-  // (uppercase, as `request.cf.country` sends it) → one of `languages`. Without it the
-  // step is skipped; the package ships no table of its own.
-  countryToLocale?: Record<string, string>
-  // The locale of the project's `.md` endpoints: a `.md` path is redirected once to
-  // `/<markdownLocale>/<rest>` (a leading locale segment replaced, otherwise kept). Without
-  // it, `.md` paths pass through the middleware untouched.
-  markdownLocale?: string
-}
-
-export const DEFAULT_GENERATED_DIR = 'src/i18n'
-export const DEFAULT_LOCALES_DIR = 'locales'
-
-/** The locale keys of a config's `languages`: a literal union for a literal config. */
-export type LocaleOf<C extends I18nConfig> = Extract<keyof C['languages'], string>
-
-const COUNTRY_CODE = /^[A-Z]{2}$/
-
-/**
- * Validates and returns the config unchanged. Throws at config time on an empty
- * `languages`, a `defaultLocale` or `markdownLocale` that is not one of its keys, an
- * unknown `routing`, or a `countryToLocale` entry whose key is not an uppercase country
- * code or whose value is not one of `languages` (also a type error for a literal config).
- */
-export function defineI18nConfig<const C extends I18nConfig>(
-  config: C & { countryToLocale?: Record<string, LocaleOf<C>>; markdownLocale?: LocaleOf<C> },
-): C {
-  const locales = Object.keys(config.languages ?? {})
-
-  if (locales.length === 0) {
-    throw new Error('[@edgekits/astro-i18n] `languages` must define at least one locale.')
-  }
-  // Lowercase everywhere (config, `locales/` folders, URLs); `toIetfTag` relies on it.
-  for (const locale of locales) {
-    if (locale !== locale.toLowerCase()) {
-      throw new Error(
-        `[@edgekits/astro-i18n] \`languages\` key "${locale}" is not lowercase (use "${locale.toLowerCase()}").`,
-      )
-    }
-  }
-  if (!locales.includes(config.defaultLocale)) {
-    throw new Error(
-      `[@edgekits/astro-i18n] \`defaultLocale\` "${config.defaultLocale}" is not one of \`languages\`: ${locales.join(', ')}.`,
-    )
-  }
-  if (config.markdownLocale !== undefined && !locales.includes(config.markdownLocale)) {
-    throw new Error(
-      `[@edgekits/astro-i18n] \`markdownLocale\` "${config.markdownLocale}" is not one of \`languages\`: ${locales.join(', ')}.`,
-    )
-  }
-  if (config.routing !== 'prefix') {
-    throw new Error(
-      `[@edgekits/astro-i18n] \`routing\` "${String(config.routing)}" is not supported; the only routing is 'prefix'.`,
-    )
-  }
-  for (const [country, locale] of Object.entries(config.countryToLocale ?? {})) {
-    if (!COUNTRY_CODE.test(country)) {
-      throw new Error(
-        `[@edgekits/astro-i18n] \`countryToLocale\` key "${country}" is not an uppercase ISO 3166-1 alpha-2 country code.`,
-      )
-    }
-    if (!locales.includes(locale)) {
-      throw new Error(
-        `[@edgekits/astro-i18n] \`countryToLocale\` maps "${country}" to "${locale}", which is not one of \`languages\`: ${locales.join(', ')}.`,
-      )
-    }
-  }
-
-  return config
-}
-
-/**
- * The project's locales, as keys. Empty here; the integration augments it from the
- * config's `languages` (`injectTypes` at `astro:config:done`).
- */
-export interface I18nLocales {}
-
-type LocaleKey = Extract<keyof I18nLocales, string>
-
-// Falls back to `string` while `I18nLocales` is empty, like `Namespace` over `I18n.Schema`.
-export type Locale = [LocaleKey] extends [never] ? string : LocaleKey
-
-/** The Worker bindings the engine reads from `cloudflare:workers`. */
-export interface I18nBindings {
-  TRANSLATIONS: KVNamespace
-  I18N_CACHE?: string
-  DEBUG_I18N?: string
-}
+import type { Locale } from '@edgekits/i18n-core'
+
+export { DEFAULT_GENERATED_DIR, defineI18nConfig, localesOf } from '@edgekits/i18n-core'
+export type {
+  I18nBindings,
+  I18nConfig,
+  I18nLanguage,
+  I18nLocales,
+  Locale,
+  LocaleOf,
+  LocalesOf,
+} from '@edgekits/i18n-core'
 
 declare global {
-  // Augmented by the consumer's generated `i18n.generated.d.ts`.
-  namespace I18n {
-    interface Schema {}
-  }
-
   // Set by the i18n middleware on every request.
   namespace App {
     interface Locals {

package/dist/cli/generate.d.ts

@@ -1,50 +0,0 @@
-/**
- * The CLI's code generation, as pure functions of the collected locale tree: no
- * filesystem, so the emitted text is testable. Formats are those of the site's
- * `scripts/bundle-translations.ts`, header aside.
- */
-export type TranslationTree = Record<string, unknown>;
-export type CollectedData = Record<string, Record<string, TranslationTree>>;
-export type KvBulkEntry = {
-    key: string;
-    value: string;
-};
-export declare const NAMESPACE_NAME: RegExp;
-/**
- * Throws, naming the offender, when a locale folder is not one of the config's
- * `languages` or a namespace file name does not match NAMESPACE_NAME. Run on the
- * collected tree before anything is generated or pushed.
- */
-export declare function assertValidNames(collected: CollectedData, languages: Readonly<Record<string, unknown>>): void;
-/**
- * A single-quoted TS string literal, escaped by JSON.stringify. For every name the
- * validation accepts it is byte-identical to the plain `'name'` the CLI always wrote, so
- * existing generated files do not change; anything else comes out escaped, not injected.
- */
-export declare function quoteString(value: string): string;
-/** Locales that have at least one namespace, sorted. */
-export declare function localesWithTranslations(collected: CollectedData): string[];
-/**
- * The locale the schema and the namespace list are derived from: the default locale
- * when it has translations, otherwise the first locale that does.
- */
-export declare function schemaSourceLocale(collected: CollectedData, defaultLocale: string): string | undefined;
-/** `wrangler kv bulk put` input: one entry per locale and namespace. */
-export declare function buildBulkData(collected: CollectedData, keyPrefix: string): KvBulkEntry[];
-/**
- * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
- * Throws, naming the key, when an array in it mixes kinds of elements.
- */
-export declare function buildTypesContent(collected: CollectedData, defaultLocale: string): string;
-/**
- * `runtime-constants.ts`:
- *   - NAMESPACE_KEYS            -> from the schema source locale (default locale preferred)
- *   - LOCALES_WITH_TRANSLATIONS -> from all collected locales
- *   - FULLY_TRANSLATED_LOCALES  -> locales that have ALL namespace keys
- */
-export declare function buildRuntimeConstantsContent(collected: CollectedData, defaultLocale: string): string;
-/**
- * `fallbacks.generated.ts`: one `FALLBACK_<NAMESPACE>` per default-locale namespace.
- * Null when the default locale has no translations (nothing to fall back to).
- */
-export declare function buildFallbacksContent(collected: CollectedData, defaultLocale: string): string | null;

package/dist/cli/generate.js

@@ -1,160 +0,0 @@
-import { formatTranslationKvKey } from "../key-format.js";
-const HEADER = `// Auto-generated by @edgekits/astro-i18n (edgekits-i18n CLI)
-// Do not edit manually.
-`;
-// A namespace becomes part of a KV key, a cache URL and the `FALLBACK_<NAMESPACE>`
-// identifier, so its file name is restricted to what is valid in all three.
-export const NAMESPACE_NAME = /^[a-z0-9][a-z0-9_]*$/;
-/**
- * Throws, naming the offender, when a locale folder is not one of the config's
- * `languages` or a namespace file name does not match NAMESPACE_NAME. Run on the
- * collected tree before anything is generated or pushed.
- */
-export function assertValidNames(collected, languages) {
-    const configured = Object.keys(languages);
-    for (const [locale, namespaces] of Object.entries(collected)) {
-        if (!configured.includes(locale)) {
-            throw new Error(`Locale folder "${locale}" is not one of \`languages\` in edgekits-i18n.config.ts: ${configured.join(', ')}.`);
-        }
-        for (const ns of Object.keys(namespaces)) {
-            if (!NAMESPACE_NAME.test(ns)) {
-                throw new Error(`Namespace "${ns}" (${locale}/${ns}.json) must match ${NAMESPACE_NAME}: lowercase letters, digits and underscores.`);
-            }
-        }
-    }
-}
-/**
- * A single-quoted TS string literal, escaped by JSON.stringify. For every name the
- * validation accepts it is byte-identical to the plain `'name'` the CLI always wrote, so
- * existing generated files do not change; anything else comes out escaped, not injected.
- */
-export function quoteString(value) {
-    const escaped = JSON.stringify(value).slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'");
-    return `'${escaped}'`;
-}
-/** Locales that have at least one namespace, sorted. */
-export function localesWithTranslations(collected) {
-    return Object.keys(collected).sort();
-}
-/**
- * The locale the schema and the namespace list are derived from: the default locale
- * when it has translations, otherwise the first locale that does.
- */
-export function schemaSourceLocale(collected, defaultLocale) {
-    if (collected[defaultLocale])
-        return defaultLocale;
-    return localesWithTranslations(collected)[0];
-}
-/** `wrangler kv bulk put` input: one entry per locale and namespace. */
-export function buildBulkData(collected, keyPrefix) {
-    const bulkData = [];
-    for (const [locale, namespaces] of Object.entries(collected)) {
-        for (const [ns, json] of Object.entries(namespaces)) {
-            bulkData.push({ key: formatTranslationKvKey(keyPrefix, locale, ns), value: JSON.stringify(json) });
-        }
-    }
-    return bulkData;
-}
-function isTree(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-// The JSON kind of an array element; an array is typed only when all its elements share one.
-function jsonKind(value) {
-    if (value === null)
-        return 'null';
-    if (Array.isArray(value))
-        return 'array';
-    return typeof value;
-}
-/**
- * The TS type of one JSON value. Objects become object types; arrays become `string[]`
- * (strings, other scalars, or empty) or `Array<…>` typed from their first element
- * (objects, nested arrays); every other leaf stays `string`. `keyPath` and `file` name the
- * value in the error a mixed array raises.
- */
-function generateSchemaTs(value, indent, keyPath, file) {
-    if (Array.isArray(value)) {
-        if (value.length === 0)
-            return 'string[]';
-        const kinds = [...new Set(value.map(jsonKind))];
-        if (kinds.length > 1) {
-            throw new Error(`Key "${keyPath}" (${file}) is an array that mixes ${kinds.join(', ')} elements: ` +
-                'I18n.Schema cannot type it. Use one kind of element per array.');
-        }
-        const first = value[0];
-        if (!isTree(first) && !Array.isArray(first))
-            return 'string[]';
-        return `Array<${generateSchemaTs(first, indent, `${keyPath}[0]`, file)}>`;
-    }
-    if (!isTree(value))
-        return 'string';
-    const entries = Object.entries(value);
-    if (entries.length === 0)
-        return '{}';
-    const pad = ' '.repeat(indent);
-    const padInner = ' '.repeat(indent + 2);
-    const lines = entries.map(([key, child]) => `${padInner}${JSON.stringify(key)}: ${generateSchemaTs(child, indent + 2, `${keyPath}.${key}`, file)}`);
-    return `{\n${lines.join(';\n')};\n${pad}}`;
-}
-/**
- * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
- * Throws, naming the key, when an array in it mixes kinds of elements.
- */
-export function buildTypesContent(collected, defaultLocale) {
-    const source = schemaSourceLocale(collected, defaultLocale);
-    const schemaObject = (source && collected[source]) || {};
-    const namespaceLines = Object.entries(schemaObject).map(([ns, value]) => {
-        const valueTs = generateSchemaTs(value, 10, ns, `${source}/${ns}.json`);
-        return `      ${JSON.stringify(ns)}: ${valueTs}`;
-    });
-    const interfaceBody = namespaceLines.length > 0
-        ? `    export interface Schema {\n${namespaceLines.join(';\n')};\n    }`
-        : `    export interface Schema {}`;
-    return `${HEADER}
-declare global {
-  namespace I18n {
-${interfaceBody}
-  }
-}
-
-export {}
-`;
-}
-/**
- * `runtime-constants.ts`:
- *   - NAMESPACE_KEYS            -> from the schema source locale (default locale preferred)
- *   - LOCALES_WITH_TRANSLATIONS -> from all collected locales
- *   - FULLY_TRANSLATED_LOCALES  -> locales that have ALL namespace keys
- */
-export function buildRuntimeConstantsContent(collected, defaultLocale) {
-    const source = schemaSourceLocale(collected, defaultLocale);
-    const namespaceKeys = Object.keys((source && collected[source]) || {}).sort();
-    const locales = localesWithTranslations(collected);
-    const fullyTranslatedLocales = locales.filter((locale) => {
-        const localeNamespaces = Object.keys(collected[locale] || {});
-        return namespaceKeys.every((ns) => localeNamespaces.includes(ns));
-    });
-    return `${HEADER}
-export const NAMESPACE_KEYS = [${namespaceKeys.map(quoteString).join(', ')}] as [string, ...string[]];
-
-export const LOCALES_WITH_TRANSLATIONS = [${locales.map(quoteString).join(', ')}] as const;
-
-export const FULLY_TRANSLATED_LOCALES = [${fullyTranslatedLocales.map(quoteString).join(', ')}] as const;
-`;
-}
-/**
- * `fallbacks.generated.ts`: one `FALLBACK_<NAMESPACE>` per default-locale namespace.
- * Null when the default locale has no translations (nothing to fall back to).
- */
-export function buildFallbacksContent(collected, defaultLocale) {
-    const fallbackNamespaces = collected[defaultLocale];
-    if (!fallbackNamespaces)
-        return null;
-    const lines = [HEADER];
-    lines.push(`export const FALLBACK_LOCALE = ${JSON.stringify(defaultLocale)} as const;\n`);
-    for (const [ns, json] of Object.entries(fallbackNamespaces)) {
-        const constName = `FALLBACK_${ns.toUpperCase()}`;
-        lines.push(`export const ${constName} = ${JSON.stringify(json, null, 2)} as const;\n`);
-    }
-    return lines.join('\n');
-}

package/dist/cli/hashes.d.ts

@@ -1,19 +0,0 @@
-import type { CollectedData } from './generate.ts';
-/**
- * Per-namespace content hashes and the change diff that drives the cache purge.
- * Pure apart from hashing. Same algorithm as the site's `scripts/bundle-translations.ts`,
- * so an existing `.i18n-hashes.json` stays a valid baseline.
- */
-export type HashMap = Record<string, string>;
-export declare function stableStringify(value: unknown): string;
-export declare function computeHash(value: unknown): string;
-/**
- * Hash every collected namespace and list the "<locale>:<namespace>" pairs whose hash
- * differs from the previous run (all of them when there is no previous run).
- */
-export declare function diffHashes(collected: CollectedData, previousHashes: HashMap): {
-    currentHashes: HashMap;
-    changedKeys: string[];
-};
-/** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
-export declare function purgeUrlsFor(changedKeys: readonly string[], keyPrefix: string): string[];

package/dist/cli/hashes.js

@@ -1,42 +0,0 @@
-import crypto from 'node:crypto';
-import { formatTranslationCacheUrl } from "../key-format.js";
-export function stableStringify(value) {
-    if (value === null || typeof value !== 'object') {
-        return JSON.stringify(value);
-    }
-    if (Array.isArray(value)) {
-        return '[' + value.map(stableStringify).join(',') + ']';
-    }
-    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
-    return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + stableStringify(v)).join(',') + '}';
-}
-export function computeHash(value) {
-    const json = stableStringify(value);
-    return crypto.createHash('sha256').update(json).digest('hex').slice(0, 12);
-}
-/**
- * Hash every collected namespace and list the "<locale>:<namespace>" pairs whose hash
- * differs from the previous run (all of them when there is no previous run).
- */
-export function diffHashes(collected, previousHashes) {
-    const currentHashes = {};
-    const changedKeys = [];
-    for (const [locale, namespaces] of Object.entries(collected)) {
-        for (const [ns, json] of Object.entries(namespaces)) {
-            const hashKey = `${locale}:${ns}`;
-            const hash = computeHash(json);
-            currentHashes[hashKey] = hash;
-            if (previousHashes[hashKey] !== hash) {
-                changedKeys.push(hashKey);
-            }
-        }
-    }
-    return { currentHashes, changedKeys };
-}
-/** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
-export function purgeUrlsFor(changedKeys, keyPrefix) {
-    return changedKeys.map((hashKey) => {
-        const [locale, ns] = hashKey.split(':');
-        return formatTranslationCacheUrl(keyPrefix, locale, ns);
-    });
-}

package/dist/cli/index.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};