@wpelevator/wp-release 0.16.0 → 0.17.0

package/dist/i18n/po.js

@@ -0,0 +1,180 @@
+import { po, mo } from 'gettext-parser';
+import postfixModule from '@tannin/postfix';
+import { ValidationError } from "../errors.js";
+import { compareText } from "./catalog.js";
+const postfix = postfixModule;
+/**
+ * Validate gettext plural expressions with Tannin's parser, without eval or Function.
+ * @param header
+ */
+function validatePluralForms(header) {
+    const match = /^\s*nplurals\s*=\s*([1-9]\d*)\s*;\s*plural\s*=\s*([^;]+)\s*;?\s*$/.exec(header);
+    if (!match || Number(match[1]) > 100) {
+        throw new ValidationError('PO requires a valid Plural-Forms header with nplurals and a plural expression.');
+    }
+    const expression = match[2] ?? '';
+    if (/[^\dn\s!%*/+<>=&|?:()\-]/.test(expression)) {
+        throw new ValidationError('Plural-Forms contains an unsupported expression token.');
+    }
+    try {
+        let depth = 0;
+        for (const term of postfix(expression)) {
+            if ('n' === term || /^\d+$/.test(String(term))) {
+                depth++;
+            }
+            else {
+                if (![
+                    '!',
+                    '*',
+                    '/',
+                    '%',
+                    '+',
+                    '-',
+                    '<',
+                    '<=',
+                    '>',
+                    '>=',
+                    '==',
+                    '!=',
+                    '&&',
+                    '||',
+                    '?:',
+                ].includes(term)) {
+                    throw new Error('Unsupported plural operator.');
+                }
+                let arity = 2;
+                if ('!' === term) {
+                    arity = 1;
+                }
+                if ('?:' === term) {
+                    arity = 3;
+                }
+                if (depth < arity) {
+                    throw new Error('Invalid operand count.');
+                }
+                depth -= arity - 1;
+            }
+        }
+        if (1 !== depth) {
+            throw new Error('Incomplete expression.');
+        }
+    }
+    catch (error) {
+        throw new ValidationError(`Malformed Plural-Forms expression: ${String(error)}`);
+    }
+    return Number(match[1]);
+}
+/**
+ * Parse translated PO as data, filtering fuzzy, obsolete and untranslated entries.
+ * @param contents
+ * @param domain
+ */
+export function parseTranslatedPo(contents, domain) {
+    let parsed;
+    try {
+        parsed = po.parse(contents, {
+            validation: true,
+            defaultCharset: 'UTF-8',
+        });
+    }
+    catch (error) {
+        throw new ValidationError(`Malformed PO catalog: ${String(error)}`);
+    }
+    if (!parsed.headers || !parsed.translations) {
+        throw new ValidationError('Malformed PO catalog: missing gettext headers or translations.');
+    }
+    const headers = Object.fromEntries(Object.entries(parsed.headers).map(([key, value]) => [
+        key.toLowerCase(),
+        value,
+    ]));
+    const locale = headers.language;
+    if (!locale || !/^[A-Za-z][A-Za-z0-9_@.-]*$/.test(locale)) {
+        throw new ValidationError('PO requires a non-empty valid Language header.');
+    }
+    const pluralForms = headers['plural-forms'] ?? '';
+    const nplurals = validatePluralForms(pluralForms);
+    const messages = [];
+    for (const entry of Object.values(parsed.translations).flatMap((context) => Object.values(context))) {
+        const flags = (entry.comments?.flag ?? '')
+            .split(',')
+            .map((flag) => flag.trim())
+            .filter(Boolean);
+        if (entry.msgid &&
+            !entry.obsolete &&
+            !flags.includes('fuzzy') &&
+            entry.msgstr.every((translation) => !!translation)) {
+            if (entry.msgstr.length !==
+                (undefined !== entry.msgid_plural ? nplurals : 1) ||
+                /[\0\u0004]/.test(entry.msgid) ||
+                /[\0\u0004]/.test(entry.msgctxt ?? '') ||
+                entry.msgstr.some((value) => value.includes('\0'))) {
+                throw new ValidationError(`Invalid translation forms or reserved separators for ${JSON.stringify(entry.msgid)}.`);
+            }
+            const references = (entry.comments?.reference ?? '')
+                .split(/\s+/)
+                .filter(Boolean)
+                .map((reference) => {
+                const location = /^(.*?)(?::(\d+))?$/.exec(reference);
+                return {
+                    file: location?.[1] ?? reference,
+                    ...(location?.[2]
+                        ? { line: Number(location[2]) }
+                        : {}),
+                };
+            });
+            messages.push({
+                id: entry.msgid,
+                ...(undefined !== entry.msgid_plural
+                    ? { plural: entry.msgid_plural }
+                    : {}),
+                ...(undefined !== entry.msgctxt
+                    ? { context: entry.msgctxt }
+                    : {}),
+                translations: [...entry.msgstr],
+                flags,
+                references,
+                comments: (entry.comments?.extracted ?? '')
+                    .split('\n')
+                    .filter(Boolean),
+            });
+        }
+    }
+    messages.sort((a, b) => compareText(translationKey(a), translationKey(b)));
+    return { domain, headers, messages, locale, pluralForms, nplurals };
+}
+/**
+ * WordPress/Jed lookup key uses context + EOT + singular, even for plural messages.
+ * @param message
+ */
+export function translationKey(message) {
+    return (message.context ? `${message.context}\u0004` : '') + message.id;
+}
+/**
+ * Compile MO through gettext-parser; never write or mutate the input PO.
+ * @param catalog
+ */
+export function compileMo(catalog) {
+    const table = {
+        charset: 'UTF-8',
+        headers: {
+            ...catalog.headers,
+            'content-type': 'text/plain; charset=UTF-8',
+        },
+        translations: Object.create(null),
+    };
+    for (const message of catalog.messages) {
+        const context = message.context ?? '';
+        table.translations[context] ??= Object.create(null);
+        table.translations[context][message.id] = {
+            msgid: message.id,
+            ...(undefined !== message.context
+                ? { msgctxt: message.context }
+                : {}),
+            ...(undefined !== message.plural
+                ? { msgid_plural: message.plural }
+                : {}),
+            msgstr: [...message.translations],
+        };
+    }
+    return mo.compile(table);
+}

