@gtkx/cli 1.3.0 → 1.5.0

package/src/i18n/catalog-template.ts

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync, renameSync } from "node:fs";
+
+const POT_CREATION_DATE = /^"POT-Creation-Date: .*\\n"$/m;
+
+const isUnchangedTemplate = (previous: string, next: string): boolean => {
+    const previousDate = POT_CREATION_DATE.exec(previous)?.[0];
+
+    return previousDate !== undefined && next.replace(POT_CREATION_DATE, () => previousDate) === previous;
+};
+
+const replaceCatalogTemplate = (source: string, output: string): void => {
+    if (existsSync(output)) {
+        const previous = readFileSync(output, "utf8");
+        const next = readFileSync(source, "utf8");
+
+        if (next === previous || isUnchangedTemplate(previous, next)) {
+            return;
+        }
+    }
+
+    renameSync(source, output);
+};
+
+export { replaceCatalogTemplate };

package/src/i18n/catalogs.ts

@@ -0,0 +1,216 @@
+import {
+    chmodSync,
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    readFileSync,
+    renameSync,
+    rmSync,
+    statSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { runCliTool } from "../internal/run-cli-tool.js";
+
+type Catalog = {
+    locale: string;
+    path: string;
+};
+
+type CatalogProject = {
+    catalogs: Catalog[];
+    domain: string;
+    linguasPath: string;
+    locales: string[];
+    poDir: string;
+    poFiles: string[];
+    root: string;
+};
+
+type PreparedCatalog = {
+    isChanged: boolean;
+    output: string;
+    target: string;
+};
+
+const PO_DIRNAME = "po";
+const LOCALE_DIRNAME = "locale";
+const LINGUAS_FILENAME = "LINGUAS";
+const LOCALE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.@+-]*$/;
+const DOMAIN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MODE_MASK = 0o7777;
+
+const parseLocales = (linguasPath: string): string[] => {
+    const source = readFileSync(linguasPath, "utf8");
+
+    const tokens = source
+        .split(/\r?\n/)
+        .flatMap((line) => line.replace(/#.*/, "").trim().split(/\s+/))
+        .filter((token) => token.length > 0);
+
+    const seen: Set<string> = new Set();
+
+    for (const token of tokens) {
+        if (!LOCALE_PATTERN.test(token) || seen.has(token)) {
+            throw new Error(`Invalid locale in ${linguasPath}: ${token}`);
+        }
+
+        seen.add(token);
+    }
+
+    return tokens;
+};
+
+const requireFile = (path: string): void => {
+    if (!existsSync(path) || !statSync(path).isFile()) {
+        throw new Error(`Missing translation catalog: ${path}`);
+    }
+};
+
+const requiresCatalogInitialization = (project: CatalogProject): boolean =>
+    project.catalogs.some((catalog) => !existsSync(catalog.path));
+
+const resolveCatalogProject = (root: string, domain: string): CatalogProject | null => {
+    const projectRoot = resolve(root);
+    const poDir = join(projectRoot, PO_DIRNAME);
+
+    if (!existsSync(poDir)) {
+        return null;
+    }
+
+    if (!statSync(poDir).isDirectory()) {
+        throw new Error(`Translation source is not a directory: ${poDir}`);
+    }
+
+    if (!DOMAIN_PATTERN.test(domain)) {
+        throw new Error(`Invalid translation domain: ${domain}`);
+    }
+
+    const linguasPath = join(poDir, LINGUAS_FILENAME);
+    requireFile(linguasPath);
+    const locales = parseLocales(linguasPath);
+    const catalogs = locales.map((locale) => ({ locale, path: join(poDir, `${locale}.po`) }));
+
+    return {
+        catalogs,
+        domain,
+        linguasPath,
+        locales,
+        poDir,
+        poFiles: catalogs.map((catalog) => catalog.path),
+        root: projectRoot,
+    };
+};
+
+const compileCatalogs = (project: CatalogProject, outputDir: string): string[] => {
+    const localeDir = resolve(outputDir);
+
+    for (const catalog of project.catalogs) {
+        requireFile(catalog.path);
+    }
+
+    return project.catalogs.map((catalog) => {
+        const output = join(localeDir, catalog.locale, "LC_MESSAGES", `${project.domain}.mo`);
+        mkdirSync(dirname(output), { recursive: true });
+
+        runCliTool({
+            tool: "msgfmt",
+            args: ["--check", "--output-file", output, catalog.path],
+            target: catalog.path,
+        });
+
+        return output;
+    });
+};
+
+const initializeCatalog = (catalog: Catalog, template: string, output: string): void => {
+    runCliTool({
+        tool: "msginit",
+        args: [
+            "--no-translator",
+            "--no-wrap",
+            `--locale=${catalog.locale}`,
+            `--input=${template}`,
+            `--output-file=${output}`,
+        ],
+        target: catalog.path,
+    });
+};
+
+const mergeCatalog = (catalog: Catalog, template: string, output: string): void => {
+    requireFile(catalog.path);
+
+    runCliTool({
+        tool: "msgmerge",
+        args: ["--quiet", "--no-wrap", `--output-file=${output}`, catalog.path, template],
+        target: catalog.path,
+    });
+
+    chmodSync(output, statSync(catalog.path).mode & MODE_MASK);
+};
+
+const prepareCatalog = (
+    catalog: Catalog,
+    index: number,
+    template: string,
+    stagingDir: string,
+): PreparedCatalog => {
+    const output = join(stagingDir, `${String(index)}.po`);
+    const isExisting = existsSync(catalog.path);
+
+    if (isExisting) {
+        mergeCatalog(catalog, template, output);
+    } else {
+        initializeCatalog(catalog, template, output);
+    }
+
+    return {
+        isChanged: !isExisting || !readFileSync(output).equals(readFileSync(catalog.path)),
+        output,
+        target: catalog.path,
+    };
+};
+
+const synchronizeCatalogs = (project: CatalogProject): void => {
+    if (project.catalogs.length === 0) {
+        return;
+    }
+
+    const template = join(project.poDir, `${project.domain}.pot`);
+    requireFile(template);
+    const stagingDir = mkdtempSync(join(project.poDir, ".gtkx-catalog-"));
+
+    try {
+        const merged = project.catalogs.map((catalog, index) =>
+            prepareCatalog(catalog, index, template, stagingDir));
+
+        for (const catalog of merged) {
+            if (catalog.isChanged) {
+                renameSync(catalog.output, catalog.target);
+            }
+        }
+    } finally {
+        rmSync(stagingDir, { recursive: true, force: true });
+    }
+};
+
+const isCatalogSource = (root: string, path: string): boolean => {
+    const projectRoot = resolve(root);
+    const sourcePath = isAbsolute(path) ? resolve(path) : resolve(projectRoot, path);
+    const poPath = relative(join(projectRoot, PO_DIRNAME), sourcePath);
+
+    if (poPath === "" || poPath === ".." || poPath.startsWith(`..${sep}`) || isAbsolute(poPath)) {
+        return false;
+    }
+
+    return !poPath.includes(sep) && (poPath === LINGUAS_FILENAME || poPath.endsWith(".po"));
+};
+
+export {
+    type CatalogProject,
+    LOCALE_DIRNAME,
+    compileCatalogs,
+    isCatalogSource,
+    requiresCatalogInitialization,
+    resolveCatalogProject,
+    synchronizeCatalogs,
+};

package/src/i18n/extractor-plugin.ts

@@ -0,0 +1,413 @@
+import type { Plugin, PluginContext } from "i18next-cli";
+import {
+    type BindingExtraction,
+    extractBindings,
+    type ScopeInfo,
+} from "./binding-extractor.js";
+
+type GtkxExtractorPlugin = {
+    plugin: Plugin;
+    transComponents: string[];
+};
+
+type ExtractorState = {
+    extraction: BindingExtraction;
+    sentinel: string;
+};
+
+type ReconciledNodes = {
+    blocked: Set<string>;
+    calls: Set<string>;
+    trans: Set<string>;
+};
+
+const emptyExtraction = (): BindingExtraction => ({
+    blockedGetFixedT: new Set(),
+    calls: new Map(),
+    errors: [],
+    messages: [],
+    trans: new Map(),
+});
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === "object" && value !== null;
+
+const nodeSpanKey = (node: Record<string, unknown>): string | undefined => {
+    if (!isRecord(node.span)) {
+        return;
+    }
+
+    return typeof node.span.start === "number" && typeof node.span.end === "number"
+        ? `${String(node.span.start)}:${String(node.span.end)}`
+        : undefined;
+};
+
+const identifier = (value: string, source: unknown): Record<string, unknown> => {
+    const span = isRecord(source) && isRecord(source.span) ? source.span : { end: 0, start: 0 };
+
+    return {
+        ctxt: 0,
+        optional: false,
+        span,
+        type: "Identifier",
+        value,
+    };
+};
+
+const sentinelFor = (code: string): string => {
+    let sentinel = "__gtkxI18nSentinel";
+
+    while (new RegExp(String.raw`\b${sentinel}\b`, "u").test(code)) {
+        sentinel += "_";
+    }
+
+    return sentinel;
+};
+
+const canonicalSource = (code: string): string => {
+    const hasBom = code.startsWith("\u{FEFF}");
+    let hashbangIndex = -1;
+
+    if (code.startsWith("#!")) {
+        hashbangIndex = 0;
+    } else if (hasBom && code.startsWith("#!", 1)) {
+        hashbangIndex = 1;
+    }
+
+    let canonical = hasBom ? ` ${code.slice(1)}` : code;
+
+    if (hashbangIndex !== -1) {
+        canonical = `${canonical.slice(0, hashbangIndex)}//${canonical.slice(hashbangIndex + 2)}`;
+    }
+
+    return `;${canonical}`;
+};
+
+const replaceCallCallee = (node: Record<string, unknown>, sentinel: string): void => {
+    node.callee = identifier(sentinel, node.callee);
+};
+
+const replaceJsxName = (element: unknown, sentinel: string): void => {
+    if (!isRecord(element)) {
+        return;
+    }
+
+    if (isRecord(element.opening)) {
+        element.opening.name = identifier(sentinel, element.opening.name);
+    }
+
+    if (isRecord(element.closing)) {
+        element.closing.name = identifier(sentinel, element.closing.name);
+    }
+};
+
+const isJsxAttribute = (value: unknown): value is Record<string, unknown> =>
+    isRecord(value) && value.type === "JSXAttribute";
+
+const isTAttributeName = (value: unknown): boolean =>
+    isRecord(value) && value.value === "t";
+
+const isExpressionContainer = (value: unknown): value is Record<string, unknown> =>
+    isRecord(value) && value.type === "JSXExpressionContainer";
+
+const transTExpression = (attribute: unknown): Record<string, unknown> | undefined => {
+    if (!isJsxAttribute(attribute)) {
+        return;
+    }
+
+    if (!isTAttributeName(attribute.name)) {
+        return;
+    }
+
+    if (!isExpressionContainer(attribute.value)) {
+        return;
+    }
+
+    return attribute.value;
+};
+
+const replaceTransTProp = (
+    element: Record<string, unknown>,
+    sentinel: string,
+    info: ScopeInfo | null,
+    context: PluginContext,
+): void => {
+    if (info === null || !isRecord(element.opening) || !Array.isArray(element.opening.attributes)) {
+        return;
+    }
+
+    for (const attribute of element.opening.attributes) {
+        const expression = transTExpression(attribute);
+
+        if (expression === undefined) {
+            continue;
+        }
+
+        context.setVarInScope(sentinel, info);
+        expression.expression = identifier(sentinel, expression.expression);
+
+        return;
+    }
+};
+
+const reconcileBlockedNode = (
+    value: Record<string, unknown>,
+    key: string,
+    extraction: BindingExtraction,
+    reconciled: ReconciledNodes,
+): void => {
+    if (value.type !== "VariableDeclarator") {
+        return;
+    }
+
+    if (!extraction.blockedGetFixedT.has(key)) {
+        return;
+    }
+
+    blockUnrelatedGetFixedT(value);
+    reconciled.blocked.add(key);
+};
+
+const reconcileCallNode = (
+    value: Record<string, unknown>,
+    key: string,
+    extraction: BindingExtraction,
+    reconciled: ReconciledNodes,
+): void => {
+    if (value.type === "CallExpression" && extraction.calls.has(key)) {
+        reconciled.calls.add(key);
+    }
+};
+
+const reconcileTransNode = (
+    value: Record<string, unknown>,
+    key: string,
+    extraction: BindingExtraction,
+    reconciled: ReconciledNodes,
+): void => {
+    if (value.type === "JSXElement" && extraction.trans.has(key)) {
+        reconciled.trans.add(key);
+    }
+};
+
+const reconcileNode = (
+    value: Record<string, unknown>,
+    extraction: BindingExtraction,
+    reconciled: ReconciledNodes,
+): void => {
+    const key = nodeSpanKey(value);
+
+    if (key === undefined) {
+        return;
+    }
+
+    reconcileBlockedNode(value, key, extraction, reconciled);
+    reconcileCallNode(value, key, extraction, reconciled);
+    reconcileTransNode(value, key, extraction, reconciled);
+};
+
+const visitModuleChild = (
+    child: unknown,
+    extraction: BindingExtraction,
+    reconciled: ReconciledNodes,
+): void => {
+    if (Array.isArray(child)) {
+        for (const item of child) {
+            visitModuleNode(item, extraction, reconciled);
+        }
+
+        return;
+    }
+
+    visitModuleNode(child, extraction, reconciled);
+};
+
+const visitModuleNode = (
+    value: unknown,
+    extraction: BindingExtraction,
+    reconciled: ReconciledNodes,
+): void => {
+    if (!isRecord(value)) {
+        return;
+    }
+
+    reconcileNode(value, extraction, reconciled);
+
+    for (const [name, child] of Object.entries(value)) {
+        if (name !== "span") {
+            visitModuleChild(child, extraction, reconciled);
+        }
+    }
+};
+
+const wasExtractionReconciled = (
+    extraction: BindingExtraction,
+    reconciled: ReconciledNodes,
+): boolean =>
+    reconciled.blocked.size === extraction.blockedGetFixedT.size &&
+    reconciled.calls.size === extraction.calls.size &&
+    reconciled.trans.size === extraction.trans.size;
+
+const blockUnrelatedGetFixedT = (declarator: Record<string, unknown>): void => {
+    if (!isRecord(declarator.init) || !isRecord(declarator.init.callee)) {
+        return;
+    }
+
+    const callee = declarator.init.callee;
+
+    if (
+        callee.type === "MemberExpression" &&
+        isRecord(callee.property) &&
+        callee.property.value === "getFixedT"
+    ) {
+        callee.property.value = "__gtkxIgnoredGetFixedT";
+    }
+};
+
+const prepareModule = (
+    module: Record<string, unknown>,
+    extraction: BindingExtraction,
+    context: PluginContext,
+): void => {
+    const reconciled: ReconciledNodes = {
+        blocked: new Set(),
+        calls: new Set(),
+        trans: new Set(),
+    };
+
+    visitModuleNode(module, extraction, reconciled);
+
+    if (!wasExtractionReconciled(extraction, reconciled)) {
+        context.logger.warn("GTKX could not reconcile the binding-aware and i18next syntax trees");
+    }
+};
+
+const submitMessages = (
+    extraction: BindingExtraction,
+    context: PluginContext,
+): void => {
+    for (const error of extraction.errors) {
+        context.logger.warn(error);
+    }
+
+    for (const message of extraction.messages) {
+        context.addKey({
+            key: message.key,
+            defaultValue: message.defaultValue,
+            explicitDefault: message.explicitDefault,
+            locations: [message.location],
+            ...(message.ns !== undefined && { ns: message.ns }),
+        });
+    }
+};
+
+const loadSource = async (
+    state: ExtractorState,
+    transComponents: string[],
+    code: string,
+    path: string,
+): Promise<string> => {
+    const canonical = canonicalSource(code);
+    state.extraction = await extractBindings(canonical, path);
+    state.sentinel = sentinelFor(canonical);
+    transComponents.splice(0, transComponents.length, state.sentinel);
+
+    return canonical;
+};
+
+const visitCall = (
+    state: ExtractorState,
+    node: Record<string, unknown>,
+    key: string,
+    context: PluginContext,
+): void => {
+    const call = state.extraction.calls.get(key);
+
+    if (call !== undefined) {
+        context.setVarInScope(state.sentinel, call.info);
+        replaceCallCallee(node, state.sentinel);
+    }
+};
+
+const visitTrans = (
+    state: ExtractorState,
+    node: Record<string, unknown>,
+    key: string,
+    context: PluginContext,
+): void => {
+    const transInfo = state.extraction.trans.get(key);
+
+    if (transInfo !== undefined) {
+        const tSentinel = `${state.sentinel}T`;
+        replaceJsxName(node, state.sentinel);
+        replaceTransTProp(node, tSentinel, transInfo, context);
+    }
+};
+
+const visitMatchedNode = (
+    state: ExtractorState,
+    node: Record<string, unknown>,
+    key: string,
+    context: PluginContext,
+): void => {
+    if (node.type === "VariableDeclarator" && state.extraction.blockedGetFixedT.has(key)) {
+        blockUnrelatedGetFixedT(node);
+
+        return;
+    }
+
+    if (node.type === "CallExpression") {
+        visitCall(state, node, key, context);
+
+        return;
+    }
+
+    if (node.type === "JSXElement") {
+        visitTrans(state, node, key, context);
+    }
+};
+
+const visitNode = (
+    state: ExtractorState,
+    node: unknown,
+    context: PluginContext,
+): void => {
+    if (!isRecord(node)) {
+        return;
+    }
+
+    if (node.type === "Module") {
+        prepareModule(node, state.extraction, context);
+        submitMessages(state.extraction, context);
+
+        return;
+    }
+
+    const key = nodeSpanKey(node);
+
+    if (key !== undefined) {
+        visitMatchedNode(state, node, key, context);
+    }
+};
+
+const gtkxExtractorPlugin = (): GtkxExtractorPlugin => {
+    const state: ExtractorState = {
+        extraction: emptyExtraction(),
+        sentinel: "__gtkxI18nSentinel",
+    };
+
+    const transComponents: string[] = [];
+
+    const plugin: Plugin = {
+        name: "gtkx-react-i18next",
+        onLoad: loadSource.bind(undefined, state, transComponents),
+        onVisitNode: visitNode.bind(undefined, state),
+    };
+
+    return {
+        plugin,
+        transComponents,
+    };
+};
+
+export { gtkxExtractorPlugin };

package/src/i18n/metadata-templates.ts

@@ -0,0 +1,29 @@
+import { join, relative } from "node:path";
+import type { CatalogProject } from "./catalogs.js";
+
+type MetadataTemplateKind = "desktop" | "metainfo.xml" | "mime.xml";
+
+type MetadataTemplateFile = {
+    kind: MetadataTemplateKind;
+    path: string;
+    relativePath: string;
+};
+
+const METADATA_TEMPLATE_KINDS: MetadataTemplateKind[] = ["desktop", "metainfo.xml", "mime.xml"];
+const METADATA_TEMPLATE_DIRNAME = ".gtkx-metadata";
+
+const metadataTemplateFile = (project: CatalogProject, kind: MetadataTemplateKind): MetadataTemplateFile => {
+    const path = join(project.poDir, METADATA_TEMPLATE_DIRNAME, `${project.domain}.template.${kind}`);
+    const relativePath = relative(project.root, path).replaceAll("\\", "/");
+
+    return { kind, path, relativePath };
+};
+
+const metadataTemplateFiles = (project: CatalogProject): MetadataTemplateFile[] =>
+    METADATA_TEMPLATE_KINDS.map((kind) => metadataTemplateFile(project, kind));
+
+export {
+    type MetadataTemplateKind,
+    metadataTemplateFile,
+    metadataTemplateFiles,
+};