gt 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # gtx-cli
 
+## 2.10.0
+
+### Minor Changes
+
+- [#1104](https://github.com/generaltranslation/gt/pull/1104) [`51430bd`](https://github.com/generaltranslation/gt/commit/51430bd1d85a4937ff3b4dcd0090d79e3b4c1504) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Adding metadata support for keyed file types
+
+### Patch Changes
+
+- [#1101](https://github.com/generaltranslation/gt/pull/1101) [`437a389`](https://github.com/generaltranslation/gt/commit/437a3898f1daa0a40ac033c2cc1bb94b4a0fd86b) Thanks [@ErnestM1234](https://github.com/ErnestM1234)! - fix: remove tw content json from init
+
+- [#1103](https://github.com/generaltranslation/gt/pull/1103) [`7164ceb`](https://github.com/generaltranslation/gt/commit/7164ceb9785863cdf4dc659fe5bd0f87511a5bed) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Extract code metadata
+
 ## 2.9.0
 
 ### Minor Changes

package/dist/cli/base.js

@@ -399,10 +399,7 @@ See https://generaltranslation.com/en/docs/next/guides/local-tx`);
                     { value: 'ts', label: FILE_EXT_TO_EXT_LABEL.ts },
                     { value: 'js', label: FILE_EXT_TO_EXT_LABEL.js },
                     { value: 'yaml', label: FILE_EXT_TO_EXT_LABEL.yaml },
-                    {
-                        value: 'twilioContentJson',
-                        label: FILE_EXT_TO_EXT_LABEL.twilioContentJson,
-                    },
+                    // TWILIO_CONTENT_JSON not supported in CLI init as its too niche
                 ],
                 required: !isUsingGT,
             });

package/dist/extraction/postProcess.js

@@ -47,6 +47,20 @@ export function dedupeUpdates(updates) {
         if (existingPaths.length) {
             existing.metadata.filePaths = existingPaths;
         }
+        // Merge sourceCode entries
+        const newSourceCode = update.metadata.sourceCode;
+        if (newSourceCode && typeof newSourceCode === 'object') {
+            if (!existing.metadata.sourceCode) {
+                existing.metadata.sourceCode = {};
+            }
+            const existingSourceCode = existing.metadata.sourceCode;
+            for (const [file, entries] of Object.entries(newSourceCode)) {
+                if (!existingSourceCode[file]) {
+                    existingSourceCode[file] = [];
+                }
+                existingSourceCode[file].push(...entries);
+            }
+        }
     }
     const mergedUpdates = [...mergedByHash.values(), ...noHashUpdates];
     updates.splice(0, updates.length, ...mergedUpdates);

package/dist/formats/files/aggregateFiles.js

@@ -4,10 +4,26 @@ import { getRelative, readFile } from '../../fs/findFilepath.js';
 import { SUPPORTED_FILE_EXTENSIONS } from './supportedFiles.js';
 import { parseJson } from '../json/parseJson.js';
 import parseYaml from '../yaml/parseYaml.js';
+import { validateYamlSchema } from '../yaml/utils.js';
+import { flattenJson } from '../json/flattenJson.js';
 import YAML from 'yaml';
 import { determineLibrary } from '../../fs/determineFramework/index.js';
 import { hashStringSync } from '../../utils/hash.js';
 import { preprocessContent } from './preprocessContent.js';