package/dist/i18n/pot.d.ts

@@ -0,0 +1,16 @@
+import type { Catalog } from './catalog.ts';
+/**
+ * Serialize deterministic UTF-8 POT bytes in the gettext layout, with no wall-clock data.
+ *
+ * Messages keep the catalog order, and each entry lists extracted comments, references and flags before its strings.
+ *
+ * @param catalog             Catalog to serialize.
+ * @param options             Serialization options.
+ * @param options.references  Whether to include source references (default true).
+ * @param options.fileComment Static text to prepend as gettext comments.
+ * @return POT file contents.
+ */
+export declare function serializePot(catalog: Catalog, options?: {
+    references?: boolean;
+    fileComment?: string;
+}): Buffer;

package/dist/i18n/pot.js

@@ -0,0 +1,119 @@
+import { mergeI18nHeaders, validateI18nFileComment, validateI18nHeaders, } from "./options.js";
+const ESCAPES = {
+    '\\': '\\\\',
+    '"': '\\"',
+    '\x07': '\\a',
+    '\b': '\\b',
+    '\f': '\\f',
+    '\n': '\\n',
+    '\r': '\\r',
+    '\t': '\\t',
+    '\v': '\\v',
+};
+/**
+ * Serialize deterministic UTF-8 POT bytes in the gettext layout, with no wall-clock data.
+ *
+ * Messages keep the catalog order, and each entry lists extracted comments, references and flags before its strings.
+ *
+ * @param catalog             Catalog to serialize.
+ * @param options             Serialization options.
+ * @param options.references  Whether to include source references (default true).
+ * @param options.fileComment Static text to prepend as gettext comments.
+ * @return POT file contents.
+ */
+export function serializePot(catalog, options = {}) {
+    validateI18nHeaders(catalog.headers);
+    if (undefined !== options.fileComment) {
+        validateI18nFileComment(options.fileComment);
+    }
+    const fileComment = undefined === options.fileComment
+        ? ''
+        : options.fileComment
+            .split(/\r\n|\r|\n/)
+            .map((line) => `# ${line}\n`)
+            .join('');
+    const entries = catalog.messages.map((message) => serializeMessage(message, false !== options.references));
+    return Buffer.from(fileComment + [serializeHeaders(catalog), ...entries].join('\n'));
+}
+/**
+ * Serialize the header entry: the default headers in a fixed order, overridden in place or removed with `false`, then custom headers in the given order.
+ *
+ * @param catalog Catalog with the domain and header overrides.
+ * @return Header entry.
+ */
+function serializeHeaders(catalog) {
+    const defaults = {
+        'Project-Id-Version': catalog.domain,
+        'Report-Msgid-Bugs-To': '',
+        'Last-Translator': '',
+        'Language-Team': '',
+        'MIME-Version': '1.0',
+        'Content-Type': 'text/plain; charset=UTF-8',
+        'Content-Transfer-Encoding': '8bit',
+        'POT-Creation-Date': '',
+        'PO-Revision-Date': '',
+        'X-Domain': catalog.domain,
+    };
+    const headers = Object.entries(mergeI18nHeaders(defaults, catalog.headers))
+        .filter(([, value]) => false !== value)
+        .map(([name, value]) => `"${escape(`${name}: ${value}\n`)}"\n`);
+    return `msgid ""\nmsgstr ""\n${headers.join('')}`;
+}
+/**
+ * Serialize one message entry.
+ *
+ * @param message    Catalog message.
+ * @param references Whether to include source references.
+ * @return Message entry.
+ */
+function serializeMessage(message, references) {
+    const lines = [
+        ...message.comments.flatMap((comment) => comment.split(/\r\n|\r|\n/).map((line) => `#. ${line}`)),
+        ...(references
+            ? [
+                ...new Set(message.references.map((reference) => `#: ${reference.file}${reference.line ? `:${reference.line}` : ''}`)),
+            ]
+            : []),
+        ...(message.flags.length
+            ? [`#, ${message.flags.join(', ')}`]
+            : []),
+        ...(undefined !== message.context
+            ? [poString('msgctxt', message.context)]
+            : []),
+        poString('msgid', message.id),
+    ];
+    if (undefined === message.plural) {
+        lines.push('msgstr ""');
+    }
+    else {
+        lines.push(poString('msgid_plural', message.plural), 'msgstr[0] ""', 'msgstr[1] ""');
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Format a gettext keyword and string, splitting strings with newlines into one line per segment.
+ *
+ * @param keyword Gettext keyword, like msgid.
+ * @param value   String value.
+ * @return Serialized keyword lines.
+ */
+function poString(keyword, value) {
+    if (!value.includes('\n')) {
+        return `${keyword} "${escape(value)}"`;
+    }
+    return [
+        `${keyword} ""`,
+        ...value
+            .split(/(?<=\n)/)
+            .map((segment) => `"${escape(segment)}"`),
+    ].join('\n');
+}
+/**
+ * Escape a string for a quoted gettext string.
+ *
+ * @param value Raw string.
+ * @return Escaped string.
+ */
+function escape(value) {
+    return value.replace(/[\\"\x07\b\f\n\r\t\v]/g, (character) => ESCAPES[character] ?? character);
+}

package/dist/i18n/translation-json.d.ts

@@ -0,0 +1,14 @@
+import type { TranslatedCatalog } from './po.ts';
+/** Many-to-many source references to runtime scripts, both relative to the package. */
+export type ScriptTranslationMap = Record<string, string[]>;
+export interface ScriptTranslationOutput {
+    file: string;
+    source: string;
+    bytes: Buffer;
+}
+/**
+ * Compile deterministic Jed catalogs using explicit source/build mapping or unbundled identity paths.
+ * @param catalog
+ * @param mapping
+ */
+export declare function compileScriptTranslations(catalog: TranslatedCatalog, mapping?: ScriptTranslationMap): ScriptTranslationOutput[];

package/dist/i18n/translation-json.js

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { ValidationError } from "../errors.js";
+import { compareText } from "./catalog.js";
+import { translationKey } from "./po.js";
+function normalizedPath(path) {
+    if (!path ||
+        path.includes('\\') ||
+        path.includes('\0') ||
+        posix.isAbsolute(path) ||
+        /^[A-Za-z]:/.test(path) ||
+        path
+            .split('/')
+            .some((component) => ['', '.', '..'].includes(component))) {
+        throw new ValidationError(`Script translation paths must be normalized package-relative paths: ${path}.`);
+    }
+    return path;
+}
+/**
+ * Compile deterministic Jed catalogs using explicit source/build mapping or unbundled identity paths.
+ * @param catalog
+ * @param mapping
+ */
+export function compileScriptTranslations(catalog, mapping) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(catalog.domain)) {
+        throw new ValidationError('JSON compilation requires a safe text domain filename component.');
+    }
+    if (mapping) {
+        for (const [source, scripts] of Object.entries(mapping)) {
+            normalizedPath(source);
+            if (!Array.isArray(scripts) ||
+                scripts.some((script) => 'string' !== typeof script)) {
+                throw new ValidationError('Script maps must contain arrays of runtime script paths.');
+            }
+            scripts.forEach(normalizedPath);
+        }
+    }
+    const groups = new Map();
+    for (const message of catalog.messages) {
+        for (const reference of message.references) {
+            const source = normalizedPath(reference.file);
+            let scripts = [];
+            if (mapping) {
+                scripts = Object.hasOwn(mapping, source)
+                    ? mapping[source] ?? []
+                    : [];
+            }
+            else if (/\.(?:js|mjs|cjs)$/.test(source)) {
+                scripts = [source];
+            }
+            else if (/\.(?:jsx|tsx?|mts|cts)$/.test(source)) {
+                throw new ValidationError(`A source-to-runtime script map is required for ${source}.`);
+            }
+            for (const script of scripts) {
+                // WordPress hashes the unminified script path when the registered URL ends in .min.js.
+                const runtime = normalizedPath(script).replace(/\.min\.js$/, '.js');
+                if (!/\.(?:js|mjs|cjs)$/.test(runtime)) {
+                    throw new ValidationError(`Runtime translation target must be a JavaScript file: ${runtime}.`);
+                }
+                const entries = groups.get(runtime) ??
+                    new Map();
+                entries.set(translationKey(message), message);
+                groups.set(runtime, entries);
+            }
+        }
+    }
+    return [...groups.entries()]
+        .sort(([a], [b]) => compareText(a, b))
+        .map(([source, entries]) => {
+        const translations = Object.create(null);
+        translations[''] = {
+            domain: catalog.domain,
+            lang: catalog.locale,
+            'plural-forms': catalog.pluralForms,
+        };
+        for (const [key, message] of [...entries].sort(([a], [b]) => compareText(a, b))) {
+            translations[key] = [...message.translations];
+        }
+        const data = {
+            'translation-revision-date': catalog.headers['po-revision-date'] ?? '',
+            generator: '@wpelevator/wp-release',
+            domain: catalog.domain,
+            locale_data: { messages: translations },
+            source,
+        };
+        return {
+            source,
+            file: `${'default' === catalog.domain
+                ? catalog.locale
+                : `${catalog.domain}-${catalog.locale}`}-${createHash('md5')
+                .update(source)
+                .digest('hex')}.json`,
+            bytes: Buffer.from(JSON.stringify(data) + '\n'),
+        };
+    });
+}

package/dist/i18n/translation-php.d.ts

@@ -0,0 +1,6 @@
+import type { TranslatedCatalog } from './po.ts';
+/**
+ * WordPress 6.5+ translation-array format; catalog text is never interpolated as PHP code.
+ * @param catalog
+ */
+export declare function compilePhpTranslations(catalog: TranslatedCatalog): Buffer;

package/dist/i18n/translation-php.js

@@ -0,0 +1,35 @@
+import { compareText } from "./catalog.js";
+import { translationKey } from "./po.js";
+/**
+ * Single-quoted PHP data values; NUL separators use an explicit safe literal expression.
+ * @param value
+ */
+function phpString(value) {
+    return value
+        .split('\0')
+        .map((part) => `'${part
+        .replaceAll('\\', '\\\\')
+        .replaceAll("'", "\\'")}'`)
+        .join(' . "\\0" . ');
+}
+/**
+ * WordPress 6.5+ translation-array format; catalog text is never interpolated as PHP code.
+ * @param catalog
+ */
+export function compilePhpTranslations(catalog) {
+    const headers = Object.entries(catalog.headers)
+        .filter(([key]) => 'messages' !== key)
+        .sort(([a], [b]) => compareText(a, b));
+    const messages = catalog.messages.map((message) => `\t\t${phpString(translationKey(message))} => ${phpString(message.translations.join('\0'))},`);
+    const lines = [
+        '<?php',
+        'return [',
+        ...headers.map(([key, value]) => `\t${phpString(key)} => ${phpString(value)},`),
+        "\t'messages' => [",
+        ...messages,
+        '\t],',
+        '];',
+        '',
+    ];
+    return Buffer.from(lines.join('\n'));
+}

package/dist/index.d.ts

@@ -65,3 +65,25 @@ export type { BuildPackageInput, BuildPackageResult } from './package-build.ts';
 export type { BuildResult } from './commands/build.ts';
 export { wordpressCodec, sha256sumCodec, resolveManifestCodec, readIntegrity, } from './integrity.ts';
 export type { ManifestCodec, IntegrityConfig } from './integrity.ts';
+export { aggregateCatalog, hasFatalDiagnostics } from './i18n/catalog.ts';
+export type { Catalog, CatalogMessage, ExtractedMessage, SourceReference, I18nDiagnostic, ExtractionResult, CatalogResult, } from './i18n/catalog.ts';
+export { parsePhpTranslations } from './i18n/php.ts';
+export { parseJavascriptTranslations } from './i18n/javascript.ts';
+export { parseMetadataTranslations, extractHeaderTranslations, } from './i18n/metadata.ts';
+export type { ParseSourceInput } from './i18n/extraction.ts';
+export { auditCatalog } from './i18n/audit.ts';
+export { serializePot } from './i18n/pot.ts';
+export { discoverI18nFiles } from './i18n/files.ts';
+export { resolveI18nOptions, DEFAULT_I18N_INCLUDE, DEFAULT_I18N_EXCLUDE, } from './i18n/options.ts';
+export type { I18nHeaders, I18nOptions } from './i18n/options.ts';
+export { extractCatalog, generatePackagePot, resolvePotPath, validatePotDestinations, } from './i18n/generate.ts';
+export type { ExtractCatalogInput, ExtractCatalogResult, PackagePotInput, PackagePotResult, } from './i18n/generate.ts';
+export { resolveI18nPackages } from './i18n/packages.ts';
+export type { I18nPackageInput, I18nPackage } from './i18n/packages.ts';
+export { parseTranslatedPo, compileMo } from './i18n/po.ts';
+export type { TranslatedCatalog } from './i18n/po.ts';
+export { compileScriptTranslations } from './i18n/translation-json.ts';
+export type { ScriptTranslationMap, ScriptTranslationOutput, } from './i18n/translation-json.ts';
+export { compilePhpTranslations } from './i18n/translation-php.ts';
+export { compileTranslations } from './i18n/compile.ts';
+export type { CompileTranslationsInput, CompileTranslationsResult, } from './i18n/compile.ts';

package/dist/index.js

@@ -29,3 +29,17 @@ export { getDeployPackages, getGitDeploys, getPackageFiles, getSvnDeploys, } fro
 export { zipPackage } from "./package-zip.js";
 export { buildPackage } from "./package-build.js";
 export { wordpressCodec, sha256sumCodec, resolveManifestCodec, readIntegrity, } from "./integrity.js";
+export { aggregateCatalog, hasFatalDiagnostics } from "./i18n/catalog.js";
+export { parsePhpTranslations } from "./i18n/php.js";
+export { parseJavascriptTranslations } from "./i18n/javascript.js";
+export { parseMetadataTranslations, extractHeaderTranslations, } from "./i18n/metadata.js";
+export { auditCatalog } from "./i18n/audit.js";
+export { serializePot } from "./i18n/pot.js";
+export { discoverI18nFiles } from "./i18n/files.js";
+export { resolveI18nOptions, DEFAULT_I18N_INCLUDE, DEFAULT_I18N_EXCLUDE, } from "./i18n/options.js";
+export { extractCatalog, generatePackagePot, resolvePotPath, validatePotDestinations, } from "./i18n/generate.js";
+export { resolveI18nPackages } from "./i18n/packages.js";
+export { parseTranslatedPo, compileMo } from "./i18n/po.js";
+export { compileScriptTranslations } from "./i18n/translation-json.js";
+export { compilePhpTranslations } from "./i18n/translation-php.js";
+export { compileTranslations } from "./i18n/compile.js";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@wpelevator/wp-release",
-	"version": "0.16.0",
-	"description": "Package, checksum, sign, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org SVN",
+	"version": "0.17.0",
+	"description": "Package, checksum, sign, verify and version-check WordPress plugins and themes, extract and compile their translations, and deploy plugins to WordPress.org SVN",
 	"license": "MIT",
 	"author": "WP Elevator (https://wpelevator.com)",
 	"homepage": "https://github.com/wpelevator/basement/tree/main/packages/js/wp-release#readme",
@@ -42,15 +42,27 @@
 		"svn",
 		"zip",
 		"checksums",
-		"signing"
+		"signing",
+		"i18n",
+		"gettext",
+		"pot"
 	],
 	"dependencies": {
+		"@tannin/postfix": "^1.1.0",
+		"@babel/parser": "^7.29.7",
+		"@babel/traverse": "^7.29.7",
+		"gettext-parser": "^8.0.0",
 		"ignore": "^7.0.12",
+		"minimatch": "^10.2.6",
+		"php-parser": "^3.7.0",
 		"semver": "^7.7.1",
 		"yauzl": "^3.4.0",
 		"yazl": "^3.3.1"
 	},
 	"devDependencies": {
+		"@babel/types": "^7.29.7",
+		"@types/babel__traverse": "^7.28.0",
+		"@types/gettext-parser": "^9.0.0",
 		"@types/node": "^22.20.5",
 		"@types/semver": "^7.8.0",
 		"@types/yauzl": "^3.4.0",