@gtkx/cli 2.0.0-beta.1 → 2.0.0-beta.2

package/src/i18n/source-messages.ts

@@ -1,4 +1,6 @@
 import type { ExtractedKey, ExtractedKeysMap, Logger, Plugin } from "i18next-cli";
+import type { ESTree } from "vite";
+import { type NodePath, parseSync as parseBabelSync, type Scope, traverse, types } from "@babel/core";
 import { isPathInside, isPathWithin, toPosixPath } from "@gtkx/utils";
 import { runExtractor } from "i18next-cli";
 import {
@@ -10,8 +12,10 @@ import {
     writeFileSync,
 } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { parseSync, Visitor } from "vite";
 import type { CatalogProject } from "./catalogs.js";
 import { runCliTool } from "../internal/run-cli-tool.js";
+import { sourceLanguage } from "../internal/source-imports.js";
 import { replaceCatalogTemplate } from "./catalog-template.js";
 import { metadataTemplateFiles } from "./metadata-templates.js";
 import { clearI18nResources, i18nToolkitConfig } from "./types.js";
@@ -21,6 +25,7 @@ type SourceLocation = {
     line?: number | undefined;
     column?: number | undefined;
 };
+type ExtractedLocation = NonNullable<ExtractedKey["locations"]>[number];
 
 type SourceMessage = {
     context: string | null;
@@ -62,10 +67,50 @@ type PluralGroup = {
     variants: PluralVariant[];
 };
 
+type TranslationReferences = {
+    calls: Set<number>;
+    elements: Set<number>;
+    entryLocations: Map<string, SourcePoint[]>;
+    locations: Set<string>;
+    masks: SourceMask[];
+};
+type SourceMask = { end: number; start: number };
+type SourcePoint = { column: number; line: number };
+type TranslationCallKind = "alias" | "canonical";
+type ImportedBinding = {
+    imported: string;
+    local: string;
+    source: string;
+    style: "default" | "named" | "namespace";
+};
+type TranslationHookBinding = { call: types.CallExpression; isCanonical: boolean };
+type TranslationMemberExpression = types.MemberExpression | types.OptionalMemberExpression;
+type ResolvedBinding = NonNullable<ReturnType<Scope["getBinding"]>>;
+
 const CONTEXT_SEPARATOR = "\u{4}";
 const DEFAULT_NAMESPACE = "translation";
 const POTFILES_FILENAME = "POTFILES.in";
 const SYNTHETIC_FILENAME = "messages.js";
+const UNSUPPORTED_PLURAL_OPTION = /^defaultValue_(few|many|two|zero)$/u;
+const STATIC_SOURCE_OPTION_NAMES: ReadonlySet<string> = new Set([
+    "context",
+    "defaultValue",
+    "defaultValue_one",
+    "defaultValue_other",
+    "keyPrefix",
+]);
+const NESTED_CONTEXT = /["']?context["']?\s*:\s*(?:"([^"]*)"|'([^']*)')/u;
+const NESTED_COUNT = /["']?count["']?\s*:/u;
+const NESTED_STRUCTURE_TOKEN = /"[^"]*"|'[^']*'|[()]/gu;
+const TRANSLATION_MODULES = new Set(["@gtkx/i18n", "i18next"]);
+const TRANS_ELEMENTS: ReadonlySet<string> = new Set(["Trans", "TransWithoutContext"]);
+const STATIC_KEY_WRAPPER_TYPES: ReadonlySet<string> = new Set([
+    "ParenthesizedExpression",
+    "TSAsExpression",
+    "TSSatisfiesExpression",
+    "TSTypeAssertion",
+    "TSNonNullExpression",
+]);
 
 const quietLogger = (): { logger: Logger; reports: string[] } => {
     const reports: string[] = [];
@@ -294,6 +339,1164 @@ const normalizedSourceFiles = (root: string, paths: string[]): string[] => {
     return new Set(files).values().toArray().toSorted((left, right) => left.localeCompare(right));
 };
 
+type StaticKeyWrapper = ESTree.ParenthesizedExpression |
+    ESTree.TSAsExpression |
+    ESTree.TSSatisfiesExpression |
+    ESTree.TSTypeAssertion |
+    ESTree.TSNonNullExpression;
+
+const isStaticKeyWrapper = (key: ESTree.Node): key is StaticKeyWrapper =>
+    STATIC_KEY_WRAPPER_TYPES.has(key.type);
+
+const unwrapStaticWrapper = (node: ESTree.Node): ESTree.Node =>
+    isStaticKeyWrapper(node) ? unwrapStaticWrapper(node.expression) : node;
+
+const isStaticTranslationKey = (key: ESTree.Node | null | undefined): boolean => {
+    if (key === undefined || key === null) {
+        return false;
+    }
+
+    if (key.type === "Literal") {
+        return typeof key.value === "string";
+    }
+
+    if (key.type === "TemplateLiteral") {
+        return key.expressions.length === 0;
+    }
+
+    if (key.type === "ParenthesizedExpression") {
+        return false;
+    }
+
+    if (isStaticKeyWrapper(key)) {
+        return isStaticTranslationKey(key.expression);
+    }
+
+    return false;
+};
+
+const assertStaticTranslationKey = (key: ESTree.Node | null | undefined): void => {
+    if (!isStaticTranslationKey(key)) {
+        throw new Error("Translation keys must be string literals");
+    }
+};
+
+const propertyName = (property: ESTree.ObjectProperty): string | null => {
+    if (!property.computed && property.key.type === "Identifier") {
+        return property.key.name;
+    }
+
+    return property.key.type === "Literal" && typeof property.key.value === "string"
+        ? property.key.value
+        : null;
+};
+
+const assertSupportedOptionProperty = (property: ESTree.ObjectPropertyKind): void => {
+    if (property.type === "SpreadElement") {
+        throw new Error("Translation extraction requires explicit option properties");
+    }
+
+    const name = propertyName(property);
+
+    if (name === null) {
+        throw new Error("Translation extraction requires static option property names");
+    }
+
+    if (UNSUPPORTED_PLURAL_OPTION.test(name)) {
+        throw new Error("GNU gettext accepts one singular and one plural source string");
+    }
+
+    if (STATIC_SOURCE_OPTION_NAMES.has(name)) {
+        assertStaticTranslationKey(property.value);
+    }
+};
+
+const assertSupportedOptionObject = (options: ESTree.Node | null | undefined): void => {
+    if (options === null || options === undefined) {
+        return;
+    }
+
+    if (isStaticKeyWrapper(options) && unwrapStaticWrapper(options).type === "ObjectExpression") {
+        throw new Error("Translation option objects cannot be wrapped in another expression");
+    }
+
+    if (options.type !== "ObjectExpression") {
+        throw new Error("Translation option objects must be inline object literals");
+    }
+
+    for (const property of options.properties) {
+        assertSupportedOptionProperty(property);
+    }
+};
+
+const namedImportedBinding = (path: NodePath, source: string): ImportedBinding | null => {
+    if (!path.isImportSpecifier() || path.node.importKind === "type") {
+        return null;
+    }
+
+    const imported = path.node.imported;
+
+    return {
+        imported: types.isIdentifier(imported) ? imported.name : imported.value,
+        local: path.node.local.name,
+        source,
+        style: "named",
+    };
+};
+
+const defaultImportedBinding = (path: NodePath, source: string): ImportedBinding | null =>
+    path.isImportDefaultSpecifier()
+        ? { imported: "default", local: path.node.local.name, source, style: "default" }
+        : null;
+
+const namespaceImportedBinding = (path: NodePath, source: string): ImportedBinding | null =>
+    path.isImportNamespaceSpecifier()
+        ? { imported: "*", local: path.node.local.name, source, style: "namespace" }
+        : null;
+
+const importedBinding = (binding: ResolvedBinding | undefined): ImportedBinding | null => {
+    if (binding === undefined) {
+        return null;
+    }
+
+    const path = binding.path;
+    const declaration = path.parentPath;
+
+    if (!declaration.isImportDeclaration() || declaration.node.importKind === "type") {
+        return null;
+    }
+
+    const source = declaration.node.source.value;
+
+    return namedImportedBinding(path, source) ??
+        defaultImportedBinding(path, source) ??
+        namespaceImportedBinding(path, source);
+};
+
+const babelPropertyName = (property: types.ObjectProperty): string | null => {
+    const key = property.key;
+
+    if (!property.computed && types.isIdentifier(key)) {
+        return key.name;
+    }
+
+    return types.isStringLiteral(key) ? key.value : null;
+};
+
+const isBoundIdentifier = (node: types.Node | null, name: string): boolean => {
+    if (types.isIdentifier(node)) {
+        return node.name === name;
+    }
+
+    if (types.isAssignmentPattern(node)) {
+        return types.isIdentifier(node.left) && node.left.name === name;
+    }
+
+    return false;
+};
+
+const isHookPatternBinding = (pattern: types.VariableDeclarator["id"], name: string): boolean => {
+    if (types.isObjectPattern(pattern)) {
+        return pattern.properties.some((property) =>
+            types.isObjectProperty(property) &&
+            babelPropertyName(property) === "t" &&
+            isBoundIdentifier(property.value, name));
+    }
+
+    if (types.isArrayPattern(pattern)) {
+        return isBoundIdentifier(pattern.elements[0] ?? null, name);
+    }
+
+    return false;
+};
+
+const importedTranslationHook = (scope: Scope, call: types.CallExpression): ImportedBinding | null => {
+    if (!types.isIdentifier(call.callee)) {
+        return null;
+    }
+
+    const imported = importedBinding(scope.getBinding(call.callee.name));
+
+    return imported?.imported === "useTranslation" && TRANSLATION_MODULES.has(imported.source)
+        ? imported
+        : null;
+};
+
+const translationHookBinding = (binding: ResolvedBinding): TranslationHookBinding | null => {
+    const path = binding.path;
+
+    if (!path.isVariableDeclarator()) {
+        return null;
+    }
+
+    const pattern = path.node.id;
+    const initializer = path.node.init;
+
+    if (!isHookPatternBinding(pattern, binding.identifier.name) ||
+        !types.isCallExpression(initializer)) {
+        return null;
+    }
+
+    const imported = importedTranslationHook(path.scope, initializer);
+
+    if (imported === null) {
+        return null;
+    }
+
+    return { call: initializer, isCanonical: imported.local === "useTranslation" };
+};
+
+const importedTranslationFunctionKind = (imported: ImportedBinding | null): TranslationCallKind | null => {
+    if (imported?.imported !== "t" || !TRANSLATION_MODULES.has(imported.source)) {
+        return null;
+    }
+
+    return imported.local === "t" ? "canonical" : "alias";
+};
+
+const hookTranslationFunctionKind = (binding: ResolvedBinding | undefined): TranslationCallKind | null => {
+    if (binding === undefined) {
+        return null;
+    }
+
+    const hook = translationHookBinding(binding);
+
+    if (hook === null) {
+        return null;
+    }
+
+    return binding.identifier.name === "t" && hook.isCanonical ? "canonical" : "alias";
+};
+
+const directTranslationFunctionKind = (scope: Scope, name: string): TranslationCallKind | null => {
+    const binding = scope.getBinding(name);
+
+    return importedTranslationFunctionKind(importedBinding(binding)) ?? hookTranslationFunctionKind(binding);
+};
+
+const babelMemberName = (member: TranslationMemberExpression): string | null => {
+    const property = member.property;
+
+    if (member.computed) {
+        return types.isStringLiteral(property) ? property.value : null;
+    }
+
+    return types.isIdentifier(property) ? property.name : null;
+};
+
+const isImportedTranslationObject = (scope: Scope, object: types.Node): boolean => {
+    if (!types.isIdentifier(object)) {
+        return false;
+    }
+
+    const imported = importedBinding(scope.getBinding(object.name));
+
+    return imported !== null &&
+        TRANSLATION_MODULES.has(imported.source) &&
+        (imported.style === "namespace" || (imported.source === "i18next" && imported.imported === "default"));
+};
+
+const constantVariableDeclarator = (binding: ResolvedBinding): NodePath<types.VariableDeclarator> | null => {
+    const path = binding.path;
+    const declaration = path.parentPath;
+
+    if (!path.isVariableDeclarator() ||
+        !declaration.isVariableDeclaration() ||
+        declaration.node.kind !== "const") {
+        return null;
+    }
+
+    return path;
+};
+
+const isTranslationHookResultBinding = (binding: ResolvedBinding | undefined): boolean => {
+    if (binding === undefined) {
+        return false;
+    }
+
+    const path = constantVariableDeclarator(binding);
+    const initializer = path?.node.init;
+
+    return path !== null &&
+        types.isIdentifier(path.node.id) &&
+        types.isCallExpression(initializer) &&
+        importedTranslationHook(path.scope, initializer) !== null;
+};
+
+const isHookTranslationMember = (scope: Scope, member: TranslationMemberExpression): boolean => {
+    if (babelMemberName(member) !== "t") {
+        return false;
+    }
+
+    const object = member.object;
+
+    if (types.isCallExpression(object)) {
+        return importedTranslationHook(scope, object) !== null;
+    }
+
+    return types.isIdentifier(object) && isTranslationHookResultBinding(scope.getBinding(object.name));
+};
+
+const isTranslationMember = (scope: Scope, member: TranslationMemberExpression): boolean =>
+    babelMemberName(member) === "t" &&
+    (isImportedTranslationObject(scope, member.object) || isHookTranslationMember(scope, member));
+
+const isDirectTranslationFunction = (scope: Scope, node: types.Node): boolean =>
+    types.isIdentifier(node) && directTranslationFunctionKind(scope, node.name) !== null;
+
+const isTranslationFunctionValue = (scope: Scope, node: types.Node): boolean => {
+    if (isDirectTranslationFunction(scope, node)) {
+        return true;
+    }
+
+    return (types.isMemberExpression(node) || types.isOptionalMemberExpression(node)) &&
+        isTranslationMember(scope, node);
+};
+
+const isTranslationBindCall = (scope: Scope, node: types.Node): boolean => {
+    if (!types.isCallExpression(node) || !types.isMemberExpression(node.callee)) {
+        return false;
+    }
+
+    return babelMemberName(node.callee) === "bind" &&
+        isTranslationFunctionValue(scope, node.callee.object);
+};
+
+const isTranslationObjectPatternAlias = (
+    path: NodePath<types.VariableDeclarator>,
+    binding: ResolvedBinding,
+): boolean => {
+    const pattern = path.node.id;
+    const initializer = path.node.init;
+
+    if (!types.isObjectPattern(pattern) ||
+        !isHookPatternBinding(pattern, binding.identifier.name) ||
+        !types.isIdentifier(initializer)) {
+        return false;
+    }
+
+    return isImportedTranslationObject(path.scope, initializer) ||
+        isTranslationHookResultBinding(path.scope.getBinding(initializer.name));
+};
+
+const isTranslationAliasBinding = (binding: ResolvedBinding | undefined): boolean => {
+    if (binding === undefined) {
+        return false;
+    }
+
+    const path = constantVariableDeclarator(binding);
+
+    if (path === null) {
+        return false;
+    }
+
+    if (isTranslationObjectPatternAlias(path, binding)) {
+        return true;
+    }
+
+    const initializer = path.node.init;
+
+    return types.isIdentifier(path.node.id) &&
+        initializer !== null &&
+        initializer !== undefined &&
+        (isTranslationFunctionValue(path.scope, initializer) || isTranslationBindCall(path.scope, initializer));
+};
+
+const translationFunctionKind = (scope: Scope, name: string): TranslationCallKind | null => {
+    const direct = directTranslationFunctionKind(scope, name);
+
+    if (direct !== null) {
+        return direct;
+    }
+
+    return isTranslationAliasBinding(scope.getBinding(name)) ? "alias" : null;
+};
+
+const translationElementKind = (path: NodePath, name: string): TranslationCallKind | null => {
+    const imported = importedBinding(path.scope.getBinding(name));
+
+    if (imported?.source !== "@gtkx/i18n" || !TRANS_ELEMENTS.has(imported.imported)) {
+        return null;
+    }
+
+    return imported.local === imported.imported ? "canonical" : "alias";
+};
+
+const nodeStart = (path: NodePath): number => {
+    const start = path.node.start;
+
+    if (start === null || start === undefined) {
+        throw new Error("Translation extraction could not locate a source expression");
+    }
+
+    return start;
+};
+
+const registerSourceMask = (node: types.Node, references: TranslationReferences): void => {
+    const { start, end } = node;
+
+    if (start === null || start === undefined || end === null || end === undefined) {
+        throw new Error("Translation extraction could not locate a source expression");
+    }
+
+    references.masks.push({ start, end });
+};
+
+const sourceLocationKey = (line: number, column: number): string => `${String(line)}:${String(column)}`;
+
+const sourcePoint = (node: types.Node): SourcePoint | null => {
+    const location = node.loc?.start;
+
+    return location === undefined ? null : { column: location.column, line: location.line };
+};
+
+const registerSourceLocation = (node: types.Node, references: TranslationReferences): SourcePoint | null => {
+    const point = sourcePoint(node);
+
+    if (point !== null) {
+        references.locations.add(sourceLocationKey(point.line, point.column));
+    }
+
+    return point;
+};
+
+const babelStaticKey = (node: types.Node | null | undefined): string | null => {
+    if (node === null || node === undefined) {
+        return null;
+    }
+
+    if (types.isStringLiteral(node)) {
+        return node.value;
+    }
+
+    if (types.isTemplateLiteral(node) && node.expressions.length === 0) {
+        return node.quasis[0]?.value.cooked ?? null;
+    }
+
+    if (types.isParenthesizedExpression(node) ||
+        types.isTSAsExpression(node) ||
+        types.isTSSatisfiesExpression(node) ||
+        types.isTSTypeAssertion(node) ||
+        types.isTSNonNullExpression(node)) {
+        return babelStaticKey(node.expression);
+    }
+
+    return null;
+};
+
+const babelObjectExpression = (node: types.Node | null | undefined): types.ObjectExpression | null => {
+    if (node === null || node === undefined) {
+        return null;
+    }
+
+    if (types.isObjectExpression(node)) {
+        return node;
+    }
+
+    if (types.isParenthesizedExpression(node) ||
+        types.isTSAsExpression(node) ||
+        types.isTSSatisfiesExpression(node) ||
+        types.isTSTypeAssertion(node) ||
+        types.isTSNonNullExpression(node)) {
+        return babelObjectExpression(node.expression);
+    }
+
+    return null;
+};
+
+const babelNamedProperty = (
+    object: types.ObjectExpression | null,
+    name: string,
+): types.ObjectProperty | null => {
+    if (object === null) {
+        return null;
+    }
+
+    for (const property of object.properties) {
+        if (types.isObjectProperty(property) && babelPropertyName(property) === name) {
+            return property;
+        }
+    }
+
+    return null;
+};
+
+const babelStringProperty = (object: types.ObjectExpression | null, name: string): string | null => {
+    const property = babelNamedProperty(object, name);
+
+    if (property === null) {
+        return null;
+    }
+
+    const value = babelStaticKey(property.value);
+
+    if (value === null) {
+        throw new Error(`Translation ${name} values must be string literals`);
+    }
+
+    return value;
+};
+
+const callOptions = (call: types.CallExpression): types.ObjectExpression | null =>
+    babelObjectExpression(call.arguments[1]) ?? babelObjectExpression(call.arguments[2]);
+
+const hookKeyPrefix = (callee: NodePath<types.Identifier>): string => {
+    const binding = callee.scope.getBinding(callee.node.name);
+    const hook = binding === undefined ? null : translationHookBinding(binding);
+
+    return babelStringProperty(
+        hook === null ? null : babelObjectExpression(hook.call.arguments[1]),
+        "keyPrefix",
+    ) ?? "";
+};
+
+const prefixedTranslationKey = (prefix: string, key: string): string => {
+    if (prefix.length === 0) {
+        return key;
+    }
+
+    return prefix.endsWith(".") ? `${prefix}${key}` : `${prefix}.${key}`;
+};
+
+const extractedEntryKey = (call: types.CallExpression, keyPrefix: string): string | null => {
+    const key = babelStaticKey(call.arguments[0]);
+
+    if (key === null) {
+        return null;
+    }
+
+    const options = callOptions(call);
+    const callPrefix = babelStringProperty(options, "keyPrefix");
+
+    if (callPrefix === "" && keyPrefix.length > 0) {
+        throw new Error("An empty call keyPrefix cannot override a hook keyPrefix during extraction");
+    }
+
+    const selectedPrefix = callPrefix ?? keyPrefix;
+    const prefixed = prefixedTranslationKey(selectedPrefix, key);
+    const context = babelStringProperty(options, "context");
+
+    return context === null ? prefixed : `${prefixed}${CONTEXT_SEPARATOR}${context}`;
+};
+
+const registerEntryLocation = (
+    key: string | null,
+    point: SourcePoint | null,
+    references: TranslationReferences,
+): void => {
+    if (key === null || point === null) {
+        return;
+    }
+
+    const locations = references.entryLocations.get(key) ?? [];
+    locations.push(point);
+    references.entryLocations.set(key, locations);
+};
+
+const registerCallReference = (
+    callPath: NodePath<types.CallExpression>,
+    references: TranslationReferences,
+    keyPrefix: string,
+): void => {
+    references.calls.add(nodeStart(callPath));
+    const firstArgument = callPath.node.arguments[0];
+    const point = registerSourceLocation(firstArgument ?? callPath.node, references);
+    registerEntryLocation(extractedEntryKey(callPath.node, keyPrefix), point, references);
+};
+
+const parserPlugins = (lang: ReturnType<typeof sourceLanguage>): ("decorators" | "jsx" | "typescript")[] => [
+    "decorators",
+    ...(lang === "ts" || lang === "tsx" ? ["typescript" as const] : []),
+    ...(lang === "jsx" || lang === "tsx" ? ["jsx" as const] : []),
+];
+
+const registerIdentifierTranslationCall = (
+    callPath: NodePath<types.CallExpression>,
+    callee: NodePath,
+    references: TranslationReferences,
+): void => {
+    if (!callee.isIdentifier()) {
+        return;
+    }
+
+    const kind = translationFunctionKind(callee.scope, callee.node.name);
+
+    if (kind === "alias") {
+        throw new Error("Translation calls must use the imported name t");
+    }
+
+    if (kind === "canonical") {
+        registerCallReference(callPath, references, hookKeyPrefix(callee));
+    } else if (callee.node.name === "t") {
+        registerSourceMask(callee.node, references);
+    }
+};
+
+const registerTranslationCall = (
+    callPath: NodePath<types.CallExpression>,
+    references: TranslationReferences,
+): void => {
+    assertSupportedWrappedCallee(callPath);
+    const callee = callPath.get("callee");
+
+    if (callee.isIdentifier()) {
+        registerIdentifierTranslationCall(callPath, callee, references);
+
+        return;
+    }
+
+    if (callee.isMemberExpression() && isTranslationMember(callee.scope, callee.node)) {
+        throw new Error("Translation calls must use the named t export");
+    }
+};
+
+const unwrapTranslationCallee = (node: types.Node): types.Node => {
+    if (types.isParenthesizedExpression(node) ||
+        types.isTSAsExpression(node) ||
+        types.isTSSatisfiesExpression(node) ||
+        types.isTSTypeAssertion(node) ||
+        types.isTSNonNullExpression(node)) {
+        return unwrapTranslationCallee(node.expression);
+    }
+
+    return node;
+};
+
+const isTranslationCallee = (scope: Scope, node: types.Node): boolean => {
+    if (types.isIdentifier(node)) {
+        return translationFunctionKind(scope, node.name) !== null;
+    }
+
+    return (types.isMemberExpression(node) || types.isOptionalMemberExpression(node)) &&
+        isTranslationMember(scope, node);
+};
+
+const assertSupportedWrappedCallee = (callPath: NodePath<types.CallExpression>): void => {
+    const callee = callPath.node.callee;
+    const unwrapped = unwrapTranslationCallee(callee);
+
+    if (unwrapped !== callee && isTranslationCallee(callPath.scope, unwrapped)) {
+        throw new Error("Translation call expressions cannot wrap their callee");
+    }
+};
+
+const assertSupportedOptionalCall = (callPath: NodePath<types.OptionalCallExpression>): void => {
+    const callee = unwrapTranslationCallee(callPath.node.callee);
+
+    if (isTranslationCallee(callPath.scope, callee)) {
+        throw new Error("Translation calls cannot use optional chaining");
+    }
+};
+
+const assertUnsupportedTranslationTag = (tagPath: NodePath<types.TaggedTemplateExpression>): void => {
+    const tag = unwrapTranslationCallee(tagPath.node.tag);
+
+    if (isTranslationCallee(tagPath.scope, tag)) {
+        throw new Error("Translation calls cannot use tagged-template syntax");
+    }
+};
+
+const registerUnrecognizedElementMasks = (
+    elementPath: NodePath,
+    name: NodePath<types.JSXIdentifier>,
+    references: TranslationReferences,
+): void => {
+    registerSourceMask(name.node, references);
+    const parent = elementPath.parentPath.node;
+    const closingName = types.isJSXElement(parent) ? parent.closingElement?.name : null;
+
+    if (types.isJSXIdentifier(closingName)) {
+        registerSourceMask(closingName, references);
+    }
+};
+
+const registerTranslationElement = (elementPath: NodePath, references: TranslationReferences): void => {
+    const name = elementPath.get("name");
+
+    if (!name.isJSXIdentifier()) {
+        return;
+    }
+
+    const kind = translationElementKind(name, name.node.name);
+
+    if (kind === "alias") {
+        throw new Error("Translation components must use their imported names");
+    }
+
+    if (kind === "canonical") {
+        references.elements.add(nodeStart(elementPath));
+        registerSourceLocation(elementPath.node, references);
+    } else if (TRANS_ELEMENTS.has(name.node.name)) {
+        registerUnrecognizedElementMasks(elementPath, name, references);
+    }
+};
+
+const maskUnrecognizedTranslations = (source: string, references: TranslationReferences): string => {
+    let masked = source;
+    const masks = references.masks.toSorted((left, right) => right.start - left.start);
+
+    for (const { start, end } of masks) {
+        masked = `${masked.slice(0, start)}${"_".repeat(end - start)}${masked.slice(end)}`;
+    }
+
+    return masked;
+};
+
+const translationReferences = (
+    path: string,
+    source: string,
+    lang: ReturnType<typeof sourceLanguage>,
+): TranslationReferences => {
+    const parsed = parseBabelSync(source, {
+        ast: true,
+        babelrc: false,
+        configFile: false,
+        filename: path,
+        parserOpts: { createParenthesizedExpressions: true, plugins: parserPlugins(lang) },
+        sourceType: "module",
+    });
+
+    if (parsed === null) {
+        throw new Error(`Translation extraction could not parse ${path}`);
+    }
+
+    const references: TranslationReferences = {
+        calls: new Set(),
+        elements: new Set(),
+        entryLocations: new Map(),
+        locations: new Set(),
+        masks: [],
+    };
+
+    traverse(parsed, {
+        CallExpression(callPath) {
+            registerTranslationCall(callPath, references);
+        },
+        JSXOpeningElement(elementPath) {
+            registerTranslationElement(elementPath, references);
+        },
+        OptionalCallExpression(callPath) {
+            assertSupportedOptionalCall(callPath);
+        },
+        TaggedTemplateExpression(tagPath) {
+            assertUnsupportedTranslationTag(tagPath);
+        },
+    });
+
+    return references;
+};
+
+const assertSupportedTranslationCall = (node: ESTree.CallExpression, references: TranslationReferences): void => {
+    if (!references.calls.has(node.start)) {
+        return;
+    }
+
+    assertStaticTranslationKey(node.arguments[0]);
+    assertSupportedTranslationOptions(node.arguments[1], node.arguments[2]);
+};
+
+const assertSupportedTranslationOptions = (
+    second: ESTree.Node | null | undefined,
+    third: ESTree.Node | null | undefined,
+): void => {
+    if (third !== undefined && third !== null) {
+        assertStaticTranslationKey(second);
+        assertSupportedOptionObject(third);
+
+        return;
+    }
+
+    if (second === undefined || second === null || isStaticTranslationKey(second)) {
+        return;
+    }
+
+    assertSupportedOptionObject(second);
+};
+
+const isNamedJsxAttribute = (attribute: ESTree.JSXAttribute, name: string): boolean =>
+    attribute.name.type === "JSXIdentifier" && attribute.name.name === name;
+
+const assertSupportedTransKey = (attribute: ESTree.JSXAttribute): void => {
+    if (!isNamedJsxAttribute(attribute, "i18nKey")) {
+        return;
+    }
+
+    const key = attribute.value?.type === "JSXExpressionContainer"
+        ? attribute.value.expression
+        : attribute.value;
+    assertStaticTranslationKey(key);
+};
+
+const assertSupportedTransStringAttribute = (attribute: ESTree.JSXAttribute, name: string): void => {
+    if (!isNamedJsxAttribute(attribute, name)) {
+        return;
+    }
+
+    const value = attribute.value?.type === "JSXExpressionContainer"
+        ? attribute.value.expression
+        : attribute.value;
+    assertStaticTranslationKey(value);
+};
+
+const assertSupportedTransOptions = (attribute: ESTree.JSXAttribute): void => {
+    if (isNamedJsxAttribute(attribute, "tOptions") && attribute.value?.type === "JSXExpressionContainer") {
+        assertSupportedOptionObject(attribute.value.expression);
+    }
+};
+
+const assertSupportedTransAttribute = (attribute: ESTree.JSXAttributeItem): void => {
+    if (attribute.type === "JSXSpreadAttribute") {
+        throw new Error("Translation extraction requires explicit component properties");
+    }
+
+    assertSupportedTransKey(attribute);
+    assertSupportedTransStringAttribute(attribute, "context");
+    assertSupportedTransStringAttribute(attribute, "defaults");
+    assertSupportedTransOptions(attribute);
+};
+
+const assertSupportedTransElement = (node: ESTree.JSXOpeningElement, references: TranslationReferences): void => {
+    if (!references.elements.has(node.start)) {
+        return;
+    }
+
+    for (const attribute of node.attributes) {
+        assertSupportedTransAttribute(attribute);
+    }
+};
+
+const assertSupportedTranslationSyntax = (path: string, source: string): TranslationReferences => {
+    const lang = sourceLanguage(path);
+
+    if (lang === undefined) {
+        return { calls: new Set(), elements: new Set(), entryLocations: new Map(), locations: new Set(), masks: [] };
+    }
+
+    const parsed = parseSync(path, source, { lang });
+    const references = translationReferences(path, source, lang);
+
+    new Visitor({
+        CallExpression(node) {
+            assertSupportedTranslationCall(node, references);
+        },
+        JSXOpeningElement(node) {
+            assertSupportedTransElement(node, references);
+        },
+    }).visit(parsed.program);
+
+    return references;
+};
+
+const extractedLocationFile = (root: string, file: string): string =>
+    resolve(root, file);
+
+const isRecognizedLocation = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    location: SourceLocation,
+): boolean => {
+    if (location.line === undefined || location.column === undefined) {
+        return false;
+    }
+
+    const sourceReferences = references.get(extractedLocationFile(root, location.file));
+
+    return sourceReferences?.locations.has(sourceLocationKey(location.line, location.column)) === true;
+};
+
+const recognizedKeyLocations = (
+    references: Map<string, TranslationReferences>,
+    extractedKey: string,
+): ExtractedLocation[] => {
+    const locations: ExtractedLocation[] = [];
+
+    for (const [file, sourceReferences] of references) {
+        const points = sourceReferences.entryLocations.get(extractedKey) ?? [];
+
+        for (const point of points) {
+            locations.push({ file, column: point.column, line: point.line });
+        }
+    }
+
+    return locations;
+};
+
+const recognizedEntry = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    entry: ExtractedKey,
+): ExtractedKey | null => {
+    const extractedLocations = entry.locations ?? [];
+    const locations = extractedLocations.length === 0
+        ? recognizedKeyLocations(references, entry.key)
+        : extractedLocations.filter((location) => isRecognizedLocation(root, references, location));
+
+    return locations.length === 0 ? null : { ...entry, locations };
+};
+
+type NestedReferenceParts = { base: string; options: string };
+
+const quotedNestedReferenceParts = (content: string, quote: string): NestedReferenceParts | null => {
+    const end = content.indexOf(quote, 1);
+
+    return end === -1
+        ? null
+        : { base: content.slice(1, end), options: content.slice(end + 1) };
+};
+
+const nestedReferenceParts = (value: string): NestedReferenceParts | null => {
+    const content = value.trim();
+    const quote = content[0];
+
+    if (quote === "\"" || quote === "'") {
+        return quotedNestedReferenceParts(content, quote);
+    }
+
+    const separator = content.indexOf(",");
+    const base = (separator === -1 ? content : content.slice(0, separator)).trim();
+
+    return base.length === 0
+        ? null
+        : { base, options: separator === -1 ? "" : content.slice(separator + 1) };
+};
+
+const nestedReferenceContext = (options: string): string | null => {
+    const match = NESTED_CONTEXT.exec(options);
+    const context = match?.[1] ?? match?.[2] ?? null;
+
+    return context === null || context.length === 0 ? null : context;
+};
+
+const adjustedParenthesisDepth = (character: string | undefined, depth: number): number => {
+    if (character === "(") {
+        return depth + 1;
+    }
+
+    return character === ")" ? depth - 1 : depth;
+};
+
+const nestedReferenceEnd = (text: string, start: number): number => {
+    let depth = 0;
+    const tokens = text.slice(start).matchAll(NESTED_STRUCTURE_TOKEN);
+
+    for (const token of tokens) {
+        const character = token[0];
+
+        if (character === ")" && depth === 0) {
+            return start + token.index;
+        }
+
+        depth = adjustedParenthesisDepth(character, depth);
+    }
+
+    return -1;
+};
+
+const nestedReferenceContents = (text: string): string[] => {
+    const contents: string[] = [];
+    let offset = 0;
+
+    while (offset < text.length) {
+        const prefix = text.indexOf("$t(", offset);
+
+        if (prefix === -1) {
+            break;
+        }
+
+        const start = prefix + 3;
+        const end = nestedReferenceEnd(text, start);
+
+        if (end === -1) {
+            break;
+        }
+
+        contents.push(text.slice(start, end));
+        offset = end + 1;
+    }
+
+    return contents;
+};
+
+const nestedPluralKeys = (base: string, context: string | null): string[] => {
+    const pluralBase = context === null ? base : `${base}${CONTEXT_SEPARATOR}${context}`;
+
+    return [`${pluralBase}_one`, `${pluralBase}_other`];
+};
+
+const nestedReferenceKeys = (content: string): string[] => {
+    const parts = nestedReferenceParts(content);
+
+    if (parts === null) {
+        return [];
+    }
+
+    const context = nestedReferenceContext(parts.options);
+    const contextual = context === null
+        ? []
+        : [`${parts.base}_${context}`, `${parts.base}${CONTEXT_SEPARATOR}${context}`];
+
+    return NESTED_COUNT.test(parts.options)
+        ? [parts.base, ...contextual, ...nestedPluralKeys(parts.base, context)]
+        : [parts.base, ...contextual];
+};
+
+const nestedEntryKeys = (text: string): Set<string> => {
+    const keys: Set<string> = new Set();
+
+    for (const content of nestedReferenceContents(text)) {
+        for (const key of nestedReferenceKeys(content)) {
+            keys.add(key);
+        }
+    }
+
+    return keys;
+};
+
+const registerNestedKeyLocations = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    key: string,
+    locations: ExtractedLocation[],
+): void => {
+    for (const location of locations) {
+        if (location.line === undefined || location.column === undefined) {
+            continue;
+        }
+
+        const sourceReferences = references.get(resolve(root, location.file));
+
+        if (sourceReferences !== undefined) {
+            registerEntryLocation(key, { column: location.column, line: location.line }, sourceReferences);
+        }
+    }
+};
+
+const registerNestedTextLocations = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    text: string,
+    locations: ExtractedLocation[],
+): void => {
+    for (const key of nestedEntryKeys(text)) {
+        registerNestedKeyLocations(root, references, key, locations);
+    }
+};
+
+const registerNestedEntryLocations = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    entry: ExtractedKey,
+    locations: ExtractedLocation[],
+): void => {
+    registerNestedTextLocations(root, references, entry.key, locations);
+
+    if (typeof entry.defaultValue === "string") {
+        registerNestedTextLocations(root, references, entry.defaultValue, locations);
+    }
+};
+
+const didRegisterNestedLocationPass = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    entries: ExtractedKeysMap,
+    processed: Set<string>,
+): boolean => {
+    let didRegister = false;
+
+    for (const [mapKey, entry] of entries) {
+        if (processed.has(mapKey)) {
+            continue;
+        }
+
+        const recognized = recognizedEntry(root, references, entry);
+
+        if (recognized !== null) {
+            processed.add(mapKey);
+            registerNestedEntryLocations(root, references, entry, recognized.locations ?? []);
+            didRegister = true;
+        }
+    }
+
+    return didRegister;
+};
+
+const registerNestedLocations = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    entries: ExtractedKeysMap,
+): void => {
+    const processed: Set<string> = new Set();
+    let hasRegisteredLocations = true;
+
+    while (hasRegisteredLocations) {
+        hasRegisteredLocations = didRegisterNestedLocationPass(root, references, entries, processed);
+    }
+};
+
+const retainRecognizedEntries = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    entries: ExtractedKeysMap,
+): void => {
+    for (const [mapKey, entry] of entries) {
+        const recognized = recognizedEntry(root, references, entry);
+
+        if (recognized === null) {
+            entries.delete(mapKey);
+        } else {
+            entries.set(mapKey, recognized);
+        }
+    }
+};
+
+const fileSourcePointKey = (file: string, line: number, column: number): string =>
+    `${file}\0${sourceLocationKey(line, column)}`;
+
+const registerExtractedSourcePoint = (
+    root: string,
+    points: Set<string>,
+    location: ExtractedLocation,
+): void => {
+    if (location.line !== undefined && location.column !== undefined) {
+        points.add(fileSourcePointKey(resolve(root, location.file), location.line, location.column));
+    }
+};
+
+const extractedSourcePoints = (root: string, entries: ExtractedKeysMap): Set<string> => {
+    const points: Set<string> = new Set();
+
+    for (const entry of entries.values()) {
+        const locations = entry.locations ?? [];
+
+        for (const location of locations) {
+            registerExtractedSourcePoint(root, points, location);
+        }
+    }
+
+    return points;
+};
+
+const hasMissingSourcePoint = (
+    file: string,
+    references: TranslationReferences,
+    extracted: Set<string>,
+): boolean =>
+    references.locations.values().some((location) => !extracted.has(`${file}\0${location}`));
+
+const assertAllReferencesExtracted = (
+    root: string,
+    references: Map<string, TranslationReferences>,
+    entries: ExtractedKeysMap,
+): void => {
+    const extracted = extractedSourcePoints(root, entries);
+
+    for (const [file, sourceReferences] of references) {
+        if (hasMissingSourcePoint(file, sourceReferences, extracted)) {
+            throw new Error("A translation expression could not be extracted safely");
+        }
+    }
+};
+
 const findSourceMessages = async (root: string, sourceFiles: string[]): Promise<SourceMessage[]> => {
     if (sourceFiles.length === 0) {
         clearI18nResources(root);
@@ -301,12 +1504,29 @@ const findSourceMessages = async (root: string, sourceFiles: string[]): Promise<
         return [];
     }
 
+    const sources = new Map(sourceFiles.map((file) => [file, readFileSync(file, "utf8")]));
+    const references: Map<string, TranslationReferences> = new Map();
+
+    for (const [file, source] of sources) {
+        references.set(file, assertSupportedTranslationSyntax(file, source));
+    }
+
     let extracted: ExtractedKeysMap | undefined;
     const { logger, reports } = quietLogger();
 
     const capture: Plugin = {
         name: "gtkx-gettext",
+        onLoad(code, path) {
+            const sourceReferences = references.get(resolve(root, path));
+
+            return sourceReferences === undefined
+                ? code
+                : maskUnrecognizedTranslations(code, sourceReferences);
+        },
         onEnd(keys) {
+            registerNestedLocations(root, references, keys);
+            retainRecognizedEntries(root, references, keys);
+            assertAllReferencesExtracted(root, references, keys);
             extracted = keys;
         },
     };
@@ -322,8 +1542,6 @@ const findSourceMessages = async (root: string, sourceFiles: string[]): Promise<
         throw new Error(reports.join("\n") || "i18next extraction failed");
     }
 
-    const sources = new Map(sourceFiles.map((file) => [file, readFileSync(file, "utf8")]));
-
     return sourceMessages(extracted.values().toArray())
         .map((message) => inferLocations(message, sources))
         .toSorted(compareMessages);