+import { parseKeyedMetadata, } from '../parseKeyedMetadata.js';
+/**
+ * Checks if a file path is a metadata companion file (e.g. foo.metadata.json)
+ * AND its corresponding source file (e.g. foo.json) exists in the file list.
+ * If both conditions are true, the metadata file should be skipped as a translation source.
+ */
+function isCompanionMetadataFile(filePath, allFilePaths) {
+    const metadataPattern = /\.metadata\.(json|yaml|yml)$/;
+    if (!metadataPattern.test(filePath))
+        return false;
+    // Derive the source file path: foo.metadata.json -> foo.json
+    const sourceFilePath = filePath.replace(/\.metadata\.(json|yaml|yml)$/, '.$1');
+    return allFilePaths.includes(sourceFilePath);
+}
 export const SUPPORTED_DATA_FORMATS = ['JSX', 'ICU', 'I18NEXT'];
 export async function aggregateFiles(settings) {
     // Aggregate all files to translate
@@ -39,6 +55,7 @@ export async function aggregateFiles(settings) {
             dataFormat = 'STRING';
         }
         const jsonFiles = filePaths.json
+            .filter((filePath) => !isCompanionMetadataFile(filePath, filePaths.json))
             .map((filePath) => {
             const content = readFile(filePath);
             const relativePath = getRelative(filePath);
@@ -54,6 +71,34 @@ export async function aggregateFiles(settings) {
                 }
             }
             const parsedJson = parseJson(content, filePath, settings.options || {}, settings.defaultLocale);
+            // Detect companion metadata file
+            let keyedMetadata;
+            let parsedContent;
+            try {
+                parsedContent = JSON.parse(content);
+            }
+            catch {
+                // Content not parsable — skip metadata detection
+            }
+            if (parsedContent) {
+                const rawMetadata = parseKeyedMetadata(filePath, parsedContent);
+                if (rawMetadata) {
+                    // Run metadata through the same include/composite schema as the source
+                    // so key paths align at translation time
+                    const transformed = parseJson(JSON.stringify(rawMetadata), filePath, settings.options || {}, settings.defaultLocale, false);
+                    const transformedMetadata = JSON.parse(transformed);
+                    // Filter metadata to only keep keys that exist in the transformed source
+                    // This prevents misaligned entries from wide JSONPath patterns
+                    const sourceKeys = new Set(Object.keys(JSON.parse(parsedJson)));
+                    const filtered = Object.fromEntries(Object.entries(transformedMetadata).filter(([k]) => sourceKeys.has(k)));
+                    if (Object.keys(filtered).length > 0) {
+                        keyedMetadata = filtered;
+                    }
+                    else {
+                        logger.warn(`Companion metadata found for ${relativePath} but no keys aligned with the JSON schema — metadata was not attached`);
+                    }
+                }
+            }
             return {
                 fileId: hashStringSync(relativePath),
                 versionId: hashStringSync(parsedJson),
@@ -62,6 +107,9 @@ export async function aggregateFiles(settings) {
                 fileFormat: 'JSON',
                 dataFormat,
                 locale: settings.defaultLocale,
+                ...(keyedMetadata && {
+                    formatMetadata: { keyedMetadata },
+                }),
             };
         })
             .filter((file) => {
@@ -79,6 +127,7 @@ export async function aggregateFiles(settings) {
     // Process YAML files
     if (filePaths.yaml) {
         const yamlFiles = filePaths.yaml
+            .filter((filePath) => !isCompanionMetadataFile(filePath, filePaths.yaml))
             .map((filePath) => {
             const content = readFile(filePath);
             const relativePath = getRelative(filePath);
@@ -94,6 +143,34 @@ export async function aggregateFiles(settings) {
                 }
             }
             const { content: parsedYaml, fileFormat } = parseYaml(content, filePath, settings.options || {});
+            // Detect companion metadata file
+            let keyedMetadata;
+            try {
+                const parsedYamlContent = YAML.parse(content);
+                const rawMetadata = parseKeyedMetadata(filePath, parsedYamlContent);
+                if (rawMetadata) {
+                    const yamlSchema = validateYamlSchema(settings.options || {}, filePath);
+                    if (yamlSchema?.include) {
+                        // Flatten metadata through the same include schema as the source
+                        const flattened = flattenJson(rawMetadata, yamlSchema.include);
+                        // Filter to only keep keys that exist in the transformed source
+                        const sourceKeys = new Set(Object.keys(JSON.parse(parsedYaml)));
+                        const filtered = Object.fromEntries(Object.entries(flattened).filter(([k]) => sourceKeys.has(k)));
+                        if (Object.keys(filtered).length > 0) {
+                            keyedMetadata = filtered;
+                        }
+                        else {
+                            logger.warn(`Companion metadata found for ${relativePath} but no keys aligned with the YAML schema — metadata was not attached`);
+                        }
+                    }
+                    else {
+                        keyedMetadata = rawMetadata;
+                    }
+                }
+            }
+            catch {
+                // Content not parsable as YAML — skip metadata detection
+            }
             return {
                 content: parsedYaml,
                 fileName: relativePath,
@@ -101,6 +178,9 @@ export async function aggregateFiles(settings) {
                 fileId: hashStringSync(relativePath),
                 versionId: hashStringSync(parsedYaml),
                 locale: settings.defaultLocale,
+                ...(keyedMetadata && {
+                    formatMetadata: { keyedMetadata },
+                }),
             };
         })
             .filter((file) => {

package/dist/formats/json/parseJson.d.ts

@@ -1,2 +1,2 @@
 import { AdditionalOptions } from '../../types/index.js';
-export declare function parseJson(content: string, filePath: string, options: AdditionalOptions, defaultLocale: string): string;
+export declare function parseJson(content: string, filePath: string, options: AdditionalOptions, defaultLocale: string, filterStrings?: boolean): string;

package/dist/formats/json/parseJson.js

@@ -1,11 +1,11 @@
-import { flattenJsonWithStringFilter } from './flattenJson.js';
+import { flattenJson, flattenJsonWithStringFilter } from './flattenJson.js';
 import { JSONPath } from 'jsonpath-plus';
 import { exitSync } from '../../console/logging.js';
 import { logger } from '../../console/logger.js';
 import { findMatchingItemArray, findMatchingItemObject, generateSourceObjectPointers, validateJsonSchema, } from './utils.js';
 import { applyStructuralTransforms } from './transformJson.js';
 // Parse a JSON file according to a JSON schema
-export function parseJson(content, filePath, options, defaultLocale) {
+export function parseJson(content, filePath, options, defaultLocale, filterStrings = true) {
     const jsonSchema = validateJsonSchema(options, filePath);
     if (!jsonSchema) {
         return content;
@@ -23,7 +23,8 @@ export function parseJson(content, filePath, options, defaultLocale) {
     }
     // Handle include
     if (jsonSchema.include) {
-        const flattenedJson = flattenJsonWithStringFilter(json, jsonSchema.include);
+        const flatten = filterStrings ? flattenJsonWithStringFilter : flattenJson;
+        const flattenedJson = flatten(json, jsonSchema.include);
         return JSON.stringify(flattenedJson);
     }
     if (!jsonSchema.composite) {
@@ -104,7 +105,8 @@ export function parseJson(content, filePath, options, defaultLocale) {
             }
             const { sourceItem } = matchingItem;
             // Get the fields to translate from the includes
-            const itemsToTranslate = flattenJsonWithStringFilter(sourceItem, sourceObjectOptions.include);
+            const flatten = filterStrings ? flattenJsonWithStringFilter : flattenJson;
+            const itemsToTranslate = flatten(sourceItem, sourceObjectOptions.include);
             // Add the items to translate to the result
             sourceObjectsToTranslate[sourceObjectPointer] = itemsToTranslate;
         }

package/dist/formats/parseKeyedMetadata.d.ts

@@ -0,0 +1,23 @@
+import type { SourceCode } from '../react/jsx/utils/extractSourceCode.js';
+import type { JSONObject } from '../types/data/json.js';
+export type MetadataLeaf = {
+    context?: string;
+    maxChars?: number;
+    sourceCode?: Record<string, SourceCode[]>;
+};
+export type MetadataObject = {
+    [key: string]: MetadataLeaf | MetadataObject;
+};
+export type MetadataArray = (MetadataLeaf | MetadataObject)[];
+export type KeyedMetadata = MetadataObject | MetadataArray;
+/**
+ * Detects and parses a companion metadata file for a given source file.
+ *
+ * For `translations.json`, looks for `translations.metadata.json`.
+ * For `translations.yaml` or `translations.yml`, looks for `translations.metadata.yaml` or `.yml`.
+ *
+ * @param sourceFilePath - Absolute path to the source file
+ * @param sourceContent - Parsed source content (object) for structure validation
+ * @returns Parsed metadata object, or undefined if no companion file exists
+ */
+export declare function parseKeyedMetadata(sourceFilePath: string, sourceContent: JSONObject | JSONObject[]): KeyedMetadata | undefined;

package/dist/formats/parseKeyedMetadata.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { logger } from '../console/logger.js';
+import { exitSync } from '../console/logging.js';
+/**
+ * Validates that the metadata key structure is a subset of the source key structure.
+ * Uses the source to determine whether a metadata value is a leaf (source value is a string)
+ * or a nested object (source value is an object).
+ */
+function validateMetadataStructure(source, metadata, currentPath = []) {
+    const errors = [];
+    for (const key of Object.keys(metadata)) {
+        const sourceValue = source[key];
+        const keyPath = [...currentPath, key];
+        if (sourceValue === undefined) {
+            errors.push(`Key "${keyPath.join('.')}" does not exist in source`);
+            continue;
+        }
+        // If the source value is a string, this is a translatable leaf — metadata should be a MetadataLeaf
+        // If the source value is a nested object, recurse
+        if (typeof sourceValue === 'object' &&
+            sourceValue !== null &&
+            !Array.isArray(sourceValue)) {
+            const metaValue = metadata[key];
+            if (Array.isArray(metaValue)) {
+                errors.push(`Key "${keyPath.join('.')}" is an array but source is an object`);
+            }
+            else if (typeof metaValue === 'object' && metaValue !== null) {
+                errors.push(...validateMetadataStructure(sourceValue, metaValue, keyPath));
+            }
+            else {
+                errors.push(`Key "${keyPath.join('.')}" is a primitive but source is an object`);
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Detects and parses a companion metadata file for a given source file.
+ *
+ * For `translations.json`, looks for `translations.metadata.json`.
+ * For `translations.yaml` or `translations.yml`, looks for `translations.metadata.yaml` or `.yml`.
+ *
+ * @param sourceFilePath - Absolute path to the source file
+ * @param sourceContent - Parsed source content (object) for structure validation
+ * @returns Parsed metadata object, or undefined if no companion file exists
+ */
+export function parseKeyedMetadata(sourceFilePath, sourceContent) {
+    const ext = path.extname(sourceFilePath);
+    const baseName = sourceFilePath.slice(0, -ext.length);
+    // Determine companion file path and parser
+    let metadataFilePath;
+    let parse;
+    if (ext === '.json') {
+        metadataFilePath = `${baseName}.metadata.json`;
+        parse = JSON.parse;
+    }
+    else if (ext === '.yaml' || ext === '.yml') {
+        const yamlPath = `${baseName}.metadata.yaml`;
+        const ymlPath = `${baseName}.metadata.yml`;
+        if (fs.existsSync(yamlPath)) {
+            metadataFilePath = yamlPath;
+        }
+        else if (fs.existsSync(ymlPath)) {
+            metadataFilePath = ymlPath;
+        }
+        parse = YAML.parse;
+    }
+    if (!metadataFilePath || !parse) {
+        return undefined;
+    }
+    if (!fs.existsSync(metadataFilePath)) {
+        return undefined;
+    }
+    // Read and parse
+    let metadataContent;
+    try {
+        const raw = fs.readFileSync(metadataFilePath, 'utf8');
+        const parsed = parse(raw);
+        if (typeof parsed !== 'object' || parsed === null) {
+            const relativePath = path.relative(process.cwd(), metadataFilePath);
+            logger.error(`Metadata file ${relativePath}: Expected an object or array`);
+            return exitSync(1);
+        }
+        metadataContent = parsed;
+    }
+    catch {
+        const relativePath = path.relative(process.cwd(), metadataFilePath);
+        logger.error(`Metadata file ${relativePath}: File is not parsable`);
+        return exitSync(1);
+    }
+    // Reject if root types don't match (array vs object)
+    if (Array.isArray(metadataContent) !== Array.isArray(sourceContent)) {
+        const relativePath = path.relative(process.cwd(), metadataFilePath);
+        logger.error(`Metadata file ${relativePath}: Root type (array vs object) does not match source`);
+        return exitSync(1);
+    }
+    // Validate structure against source (only for object-rooted files)
+    if (!Array.isArray(metadataContent) && !Array.isArray(sourceContent)) {
+        const errors = validateMetadataStructure(sourceContent, metadataContent);
+        if (errors.length > 0) {
+            const relativePath = path.relative(process.cwd(), metadataFilePath);
+            for (const error of errors) {
+                logger.error(`Metadata file ${relativePath}: ${error}`);
+            }
+            return exitSync(1);
+        }
+    }
+    return metadataContent;
+}

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const PACKAGE_VERSION = "2.9.0";
+export declare const PACKAGE_VERSION = "2.10.0";

package/dist/generated/version.js

@@ -1,2 +1,2 @@
 // This file is auto-generated. Do not edit manually.
-export const PACKAGE_VERSION = '2.9.0';
+export const PACKAGE_VERSION = '2.10.0';

package/dist/react/jsx/utils/extractSourceCode.d.ts

@@ -0,0 +1,15 @@
+export type SourceCode = {
+    before: string;
+    target: string;
+    after: string;
+};
+/**
+ * Extracts the surrounding lines of source code around a target node.
+ *
+ * @param filePath - Absolute path to the source file
+ * @param startLine - 1-based start line of the target node
+ * @param endLine - 1-based end line of the target node
+ * @param n - Number of surrounding lines before and after to capture
+ * @returns The surrounding lines, or undefined if the file can't be read
+ */
+export declare function extractSourceCode(filePath: string, startLine: number, endLine: number, n: number): SourceCode | undefined;

package/dist/react/jsx/utils/extractSourceCode.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+// Cache file contents to avoid re-reading the same file for multiple translation sites
+const fileContentCache = new Map();
+/**
+ * Extracts the surrounding lines of source code around a target node.
+ *
+ * @param filePath - Absolute path to the source file
+ * @param startLine - 1-based start line of the target node
+ * @param endLine - 1-based end line of the target node
+ * @param n - Number of surrounding lines before and after to capture
+ * @returns The surrounding lines, or undefined if the file can't be read
+ */
+export function extractSourceCode(filePath, startLine, endLine, n) {
+    let fileContent = fileContentCache.get(filePath);
+    if (fileContent === undefined) {
+        try {
+            const result = fs.readFileSync(filePath, 'utf8');
+            if (typeof result !== 'string') {
+                return undefined;
+            }
+            fileContent = result;
+            fileContentCache.set(filePath, fileContent);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const lines = fileContent.split('\n');
+    const totalLines = lines.length;
+    // Clamp to valid line ranges (convert to 0-based)
+    const targetStart = Math.max(0, startLine - 1);
+    const targetEnd = Math.min(totalLines - 1, endLine - 1);
+    const beforeStart = Math.max(0, targetStart - n);
+    const afterEnd = Math.min(totalLines - 1, targetEnd + n);
+    const before = lines.slice(beforeStart, targetStart).join('\n');
+    const target = lines.slice(targetStart, targetEnd + 1).join('\n');
+    const after = lines.slice(targetEnd + 1, afterEnd + 1).join('\n');
+    return { before, target, after };
+}

package/dist/react/jsx/utils/jsxParsing/parseJsx.d.ts

@@ -10,6 +10,7 @@ type ConfigOptions = {
     importAliases: Record<string, string>;
     pkgs: GTLibrary[];
     file: string;
+    includeSourceCodeContext?: boolean;
 };
 /**
  * Collectors for errors, warnings, and unwrapped expressions.

package/dist/react/jsx/utils/jsxParsing/parseJsx.js

@@ -21,6 +21,8 @@ import { isElementNode } from './types.js';
 import { multiplyJsxTree } from './multiplication/multiplyJsxTree.js';
 import { removeNullChildrenFields } from './removeNullChildrenFields.js';
 import path from 'node:path';
+import { extractSourceCode } from '../extractSourceCode.js';
+import { SURROUNDING_LINE_COUNT } from '../../../../utils/constants.js';
 // Handle CommonJS/ESM interop
 const traverse = traverseModule.default || traverseModule;
 // TODO: currently we cover VariableDeclaration and FunctionDeclaration nodes, but are there others we should cover as well?
@@ -410,6 +412,15 @@ function parseJSXElement({ node, originalName, scopeNode, updates, config, state
     const metadata = {};
     const relativeFilepath = path.relative(process.cwd(), config.file);
     metadata.filePaths = [relativeFilepath];
+    // Extract surrounding lines from source file
+    const startLine = node.loc?.start?.line;
+    const endLine = node.loc?.end?.line;
+    if (config.includeSourceCodeContext && startLine && endLine) {
+        const entry = extractSourceCode(config.file, startLine, endLine, SURROUNDING_LINE_COUNT);
+        if (entry && relativeFilepath) {
+            metadata.sourceCode = { [relativeFilepath]: [entry] };
+        }
+    }
     // We'll track this flag to know if any unwrapped {variable} is found in children
     const unwrappedExpressions = [];
     // Gather <T>'s props

package/dist/react/jsx/utils/parseStringFunction.js

@@ -283,6 +283,7 @@ export function parseStrings(importName, originalName, path, config, output) {
                 ignoreDynamicContent: false,
                 ignoreInvalidIcu: false,
                 ignoreInlineListContent: false,
+                includeSourceCodeContext: config.includeSourceCodeContext,
             };
             // Check if this is a direct call to msg('string')
             if (refPath.parent.type === 'CallExpression' &&
@@ -322,6 +323,7 @@ export function parseStrings(importName, originalName, path, config, output) {
                 ignoreInvalidIcu: isMessageHook,
                 // TODO: when we add support for array content in gt function, this should just always be false
                 ignoreInlineListContent: isInlineGT,
+                includeSourceCodeContext: config.includeSourceCodeContext,
             };
             const effectiveParent = parentPath?.node.type === 'AwaitExpression'
                 ? parentPath.parentPath

package/dist/react/jsx/utils/stringParsing/processTranslationCall/extractStringEntryMetadata.d.ts

@@ -1,6 +1,7 @@
 import * as t from '@babel/types';
 import { ParsingConfig } from '../types.js';
 import { ParsingOutput } from '../types.js';
+import type { SourceCode } from '../../extractSourceCode.js';
 /**
  * Metadata record type
  */
@@ -10,6 +11,7 @@ export type InlineMetadata = {
     id?: string;
     hash?: string;
     filePaths?: string[];
+    sourceCode?: Record<string, SourceCode[]>;
 };
 /**
  * Extracts inline metadata from a string entry
@@ -22,8 +24,17 @@ export type InlineMetadata = {
  * @note - this function does not automatically append the index to the id, this must be done manually in the caller.
  *
  */
-export declare function extractStringEntryMetadata({ options, output, config, }: {
+export declare function extractStringEntryMetadata({ options, output, config, nodeLoc, surroundingLineCount, }: {
     options?: t.CallExpression['arguments'][number];
     output: ParsingOutput;
     config: ParsingConfig;
+    nodeLoc?: {
+        start?: {
+            line: number;
+        } | null;
+        end?: {
+            line: number;
+        } | null;
+    } | null;
+    surroundingLineCount?: number;
 }): InlineMetadata;

package/dist/react/jsx/utils/stringParsing/processTranslationCall/extractStringEntryMetadata.js

@@ -7,6 +7,8 @@ import generateModule from '@babel/generator';
 import { mapAttributeName } from '../../mapAttributeName.js';
 import pathModule from 'node:path';
 import { isNumberLiteral } from '../../isNumberLiteral.js';
+import { extractSourceCode } from '../../extractSourceCode.js';
+import { SURROUNDING_LINE_COUNT } from '../../../../../utils/constants.js';
 // Handle CommonJS/ESM interop
 const generate = generateModule.default || generateModule;
 /**
@@ -20,7 +22,7 @@ const generate = generateModule.default || generateModule;
  * @note - this function does not automatically append the index to the id, this must be done manually in the caller.
  *
  */
-export function extractStringEntryMetadata({ options, output, config, }) {
+export function extractStringEntryMetadata({ options, output, config, nodeLoc, surroundingLineCount = SURROUNDING_LINE_COUNT, }) {
     // extract filepath for entry
     const relativeFilepath = pathModule.relative(process.cwd(), config.file);
     // extract inline metadata
@@ -29,9 +31,20 @@ export function extractStringEntryMetadata({ options, output, config, }) {
         output,
         config,
     });
+    // extract surrounding lines from source file
+    let sourceCode;
+    if (config.includeSourceCodeContext &&
+        nodeLoc?.start?.line &&
+        nodeLoc?.end?.line) {
+        const entry = extractSourceCode(config.file, nodeLoc.start.line, nodeLoc.end.line, surroundingLineCount);
+        if (entry && relativeFilepath) {
+            sourceCode = { [relativeFilepath]: [entry] };
+        }
+    }
     return {
         ...inlineMetadata,
         filePaths: relativeFilepath ? [relativeFilepath] : undefined,
+        ...(sourceCode && { sourceCode }),
     };
 }
 // ----- Helper Functions ----- //

package/dist/react/jsx/utils/stringParsing/processTranslationCall/index.js

@@ -1,5 +1,6 @@
 import { routeTranslationCall } from './routeTranslationCall.js';
 import { extractStringEntryMetadata } from './extractStringEntryMetadata.js';
+import { SURROUNDING_LINE_COUNT } from '../../../../../utils/constants.js';
 /**
  * Processes a single translation function call (e.g., t('hello world', { id: 'greeting' })).
  * Extracts the translatable string content and metadata, then adds it to the updates array.
@@ -27,6 +28,8 @@ export function processTranslationCall(tPath, config, output) {
         options,
         output,
         config,
+        nodeLoc: tPath.parent.loc,
+        surroundingLineCount: SURROUNDING_LINE_COUNT,
     });
     // Route tx call to appropriate handler
     routeTranslationCall({

package/dist/react/jsx/utils/stringParsing/types.d.ts

@@ -23,6 +23,10 @@ export type ParsingConfig = {
      * eg msg(['hello', 'world', 'foo', 'bar']) will not be registered
      */
     ignoreInlineListContent: boolean;
+    /**
+     * If true, include surrounding source code lines as context for translations
+     */
+    includeSourceCodeContext?: boolean;
 };
 /**
  * Mutable state for tracking parsing progress.

package/dist/react/parse/createInlineUpdates.d.ts

@@ -2,7 +2,7 @@ import { Updates } from '../../types/index.js';
 import type { ParsingConfigOptions } from '../../types/parsing.js';
 import { GTLibrary } from '../../types/libraries.js';
 import { dedupeUpdates } from '../../extraction/postProcess.js';
-export declare function createInlineUpdates(pkg: GTLibrary, validate: boolean, filePatterns: string[] | undefined, parsingOptions: ParsingConfigOptions): Promise<{
+export declare function createInlineUpdates(pkg: GTLibrary, validate: boolean, filePatterns: string[] | undefined, parsingOptions: ParsingConfigOptions, includeSourceCodeContext?: boolean): Promise<{
     updates: Updates;
     errors: string[];
     warnings: string[];

package/dist/react/parse/createInlineUpdates.js

@@ -8,7 +8,7 @@ import { DEFAULT_SRC_PATTERNS } from '../../config/generateSettings.js';
 import { getPathsAndAliases } from '../jsx/utils/getPathsAndAliases.js';
 import { GT_LIBRARIES_UPSTREAM, REACT_LIBRARIES, } from '../../types/libraries.js';
 import { calculateHashes, dedupeUpdates, linkStaticUpdates, } from '../../extraction/postProcess.js';
-export async function createInlineUpdates(pkg, validate, filePatterns, parsingOptions) {
+export async function createInlineUpdates(pkg, validate, filePatterns, parsingOptions, includeSourceCodeContext = false) {
     const updates = [];
     const errors = [];
     const warnings = new Set();
@@ -39,6 +39,7 @@ export async function createInlineUpdates(pkg, validate, filePatterns, parsingOp
                 ignoreDynamicContent: false,
                 ignoreInvalidIcu: false,
                 ignoreInlineListContent: false,
+                includeSourceCodeContext,
             }, { updates, errors, warnings });
         }
         // Parse <T> components
@@ -54,6 +55,7 @@ export async function createInlineUpdates(pkg, validate, filePatterns, parsingOp
                         parsingOptions,
                         pkgs,
                         file,
+                        includeSourceCodeContext,
                     },
                     output: {
                         errors,

package/dist/translation/parse.d.ts

@@ -10,7 +10,7 @@ import { InlineLibrary } from '../types/libraries.js';
  * @param pkg - The package name
  * @returns An object containing the updates and errors
  */
-export declare function createUpdates(options: TranslateFlags, src: string[] | undefined, sourceDictionary: string | undefined, pkg: InlineLibrary, validate: boolean, parsingOptions: ParsingConfigOptions): Promise<{
+export declare function createUpdates(options: TranslateFlags, src: string[] | undefined, sourceDictionary: string | undefined, pkg: InlineLibrary, validate: boolean, parsingOptions: ParsingConfigOptions, includeSourceCodeContext?: boolean): Promise<{
     updates: Updates;
     errors: string[];
     warnings: string[];

package/dist/translation/parse.js

@@ -17,7 +17,7 @@ import { isPythonLibrary } from '../types/libraries.js';
  * @param pkg - The package name
  * @returns An object containing the updates and errors
  */
-export async function createUpdates(options, src, sourceDictionary, pkg, validate, parsingOptions) {
+export async function createUpdates(options, src, sourceDictionary, pkg, validate, parsingOptions, includeSourceCodeContext = false) {
     let updates = [];
     let errors = [];
     let warnings = [];
@@ -53,7 +53,7 @@ export async function createUpdates(options, src, sourceDictionary, pkg, validat
     // Scan through project for translatable content
     const { updates: newUpdates, errors: newErrors, warnings: newWarnings, } = isPythonLibrary(pkg)
         ? await createPythonInlineUpdates(src)
-        : await createInlineUpdates(pkg, validate, src, parsingOptions);
+        : await createInlineUpdates(pkg, validate, src, parsingOptions, includeSourceCodeContext);
     errors = [...errors, ...newErrors];
     warnings = [...warnings, ...newWarnings];
     updates = [...updates, ...newUpdates];

package/dist/translation/stage.js

@@ -15,7 +15,7 @@ export async function aggregateInlineTranslations(options, settings, library) {
         ]);
     }
     // ---- CREATING UPDATES ---- //
-    const { updates, errors, warnings } = await createUpdates(options, settings.src, options.dictionary, library, false, settings.parsingOptions);
+    const { updates, errors, warnings } = await createUpdates(options, settings.src, options.dictionary, library, false, settings.parsingOptions, settings.options?.includeSourceCodeContext ?? false);
     if (warnings.length > 0) {
         logger.warn(chalk.yellow(`CLI tool encountered ${warnings.length} warnings while scanning for translatable content.\n` +
             warnings

package/dist/translation/validate.js

@@ -10,7 +10,7 @@ import { Libraries } from '../types/libraries.js';
  */
 async function runValidation(settings, pkg, files) {
     if (files && files.length > 0) {
-        return createInlineUpdates(pkg, true, files, settings.parsingOptions);
+        return createInlineUpdates(pkg, true, files, settings.parsingOptions, settings.options?.includeSourceCodeContext ?? false);
     }
     // Full project validation
     // Use local variable to avoid mutating caller's settings object
@@ -23,7 +23,7 @@ async function runValidation(settings, pkg, files) {
             './dictionary.ts',
             './src/dictionary.ts',
         ]);
-    return createUpdates(settings, settings.src, dictionary, pkg, true, settings.parsingOptions);
+    return createUpdates(settings, settings.src, dictionary, pkg, true, settings.parsingOptions, settings.options?.includeSourceCodeContext ?? false);
 }
 /**
  * Parse file path from error/warning string in withLocation format: "filepath (line:col): message"

package/dist/types/index.d.ts

@@ -211,6 +211,7 @@ export type AdditionalOptions = {
         replace: string;
     }>;
     experimentalCanonicalLocaleKeys?: boolean;
+    includeSourceCodeContext?: boolean;
 };
 export type SharedStaticAssetsConfig = {
     include: string | string[];

package/dist/utils/constants.d.ts

@@ -4,3 +4,4 @@ export declare const TEMPLATE_FILE_NAME = "__INTERNAL_GT_TEMPLATE_NAME__";
 export declare const TEMPLATE_FILE_ID: string;
 export declare const DEFAULT_GIT_REMOTE_NAME = "origin";
 export declare const DEFAULT_TIMEOUT_SECONDS = 900;
+export declare const SURROUNDING_LINE_COUNT = 5;

package/dist/utils/constants.js

@@ -5,3 +5,5 @@ export const TEMPLATE_FILE_NAME = '__INTERNAL_GT_TEMPLATE_NAME__';
 export const TEMPLATE_FILE_ID = hashStringSync(TEMPLATE_FILE_NAME);
 export const DEFAULT_GIT_REMOTE_NAME = 'origin';
 export const DEFAULT_TIMEOUT_SECONDS = 900;
+// Number of source code lines to capture above and below a translation site
+export const SURROUNDING_LINE_COUNT = 5;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gt",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "main": "dist/index.js",
   "bin": "dist/main.js",
   "files": [