@wuchale/astro 0.2.0

package/README.md

@@ -0,0 +1,14 @@
+# `@wuchale/astro`
+
+[![npm version](https://img.shields.io/npm/v/@wuchale/astro?logo=npm&logoColor=red&color=blue)](https://www.npmjs.com/package/@wuchale/astro) ![License](https://img.shields.io/github/license/wuchalejs/wuchale)
+
+An adapter to integrate `wuchale` in Astro projects.
+
+**`wuchale`** is a compile-time internationalization (i18n) toolkit that
+requires zero code changes. Write your components naturally, and `wuchale`
+automatically extracts and replaces translatable strings at build time.
+
+- Main documentation: [wuchale.dev](https://wuchale.dev)
+- Setup instructions: [Getting started](https://wuchale.dev/intro/start/)
+- Adapter docs: [Astro](https://wuchale.dev/adapters/astro)
+- Repository: [wuchalejs/wuchale](https://github.com/wuchalejs/wuchale)

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import type { HeuristicFunc, Adapter, AdapterArgs, LoaderChoice, CreateHeuristicOpts } from "wuchale";
+/**
+ * Create a heuristic function optimized for Astro files
+ * Uses the default heuristic which handles translatable vs non-translatable strings
+ */
+export declare function createAstroHeuristic(opts: CreateHeuristicOpts): HeuristicFunc;
+/** Default Svelte heuristic which extracts top level variable assignments as well, leading to `$derived` being auto added when needed */
+export declare const astroDefaultHeuristic: HeuristicFunc;
+type LoadersAvailable = 'default';
+export type AstroArgs = AdapterArgs<LoadersAvailable>;
+export declare function getDefaultLoaderPath(loader: LoaderChoice<LoadersAvailable>, bundle: boolean): string | null;
+/**
+ * Create an Astro adapter for wuchale
+ *
+ * @example
+ * ```js
+ * // wuchale.config.js
+ * import { adapter as astro } from '@wuchale/astro'
+ *
+ * export default defineConfig({
+ *   adapters: {
+ *     astro: astro({ files: 'src/pages/**\/*.astro' })
+ *   }
+ * })
+ * ```
+ */
+export declare const adapter: (args?: Partial<AstroArgs>) => Adapter;
+export {};

package/dist/index.js

@@ -0,0 +1,90 @@
+import { defaultGenerateLoadID, deepMergeObjects, createHeuristic, defaultHeuristicOpts, } from "wuchale";
+import { pluralPattern } from "wuchale/adapter-vanilla";
+import { AstroTransformer, } from "./transformer.js";
+import { loaderPathResolver } from "wuchale/adapter-utils";
+/**
+ * Create a heuristic function optimized for Astro files
+ * Uses the default heuristic which handles translatable vs non-translatable strings
+ */
+export function createAstroHeuristic(opts) {
+    const defaultHeuristic = createHeuristic(opts);
+    return msg => {
+        const defRes = defaultHeuristic(msg);
+        if (!defRes) {
+            return false;
+        }
+        if (msg.details.scope !== 'script') {
+            return defRes;
+        }
+        if (msg.details.call?.startsWith('Astro.')) {
+            return false;
+        }
+        return defRes;
+    };
+}
+/** Default Svelte heuristic which extracts top level variable assignments as well, leading to `$derived` being auto added when needed */
+export const astroDefaultHeuristic = createAstroHeuristic(defaultHeuristicOpts);
+const defaultRuntime = {
+    // Astro is SSR-only, so we use non-reactive runtime by default
+    initReactive: ({ funcName }) => funcName == null ? false : null, // Only init in top-level functions
+    // Astro is SSR - always use non-reactive
+    useReactive: () => false,
+    reactive: {
+        wrapInit: (expr) => expr,
+        wrapUse: (expr) => expr,
+    },
+    plain: {
+        wrapInit: (expr) => expr,
+        wrapUse: (expr) => expr,
+    },
+};
+const defaultArgs = {
+    files: 'src/**/*.astro',
+    localesDir: './src/locales',
+    patterns: [pluralPattern],
+    heuristic: astroDefaultHeuristic,
+    granularLoad: false,
+    bundleLoad: false,
+    loader: 'default',
+    generateLoadID: defaultGenerateLoadID,
+    runtime: defaultRuntime,
+};
+const resolveLoaderPath = loaderPathResolver(import.meta.url, '../src/loaders', 'js');
+export function getDefaultLoaderPath(loader, bundle) {
+    if (loader === 'custom') {
+        return null;
+    }
+    // just 'default', so
+    let loaderName = 'astro';
+    if (bundle) {
+        loaderName += '.bundle';
+    }
+    return resolveLoaderPath(loaderName);
+}
+/**
+ * Create an Astro adapter for wuchale
+ *
+ * @example
+ * ```js
+ * // wuchale.config.js
+ * import { adapter as astro } from '@wuchale/astro'
+ *
+ * export default defineConfig({
+ *   adapters: {
+ *     astro: astro({ files: 'src/pages/**\/*.astro' })
+ *   }
+ * })
+ * ```
+ */
+export const adapter = (args = {}) => {
+    const { heuristic, patterns, runtime, loader, ...rest } = deepMergeObjects(args, defaultArgs);
+    return {
+        transform: async ({ content, filename, index, expr, matchUrl }) => {
+            return new AstroTransformer(content, filename, index, heuristic, patterns, expr, runtime, matchUrl).transformAs();
+        },
+        loaderExts: ['.js', '.ts'],
+        defaultLoaderPath: getDefaultLoaderPath(loader, rest.bundleLoad),
+        runtime,
+        ...rest,
+    };
+};

package/dist/runtime.d.ts

@@ -0,0 +1,9 @@
+import type { Composite } from 'wuchale';
+export type WuchaleComponentProps = {
+    n?: boolean;
+    x: Composite;
+    t: Function[];
+    a?: any[];
+};
+declare const _default: ({ t, n, x, a }: WuchaleComponentProps) => any[];
+export default _default;

package/dist/runtime.js

@@ -0,0 +1,18 @@
+export default ({ t, n, x, a }) => x.map((x, i) => {
+    if (typeof x === 'string') {
+        return x;
+    }
+    if (typeof x === 'number') {
+        if (!n || i > 0) {
+            return a[x];
+        }
+        return;
+    }
+    const tag = t[x[0]];
+    if (tag == null) {
+        return 'i18n-404:tag';
+    }
+    else {
+        return tag(x);
+    }
+});

package/dist/transformer.d.ts

@@ -0,0 +1,40 @@
+import { Message } from "wuchale";
+import type * as Estree from "acorn";
+import { Transformer } from "wuchale/adapter-vanilla";
+import type { IndexTracker, HeuristicFunc, TransformOutput, RuntimeConf, CatalogExpr, CodePattern, UrlMatcher } from "wuchale";
+import { MixedVisitor, type CommentDirectives } from "wuchale/adapter-utils";
+import type { ElementNode, TextNode, FragmentNode, Node, RootNode, ExpressionNode, AttributeNode, FrontmatterNode, ComponentNode, CustomElementNode } from "@astrojs/compiler/types";
+type MixedAstroNodes = Node;
+export declare class AstroTransformer extends Transformer {
+    currentElement?: string;
+    inCompoundText: boolean;
+    commentDirectivesStack: CommentDirectives[];
+    lastVisitIsComment: boolean;
+    frontMatterStart?: number;
+    mixedVisitor: MixedVisitor<MixedAstroNodes>;
+    correctedExprRanges: WeakMap<Node, {
+        start: number;
+        end: number;
+    }>;
+    constructor(content: string, filename: string, index: IndexTracker, heuristic: HeuristicFunc, patterns: CodePattern[], catalogExpr: CatalogExpr, rtConf: RuntimeConf, matchUrl: UrlMatcher);
+    _saveCorrectedExprRanges: (nodes: Node[], containerEnd: number) => void;
+    getRange: (node: Node | AttributeNode) => {
+        start: number;
+        end: number;
+    };
+    initMixedVisitor: () => MixedVisitor<Node>;
+    _parseAndVisitExpr: (expr: string, startOffset: number, startFromProgram?: boolean) => Message[];
+    visitexpression: (node: ExpressionNode) => Message[];
+    _visitChildren: (nodes: Node[]) => Message[];
+    visitFragmentNode: (node: FragmentNode) => Message[];
+    visitelement: (node: ElementNode) => Message[];
+    visitcomponent: (node: ComponentNode) => Message[];
+    ['visitcustom-element']: (node: CustomElementNode) => Message[];
+    visitattribute: (node: AttributeNode) => Message[];
+    visittext: (node: TextNode) => Message[];
+    visitfrontmatter: (node: FrontmatterNode) => Message[];
+    visitroot: (node: RootNode) => Message[];
+    visitAs: (node: Node | AttributeNode | Estree.AnyNode) => Message[];
+    transformAs: () => Promise<TransformOutput>;
+}
+export {};

package/dist/transformer.js

@@ -0,0 +1,269 @@
+import MagicString from "magic-string";
+import { Message } from "wuchale";
+import { parseScript, Transformer } from "wuchale/adapter-vanilla";
+import { nonWhitespaceText, MixedVisitor, processCommentDirectives, } from "wuchale/adapter-utils";
+import { parse } from "@astrojs/compiler";
+// Astro nodes that can have children
+const nodesWithChildren = [
+    "element",
+    "component",
+    "custom-element",
+    "fragment",
+];
+const rtRenderFunc = "_w_Tx_";
+export class AstroTransformer extends Transformer {
+    // state
+    currentElement;
+    inCompoundText = false;
+    commentDirectivesStack = [];
+    lastVisitIsComment = false;
+    frontMatterStart;
+    mixedVisitor;
+    // astro's compiler gives wrong offsets for expressions
+    correctedExprRanges = new WeakMap();
+    constructor(content, filename, index, heuristic, patterns, catalogExpr, rtConf, matchUrl) {
+        // trim() is VERY important, without it offset positions become wrong due to astro's parser
+        super(content.trim(), filename, index, heuristic, patterns, catalogExpr, rtConf, matchUrl);
+        this.heuristciDetails.insideProgram = false;
+    }
+    _saveCorrectedExprRanges = (nodes, containerEnd) => {
+        for (const [i, child] of nodes.entries()) {
+            if (child.type !== 'expression') {
+                continue;
+            }
+            const nextChild = nodes[i + 1];
+            let actualEnd;
+            if (nextChild != null) {
+                actualEnd = nextChild.position?.start?.offset ?? 0;
+                if (nextChild.type === 'expression') {
+                    actualEnd = this.content.indexOf('{', actualEnd);
+                }
+            }
+            else {
+                actualEnd = this.content.lastIndexOf('}', containerEnd) + 1;
+            }
+            this.correctedExprRanges.set(child, {
+                start: this.content.indexOf('{', child.position?.start?.offset ?? 0),
+                end: actualEnd
+            });
+        }
+    };
+    getRange = (node) => {
+        if (node.type === 'expression') {
+            return this.correctedExprRanges.get(node) ?? { start: -1, end: -1 };
+        }
+        let { start, end } = node.position ?? {};
+        return {
+            start: start?.offset ?? -1,
+            end: end?.offset ?? -1,
+        };
+    };
+    initMixedVisitor = () => new MixedVisitor({
+        mstr: this.mstr,
+        vars: this.vars,
+        getRange: this.getRange,
+        isText: node => node.type === 'text',
+        isComment: node => node.type === 'comment',
+        leaveInPlace: node => [''].includes(node.type),
+        isExpression: node => node.type === 'expression',
+        getTextContent: (node) => node.value,
+        getCommentData: (node) => node.value,
+        canHaveChildren: (node) => nodesWithChildren.includes(node.type),
+        visitFunc: (child, inCompoundText) => {
+            const inCompoundTextPrev = this.inCompoundText;
+            this.inCompoundText = inCompoundText;
+            const childTxts = this.visitAs(child);
+            this.inCompoundText = inCompoundTextPrev; // restore
+            return childTxts;
+        },
+        visitExpressionTag: this.visitexpression,
+        fullHeuristicDetails: this.fullHeuristicDetails,
+        checkHeuristic: this.getHeuristicMessageType,
+        index: this.index,
+        wrapNested: (msgInfo, hasExprs, nestedRanges, lastChildEnd) => {
+            let begin = `{${rtRenderFunc}({\nx: `;
+            if (this.inCompoundText) {
+                begin += `${this.vars().nestCtx},\nn: true`;
+            }
+            else {
+                const index = this.index.get(msgInfo.toKey());
+                begin += `${this.vars().rtCtx}(${index})`;
+            }
+            if (nestedRanges.length > 0) {
+                for (const [i, [childStart, _, haveCtx]] of nestedRanges.entries()) {
+                    let toAppend;
+                    if (i === 0) {
+                        toAppend = `${begin},\nt: [`;
+                    }
+                    else {
+                        toAppend = ', ';
+                    }
+                    this.mstr.appendRight(childStart, `${toAppend}${haveCtx ? this.vars().nestCtx : '()'} => `);
+                }
+                begin = `]`;
+            }
+            let end = '\n})}';
+            if (hasExprs) {
+                begin += ',\na: [';
+                end = ']' + end;
+            }
+            this.mstr.appendLeft(lastChildEnd, begin);
+            this.mstr.appendRight(lastChildEnd, end);
+        },
+    });
+    _parseAndVisitExpr = (expr, startOffset, startFromProgram = false) => {
+        const [ast, comments] = parseScript(expr);
+        this.comments = comments;
+        this.mstr.offset = startOffset;
+        // not just visit Program because visitProgram sets insideProgram to true
+        let msgs;
+        if (startFromProgram) {
+            msgs = this.visit(ast);
+        }
+        else {
+            msgs = ast.body.map(this.visit).flat();
+        }
+        this.mstr.offset = 0; // restore
+        return msgs;
+    };
+    visitexpression = (node) => {
+        let expr = '';
+        const msgs = [];
+        for (const part of node.children) {
+            if (part.type === 'text') {
+                expr += part.value;
+                continue;
+            }
+            msgs.push(...this.visitAs(part));
+            const { start, end } = this.getRange(part);
+            expr += `"${' '.repeat(end - start)}"`;
+        }
+        const { start } = this.getRange(node);
+        msgs.push(...this._parseAndVisitExpr(expr, start + 1));
+        return msgs;
+    };
+    _visitChildren = (nodes) => this.mixedVisitor.visit({
+        children: nodes,
+        commentDirectives: this.commentDirectives,
+        inCompoundText: this.inCompoundText,
+        scope: 'markup',
+        element: this.currentElement,
+        useComponent: this.currentElement !== 'title'
+    });
+    visitFragmentNode = (node) => this._visitChildren(node.children);
+    visitelement = (node) => {
+        const currentElement = this.currentElement;
+        this.currentElement = node.name;
+        const msgs = [];
+        for (const attrib of node.attributes) {
+            msgs.push(...this.visitAs(attrib));
+        }
+        this._saveCorrectedExprRanges(node.children, node.position?.end?.offset ?? 0);
+        msgs.push(...this._visitChildren(node.children));
+        this.currentElement = currentElement;
+        return msgs;
+    };
+    visitcomponent = (node) => this.visitelement(node);
+    ['visitcustom-element'] = (node) => this.visitelement(node);
+    visitattribute = (node) => {
+        const heurBase = {
+            scope: 'attribute',
+            element: this.currentElement,
+            attribute: node.name,
+        };
+        let { start } = this.getRange(node);
+        if (node.kind !== 'empty') {
+            start = this.content.indexOf('=', start) + 1;
+        }
+        if (node.kind === 'quoted') {
+            const [pass, msgInfo] = this.checkHeuristic(node.value, heurBase);
+            if (!pass) {
+                return [];
+            }
+            this.mstr.update(start, start + node.value.length + 2, `{${this.vars().rtTrans}(${this.index.get(msgInfo.toKey())})}`);
+            return [msgInfo];
+        }
+        if (node.kind === 'expression') {
+            heurBase.scope = 'script';
+            start = this.content.indexOf(node.value, start);
+            let expr = node.value;
+            if (expr.startsWith('...')) {
+                start += 3;
+                expr = expr.slice(3);
+            }
+            return this._parseAndVisitExpr(expr, start);
+        }
+        return [];
+    };
+    visittext = (node) => {
+        const [startWh, trimmed, endWh] = nonWhitespaceText(node.value);
+        const [pass, msgInfo] = this.checkHeuristic(trimmed, {
+            scope: 'markup',
+            element: this.currentElement,
+        });
+        if (!pass) {
+            return [];
+        }
+        const { start, end } = this.getRange(node);
+        this.mstr.update(start + startWh, end - endWh, `{${this.vars().rtTrans}(${this.index.get(msgInfo.toKey())})}`);
+        return [msgInfo];
+    };
+    visitfrontmatter = (node) => {
+        const { start } = this.getRange(node);
+        this.frontMatterStart = this.content.indexOf('---', start) + 3;
+        return this._parseAndVisitExpr(node.value, this.frontMatterStart, true);
+    };
+    visitroot = (node) => {
+        const msgs = [];
+        // ?? [] because it's undefined on an empty file
+        for (const rootChild of node.children ?? []) {
+            msgs.push(...this.visitAs(rootChild));
+        }
+        return msgs;
+    };
+    visitAs = (node) => {
+        if (node.type === 'comment') {
+            this.commentDirectives = processCommentDirectives(node.value.trim(), this.commentDirectives);
+            if (this.lastVisitIsComment) {
+                this.commentDirectivesStack[this.commentDirectivesStack.length - 1] = this.commentDirectives;
+            }
+            else {
+                this.commentDirectivesStack.push(this.commentDirectives);
+            }
+            this.lastVisitIsComment = true;
+            return [];
+        }
+        if (node.type === 'text' && !node.value.trim()) {
+            return [];
+        }
+        let msgs = [];
+        const commentDirectivesPrev = this.commentDirectives;
+        if (this.lastVisitIsComment) {
+            this.commentDirectives = this.commentDirectivesStack.pop();
+            this.lastVisitIsComment = false;
+        }
+        if (this.commentDirectives.ignoreFile) {
+            return [];
+        }
+        if (this.commentDirectives.forceType !== false) {
+            msgs = this.visit(node);
+        }
+        this.commentDirectives = commentDirectivesPrev;
+        return msgs;
+    };
+    transformAs = async () => {
+        const { ast } = await parse(this.content);
+        this.mstr = new MagicString(this.content);
+        this.mixedVisitor = this.initMixedVisitor();
+        const msgs = this.visitAs(ast);
+        if (this.frontMatterStart == null) {
+            this.mstr.appendLeft(0, '---\n');
+            this.mstr.appendRight(0, '---\n');
+        }
+        const header = [
+            `import ${rtRenderFunc} from "@wuchale/astro/runtime.js"`,
+            this.initRuntime(),
+        ].join('\n');
+        return this.finalize(msgs, this.frontMatterStart ?? 0, header);
+    };
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+    "name": "@wuchale/astro",
+    "version": "0.2.0",
+    "description": "Wuchale i18n adapter for Astro files",
+    "scripts": {
+        "dev": "tsc --watch",
+        "build": "tsc",
+        "test": "node tests/index.ts"
+    },
+    "keywords": [
+        "i18n",
+        "internationalization",
+        "translation",
+        "gettext",
+        "astro",
+        "vite",
+        "po",
+        "vite-plugin",
+        "compile-time",
+        "ast",
+        "translation-tooling",
+        "multilingual",
+        "localization",
+        "l10n",
+        "automatic-i18n"
+    ],
+    "files": [
+        "dist",
+        "src/loaders"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./runtime.js": {
+            "types": "./dist/runtime.d.ts",
+            "default": "./dist/runtime.js"
+        }
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/wuchalejs/wuchale.git"
+    },
+    "homepage": "https://wuchale.dev",
+    "bugs": "https://github.com/wuchalejs/wuchale/issues",
+    "author": "K1DV5",
+    "license": "MIT",
+    "dependencies": {
+        "@astrojs/compiler": "^2.13.0",
+        "@sveltejs/acorn-typescript": "^1.0.8",
+        "acorn": "^8.15.0",
+        "magic-string": "^0.30.21",
+        "wuchale": "^0.19.0"
+    },
+    "devDependencies": {
+        "@types/estree-jsx": "^1.0.5",
+        "typescript": "^5.9.3"
+    },
+    "type": "module"
+}

package/src/loaders/astro.bundle.js

@@ -0,0 +1,21 @@
+// Astro bundle loader template (server-side, synchronous, all locales bundled)
+import { toRuntime } from 'wuchale/runtime'
+
+const catalogs = __CATALOGS__
+const locales = Object.keys(catalogs)
+
+const store = {}
+for (const locale of locales) {
+    store[locale] = toRuntime(catalogs[locale], locale)
+}
+
+// Get current locale from global context (set by middleware)
+function getCurrentLocale() {
+    return globalThis.__wuchale_locale__ || locales[0]
+}
+
+export const getRuntime = (/** @type {string} */ _loadID) => {
+    return store[getCurrentLocale()]
+}
+
+export const getRuntimeRx = getRuntime

package/src/loaders/astro.js

@@ -0,0 +1,14 @@
+// Astro loader template (server-side, synchronous)
+// This is a template file that wuchale will use to generate the actual loader
+import { loadCatalog, loadIDs } from '${PROXY_SYNC}'
+import { currentRuntime } from 'wuchale/load-utils/server'
+
+const key = '${KEY}'
+
+export { loadCatalog, loadIDs, key }
+
+// For non-reactive server-side rendering
+export const getRuntime = (/** @type {string} */ loadID) => currentRuntime(key, loadID)
+
+// Same function for compatibility
+export const getRuntimeRx = getRuntime