+
{{ 'test' | i18n
+ Incomplete template
+ `;
+
+ // Should not throw an error
+ const usages = parser.findI18nPipeUsage(template, "test.html");
+
+ // May or may not find usages depending on parser robustness
+ expect(Array.isArray(usages)).toBe(true);
+ });
+ });
+
+ describe("TemplateTransformer", () => {
+ let transformer: TemplateTransformer;
+
+ beforeEach(() => {
+ transformer = new TemplateTransformer();
+ });
+
+ it("should transform simple interpolation to i18n attribute", () => {
+ const template = `
{{ 'welcome' | i18n }} `;
+
+ const result = transformer.transformTemplate(template, "test.html");
+
+ expect(result.success).toBe(true);
+ expect(result.changes).toHaveLength(1);
+ expect(result.changes[0].replacement).toContain('i18n="@@welcome"');
+ expect(result.changes[0].replacement).toContain("
{
+ const template = `Click `;
+
+ const result = transformer.transformTemplate(template, "test.html");
+
+ expect(result.success).toBe(true);
+ expect(result.changes).toHaveLength(1);
+ expect(result.changes[0].replacement).toContain('i18n-title="@@click-me"');
+ });
+
+ it("should handle multiple i18n pipe usages", () => {
+ const template = `
+
+
{{ 'title' | i18n }}
+
{{ 'description' | i18n }}
+
{{ 'buttonText' | i18n }}
+
+
Static Title
+
{{ someVariable }}
+
{{ 'test' | i18n }} `;
+ const validTransformed = `test test
+
+
+ {{ 'welcomeMessage' | i18n }}
+
+ {{ 'submit' | i18n }}
+
+
+
+
Before: {{ 'message' | i18n }}
+
Static content
+
After: {{ 'anotherMessage' | i18n }}
+
");
+ expect(transformedContent).toContain("
");
+ expect(transformedContent).toContain("Static content");
+ expect(transformedContent).toContain("Before:");
+ expect(transformedContent).toContain("After:");
+ });
+ });
+
+ describe("Template Output Validation", () => {
+ let transformer: TemplateTransformer;
+
+ beforeEach(() => {
+ transformer = new TemplateTransformer();
+ });
+
+ // Helper function to apply transformations to template content
+ function applyTransformations(template: string, changes: any[]): string {
+ let transformedContent = template;
+ // Apply changes in reverse order to handle position shifts correctly
+ for (const change of changes.reverse()) {
+ if (change.original && change.replacement) {
+ transformedContent = transformedContent.replace(change.original, change.replacement);
+ }
+ }
+ return transformedContent;
+ }
+
+ it("should produce correct HTML output for simple interpolation", () => {
+ const template = `{{ 'welcome' | i18n }} `;
+ const result = transformer.transformTemplate(template, "test.html");
+
+ expect(result.success).toBe(true);
+ expect(result.changes).toHaveLength(1);
+
+ const transformedContent = applyTransformations(template, result.changes);
+ expect(transformedContent).toBe(`welcome Click `;
+ const result = transformer.transformTemplate(template, "test.html");
+
+ expect(result.success).toBe(true);
+ expect(result.changes).toHaveLength(1);
+
+ const transformedContent = applyTransformations(template, result.changes);
+ expect(transformedContent).toBe(
+ `Click `,
+ );
+ });
+
+ it("should produce correct HTML output for multiple transformations", () => {
+ const template = `
+
+
{{ 'title' | i18n }}
+
{{ 'description' | i18n }}
+
{{ 'buttonText' | i18n }}
+
+
title
+
description
+
buttonText
+
camelCaseKey `);
+ });
+
+ it("should produce correct HTML output for snake_case key conversion", () => {
+ const template = `{{ 'snake_case_key' | i18n }}`;
+ const result = transformer.transformTemplate(template, "test.html");
+
+ expect(result.success).toBe(true);
+ expect(result.changes).toHaveLength(1);
+
+ const transformedContent = applyTransformations(template, result.changes);
+ expect(transformedContent).toBe(`snake_case_key `);
+ });
+
+ it("should produce correct HTML output for dotted key conversion", () => {
+ const template = `{{ 'dotted.key.name' | i18n }}`;
+ const result = transformer.transformTemplate(template, "test.html");
+
+ expect(result.success).toBe(true);
+ expect(result.changes).toHaveLength(1);
+
+ const transformedContent = applyTransformations(template, result.changes);
+ expect(transformedContent).toBe(`dotted.key.name `);
+ });
+
+ it("should produce valid HTML that passes validation", () => {
+ const template = `
+
+ `;
+ const result = transformer.transformTemplate(template, "validation-test.html");
+
+ expect(result.success).toBe(true);
+ expect(result.changes.length).toBeGreaterThan(0);
+
+ const transformedContent = applyTransformations(template, result.changes);
+
+ // Verify the transformation is valid according to the transformer's own validation
+ expect(transformer.validateTransformation(template, transformedContent)).toBe(true);
+
+ // Verify specific output characteristics
+ expect(transformedContent).toContain('i18n="@@app-title"');
+ expect(transformedContent).toContain('i18n-title="@@home-link"');
+ expect(transformedContent).toContain('i18n="@@home"');
+ expect(transformedContent).not.toContain("| i18n");
+ });
+ });
+});
diff --git a/scripts/migration/i18n/templates/template-migrator.ts b/scripts/migration/i18n/templates/template-migrator.ts
new file mode 100644
index 00000000000..35a9a937886
--- /dev/null
+++ b/scripts/migration/i18n/templates/template-migrator.ts
@@ -0,0 +1,206 @@
+/* eslint-disable no-console */
+import { readFileSync, writeFileSync } from "fs";
+
+import { MigrationConfig, TransformationResult, I18nUsage } from "../shared/types";
+
+import { TemplateTransformer } from "./template-transformer";
+
+/**
+ * Main class for template migration from i18n pipes to i18n attributes
+ */
+export class TemplateMigrator {
+ private transformer: TemplateTransformer;
+
+ constructor(private config: MigrationConfig) {
+ this.transformer = new TemplateTransformer();
+ }
+
+ /**
+ * Analyze i18n pipe usage in a template file
+ */
+ analyzeTemplate(filePath: string): I18nUsage[] {
+ try {
+ const templateContent = readFileSync(filePath, "utf-8");
+ return this.transformer.findI18nPipeUsage(templateContent, filePath);
+ } catch (error) {
+ if (this.config.verbose) {
+ console.error(`Error reading template file ${filePath}:`, error);
+ }
+ return [];
+ }
+ }
+
+ /**
+ * Migrate a single template file
+ */
+ async migrateTemplate(filePath: string): Promise {
+ try {
+ const templateContent = readFileSync(filePath, "utf-8");
+ const result = this.transformer.transformTemplate(templateContent, filePath);
+
+ if (result.success && result.changes.length > 0) {
+ // Get the transformed content by applying all changes
+ const transformedContent = this.applyChangesToContent(templateContent, result.changes);
+
+ // Validate the transformation
+ if (this.transformer.validateTransformation(templateContent, transformedContent)) {
+ if (!this.config.dryRun) {
+ writeFileSync(filePath, transformedContent, "utf-8");
+ }
+ } else {
+ result.success = false;
+ result.errors.push("Transformation validation failed");
+ }
+ }
+
+ return result;
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ return {
+ success: false,
+ filePath,
+ changes: [],
+ errors: [`Error processing template file: ${errorMessage}`],
+ };
+ }
+ }
+
+ /**
+ * Migrate multiple template files
+ */
+ async migrateTemplates(filePaths: string[]): Promise {
+ const results: TransformationResult[] = [];
+
+ for (const filePath of filePaths) {
+ if (this.config.verbose) {
+ console.log(`Processing template: ${filePath}`);
+ }
+
+ const result = await this.migrateTemplate(filePath);
+ results.push(result);
+
+ if (!result.success) {
+ console.error(`Failed to process ${filePath}:`, result.errors);
+ }
+ }
+
+ return results;
+ }
+
+ /**
+ * Generate analysis report for template usage
+ */
+ generateTemplateAnalysisReport(filePaths: string[]): string {
+ const allUsages: I18nUsage[] = [];
+
+ for (const filePath of filePaths) {
+ const usages = this.analyzeTemplate(filePath);
+ allUsages.push(...usages);
+ }
+
+ const fileCount = new Set(allUsages.map((u) => u.filePath)).size;
+ const keyCount = new Set(allUsages.map((u) => u.key)).size;
+
+ let report = `# Template i18n Pipe Usage Analysis Report\n\n`;
+ report += `## Summary\n`;
+ report += `- Total pipe usage count: ${allUsages.length}\n`;
+ report += `- Template files affected: ${fileCount}\n`;
+ report += `- Unique translation keys: ${keyCount}\n\n`;
+
+ report += `## Usage by File\n`;
+ const usagesByFile = allUsages.reduce(
+ (acc, usage) => {
+ if (!acc[usage.filePath]) {
+ acc[usage.filePath] = [];
+ }
+ acc[usage.filePath].push(usage);
+ return acc;
+ },
+ {} as Record,
+ );
+
+ Object.entries(usagesByFile).forEach(([filePath, fileUsages]) => {
+ report += `\n### ${filePath}\n`;
+ fileUsages.forEach((usage) => {
+ report += `- Line ${usage.line}: \`${usage.key}\``;
+ if (usage.parameters) {
+ report += ` (with parameters: ${usage.parameters.join(", ")})`;
+ }
+ if (usage.context) {
+ report += ` - Context: \`${usage.context.trim()}\``;
+ }
+ report += `\n`;
+ });
+ });
+
+ report += `\n## Most Common Keys\n`;
+ const keyCounts = allUsages.reduce(
+ (acc, usage) => {
+ acc[usage.key] = (acc[usage.key] || 0) + 1;
+ return acc;
+ },
+ {} as Record,
+ );
+
+ Object.entries(keyCounts)
+ .sort(([, a], [, b]) => b - a)
+ .slice(0, 10)
+ .forEach(([key, count]) => {
+ report += `- \`${key}\`: ${count} usage(s)\n`;
+ });
+
+ return report;
+ }
+
+ /**
+ * Generate migration statistics
+ */
+ generateMigrationStats(results: TransformationResult[]): string {
+ const successful = results.filter((r) => r.success).length;
+ const failed = results.filter((r) => !r.success).length;
+ const totalChanges = results.reduce((sum, r) => sum + r.changes.length, 0);
+
+ let stats = `# Template Migration Statistics\n\n`;
+ stats += `- Templates processed: ${results.length}\n`;
+ stats += `- Successful: ${successful}\n`;
+ stats += `- Failed: ${failed}\n`;
+ stats += `- Total transformations: ${totalChanges}\n\n`;
+
+ if (failed > 0) {
+ stats += `## Failed Templates\n`;
+ results
+ .filter((r) => !r.success)
+ .forEach((result) => {
+ stats += `- ${result.filePath}\n`;
+ result.errors.forEach((error) => {
+ stats += ` - ${error}\n`;
+ });
+ });
+ }
+
+ return stats;
+ }
+
+ /**
+ * Apply transformation changes to content
+ */
+ private applyChangesToContent(content: string, changes: TransformationResult["changes"]): string {
+ let transformedContent = content;
+
+ // Sort changes by position (descending) to avoid position shifts
+ const sortedChanges = changes.sort((a, b) => {
+ if (a.location.line !== b.location.line) {
+ return b.location.line - a.location.line;
+ }
+ return b.location.column - a.location.column;
+ });
+
+ for (const change of sortedChanges) {
+ if (change.type === "replace" && change.original && change.replacement) {
+ transformedContent = transformedContent.replace(change.original, change.replacement);
+ }
+ }
+
+ return transformedContent;
+ }
+}
diff --git a/scripts/migration/i18n/templates/template-parser.ts b/scripts/migration/i18n/templates/template-parser.ts
new file mode 100644
index 00000000000..7ac56987158
--- /dev/null
+++ b/scripts/migration/i18n/templates/template-parser.ts
@@ -0,0 +1,201 @@
+import { parseTemplate, TmplAstNode, TmplAstElement, TmplAstBoundText } from "@angular/compiler";
+
+import { I18nUsage } from "../shared/types";
+
+/**
+ * Utility class for parsing Angular templates using Angular compiler
+ */
+export class TemplateParser {
+ /**
+ * Find all i18n pipe usage in a template
+ */
+ findI18nPipeUsage(templateContent: string, filePath: string): I18nUsage[] {
+ const usages: I18nUsage[] = [];
+
+ // Parse template using Angular compiler
+ const parseResult = parseTemplate(templateContent, filePath);
+
+ if (parseResult.nodes) {
+ this.traverseNodes(parseResult.nodes, usages, filePath);
+ }
+
+ return usages;
+ }
+
+ /**
+ * Recursively traverse template AST nodes to find i18n pipe usage
+ */
+ private traverseNodes(nodes: TmplAstNode[], usages: I18nUsage[], filePath: string): void {
+ for (const node of nodes) {
+ this.processNode(node, usages, filePath);
+
+ // Recursively process child nodes
+ if ("children" in node && Array.isArray(node.children)) {
+ this.traverseNodes(node.children, usages, filePath);
+ }
+ }
+ }
+
+ /**
+ * Process a single template AST node to find i18n pipe usage
+ */
+ private processNode(node: TmplAstNode, usages: I18nUsage[], filePath: string): void {
+ // Handle bound text nodes (interpolations)
+ if (this.isBoundText(node)) {
+ const expression = node.value;
+
+ if (expression && typeof expression == "object" && "source" in expression) {
+ const expressionText = (expression.source as string) || "";
+
+ if (this.containsI18nPipe(expressionText)) {
+ const pipeUsage = this.extractI18nPipeUsage(expressionText);
+ if (pipeUsage) {
+ // Get the actual text from the source span instead of reconstructing it
+ const actualContext = node.sourceSpan.start.file.content.substring(
+ node.sourceSpan.start.offset,
+ node.sourceSpan.end.offset,
+ );
+ usages.push({
+ filePath,
+ line: node.sourceSpan.start.line + 1,
+ column: node.sourceSpan.start.col,
+ method: "pipe",
+ key: pipeUsage.key,
+ parameters: pipeUsage.parameters,
+ context: actualContext,
+ });
+ }
+ }
+ }
+ }
+
+ // Handle element nodes with attributes
+ if (this.isElement(node)) {
+ // Check bound attributes (property bindings)
+ for (const input of node.inputs || []) {
+ if (input.value && "source" in input.value) {
+ const inputValue = (input.value.source as string) || "";
+ if (this.containsI18nPipe(inputValue)) {
+ const pipeUsage = this.extractI18nPipeUsage(inputValue);
+ if (pipeUsage) {
+ usages.push({
+ filePath,
+ line: input.sourceSpan.start.line + 1,
+ column: input.sourceSpan.start.col,
+ method: "pipe",
+ key: pipeUsage.key,
+ parameters: pipeUsage.parameters,
+ context: `[${input.name}]="${inputValue}"`,
+ });
+ }
+ }
+ }
+ }
+
+ // Check regular attributes
+ for (const attr of node.attributes || []) {
+ if (attr.value && this.containsI18nPipe(attr.value)) {
+ const pipeUsage = this.extractI18nPipeUsage(attr.value);
+ if (pipeUsage) {
+ usages.push({
+ filePath,
+ line: attr.sourceSpan.start.line + 1,
+ column: attr.sourceSpan.start.col,
+ method: "pipe",
+ key: pipeUsage.key,
+ parameters: pipeUsage.parameters,
+ context: `${attr.name}="${attr.value}"`,
+ });
+ }
+ }
+ }
+ }
+ }
+
+ /**
+ * Check if a node is a bound text node
+ */
+ private isBoundText(node: TmplAstNode): node is TmplAstBoundText {
+ return node.constructor.name === "BoundText" || "value" in node;
+ }
+
+ /**
+ * Check if a node is an element node
+ */
+ private isElement(node: TmplAstNode): node is TmplAstElement {
+ return node.constructor.name === "Element" || ("inputs" in node && "attributes" in node);
+ }
+
+ /**
+ * Check if an expression contains i18n pipe usage
+ */
+ private containsI18nPipe(expression: string): boolean {
+ return /\|\s*i18n\b/.test(expression);
+ }
+
+ /**
+ * Extract i18n pipe usage details from an expression
+ */
+ private extractI18nPipeUsage(expression: string): { key: string; parameters?: string[] } | null {
+ // Match patterns like: 'key' | i18n or 'key' | i18n:param1:param2
+ const pipeMatch = expression.match(/['"`]([^'"`]+)['"`]\s*\|\s*i18n(?::([^|}]+))?/);
+
+ if (pipeMatch) {
+ const key = pipeMatch[1];
+ const paramString = pipeMatch[2];
+ const parameters = paramString
+ ? paramString
+ .split(":")
+ .map((p) => p.trim())
+ .filter((p) => p)
+ : undefined;
+
+ return { key, parameters };
+ }
+
+ // Match more complex patterns with variables
+ const complexMatch = expression.match(/([^|]+)\s*\|\s*i18n(?::([^|}]+))?/);
+ if (complexMatch) {
+ const keyExpression = complexMatch[1].trim();
+ const paramString = complexMatch[2];
+ const parameters = paramString
+ ? paramString
+ .split(":")
+ .map((p) => p.trim())
+ .filter((p) => p)
+ : undefined;
+
+ // For complex expressions, use the full expression as the key
+ return { key: keyExpression, parameters };
+ }
+
+ return null;
+ }
+
+ /**
+ * Get line and column information for a position in the template
+ */
+ getPositionInfo(templateContent: string, position: number): { line: number; column: number } {
+ const lines = templateContent.substring(0, position).split("\n");
+ return {
+ line: lines.length,
+ column: lines[lines.length - 1].length + 1,
+ };
+ }
+
+ /**
+ * Check if a template contains any i18n pipe usage
+ */
+ hasI18nPipeUsage(templateContent: string): boolean {
+ return /\|\s*i18n\b/.test(templateContent);
+ }
+
+ /**
+ * Extract all unique translation keys from a template
+ */
+ extractTranslationKeys(templateContent: string): string[] {
+ const usages = this.findI18nPipeUsage(templateContent, "");
+ const keys = new Set(usages.map((usage) => usage.key));
+ return Array.from(keys);
+ }
+}
diff --git a/scripts/migration/i18n/templates/template-transformer.ts b/scripts/migration/i18n/templates/template-transformer.ts
new file mode 100644
index 00000000000..49096e91bb0
--- /dev/null
+++ b/scripts/migration/i18n/templates/template-transformer.ts
@@ -0,0 +1,171 @@
+import { TransformationResult, TransformationChange, I18nUsage } from "../shared/types";
+
+import { TemplateParser } from "./template-parser";
+
+/**
+ * Template transformation utilities for migrating i18n pipes to i18n attributes
+ */
+export class TemplateTransformer {
+ private parser: TemplateParser;
+
+ constructor() {
+ this.parser = new TemplateParser();
+ }
+
+ /**
+ * Find all i18n pipe usage in a template file
+ */
+ findI18nPipeUsage(templateContent: string, filePath: string): I18nUsage[] {
+ return this.parser.findI18nPipeUsage(templateContent, filePath);
+ }
+
+ /**
+ * Transform i18n pipes to i18n attributes in a template
+ */
+ transformTemplate(templateContent: string, filePath: string): TransformationResult {
+ const changes: TransformationChange[] = [];
+ const errors: string[] = [];
+
+ try {
+ // Use the parser to find all i18n pipe usages via AST
+ const usages = this.parser.findI18nPipeUsage(templateContent, filePath);
+
+ let transformedContent = templateContent;
+
+ // Process each usage found by the AST parser (reverse order to handle replacements from end to start)
+ for (const usage of usages.reverse()) {
+ if (!usage.context) {
+ continue; // Skip usages without context
+ }
+
+ const replacement = this.generateReplacement(usage);
+ transformedContent = this.replaceAtPosition(transformedContent, usage, replacement);
+
+ changes.push({
+ type: "replace",
+ location: { line: usage.line, column: usage.column },
+ original: usage.context,
+ replacement,
+ description: `Transformed ${usage.method} usage '${usage.key}' to i18n attribute`,
+ });
+ }
+
+ return {
+ success: true,
+ filePath,
+ changes,
+ errors,
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ errors.push(`Error transforming template: ${errorMessage}`);
+ return {
+ success: false,
+ filePath,
+ changes,
+ errors,
+ };
+ }
+ }
+
+ /**
+ * Generate replacement text for a given i18n usage
+ */
+ private generateReplacement(usage: I18nUsage): string {
+ const i18nId = this.generateI18nId(usage.key);
+ const context = usage.context || "";
+
+ if (context.startsWith("{{") && context.endsWith("}}")) {
+ // Interpolation: {{ 'key' | i18n }} -> key
+ return `${usage.key} `;
+ } else if (context.includes("[") && context.includes("]")) {
+ // Attribute binding: [title]="'key' | i18n" -> [title]="key" i18n-title="@@key"
+ const attrMatch = context.match(/\[([^\]]+)\]/);
+ if (attrMatch) {
+ const attrName = attrMatch[1];
+ return `[${attrName}]="${usage.key}" i18n-${attrName}="@@${i18nId}"`;
+ }
+ }
+
+ return context; // fallback
+ }
+
+ /**
+ * Replace usage at specific position in template content
+ */
+ private replaceAtPosition(content: string, usage: I18nUsage, replacement: string): string {
+ // Find the exact position of the usage.context in the content and replace it
+ const context = usage.context || "";
+ const contextIndex = content.indexOf(context);
+ if (contextIndex !== -1) {
+ return (
+ content.substring(0, contextIndex) +
+ replacement +
+ content.substring(contextIndex + context.length)
+ );
+ }
+ return content;
+ }
+
+ /**
+ * Generate i18n ID from a translation key
+ */
+ private generateI18nId(key: string): string {
+ // Convert camelCase or snake_case to kebab-case for i18n IDs
+ return key
+ .replace(/([a-z])([A-Z])/g, "$1-$2")
+ .replace(/_/g, "-")
+ .replace(/\./g, "-")
+ .toLowerCase();
+ }
+
+ /**
+ * Get line and column information for a position in the template
+ */
+ private getPositionInfo(
+ templateContent: string,
+ position: number,
+ ): { line: number; column: number } {
+ const lines = templateContent.substring(0, position).split("\n");
+ return {
+ line: lines.length,
+ column: lines[lines.length - 1].length + 1,
+ };
+ }
+
+ /**
+ * Validate that a transformation is correct
+ */
+ validateTransformation(original: string, transformed: string): boolean {
+ try {
+ // Basic validation - ensure the transformed template is still valid HTML-like
+ const hasMatchingBrackets = this.validateBrackets(transformed);
+ const hasValidI18nAttributes = this.validateI18nAttributes(transformed);
+ const hasNoRemainingPipes = !this.parser.hasI18nPipeUsage(transformed);
+
+ return hasMatchingBrackets && hasValidI18nAttributes && hasNoRemainingPipes;
+ } catch {
+ return false;
+ }
+ }
+
+ /**
+ * Validate that brackets are properly matched
+ */
+ private validateBrackets(content: string): boolean {
+ const openBrackets = (content.match(/\{/g) || []).length;
+ const closeBrackets = (content.match(/\}/g) || []).length;
+ return openBrackets === closeBrackets;
+ }
+
+ /**
+ * Validate that i18n attributes are properly formatted
+ */
+ private validateI18nAttributes(content: string): boolean {
+ const i18nAttrs = content.match(/i18n(-[\w-]+)?="[^"]*"/g) || [];
+ return i18nAttrs.every((attr) => {
+ const valueMatch = attr.match(/="([^"]*)"/);
+ return valueMatch && valueMatch[1].startsWith("@@");
+ });
+ }
+}
diff --git a/scripts/migration/i18n/templates/test-enhanced-sample-transformed.html b/scripts/migration/i18n/templates/test-enhanced-sample-transformed.html
new file mode 100644
index 00000000000..e4058abdf27
--- /dev/null
+++ b/scripts/migration/i18n/templates/test-enhanced-sample-transformed.html
@@ -0,0 +1,11 @@
+
diff --git a/scripts/migration/i18n/templates/test-enhanced-sample.html b/scripts/migration/i18n/templates/test-enhanced-sample.html
new file mode 100644
index 00000000000..ac29a6388c2
--- /dev/null
+++ b/scripts/migration/i18n/templates/test-enhanced-sample.html
@@ -0,0 +1,7 @@
+
diff --git a/scripts/migration/i18n/templates/test-enhanced-transformer.ts b/scripts/migration/i18n/templates/test-enhanced-transformer.ts
new file mode 100644
index 00000000000..e1e244f3585
--- /dev/null
+++ b/scripts/migration/i18n/templates/test-enhanced-transformer.ts
@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+import * as fs from "fs";
+
+import * as chalk from "chalk";
+
+import { EnhancedTemplateTransformer } from "./enhanced-template-transformer";
+
+async function testEnhancedTransformer() {
+ console.log(chalk.blue("🧪 Testing Enhanced Template Transformer\n"));
+
+ try {
+ // Initialize the enhanced transformer
+ const transformer = new EnhancedTemplateTransformer();
+ await transformer.initialize("./test-combined.json");
+
+ console.log(chalk.green("✅ Initialized with combined translations"));
+
+ // Read the test template
+ const templatePath = "./templates/test-enhanced-sample.html";
+ const templateContent = fs.readFileSync(templatePath, "utf-8");
+
+ console.log(chalk.blue("\n📄 Original Template:"));
+ console.log(templateContent);
+
+ // Transform the template
+ const result = transformer.transformTemplate(templateContent, templatePath);
+
+ if (result.success) {
+ console.log(
+ chalk.green(`\n✅ Transformation successful! ${result.changes.length} changes made`),
+ );
+
+ // Apply the transformations
+ let transformedContent = templateContent;
+ for (const change of result.changes.reverse()) {
+ if (change.original && change.replacement) {
+ transformedContent = transformedContent.replace(change.original, change.replacement);
+ }
+ }
+
+ console.log(chalk.blue("\n📄 Transformed Template:"));
+ console.log(transformedContent);
+
+ console.log(chalk.blue("\n📋 Changes Made:"));
+ result.changes.forEach((change, index) => {
+ console.log(`${index + 1}. ${change.description}`);
+ console.log(` Before: ${chalk.red(change.original)}`);
+ console.log(` After: ${chalk.green(change.replacement)}`);
+ console.log();
+ });
+
+ if (result.errors.length > 0) {
+ console.log(chalk.yellow("\n⚠️ Warnings:"));
+ result.errors.forEach((error) => {
+ console.log(` ${error}`);
+ });
+ }
+
+ // Save the transformed template
+ const outputPath = "./templates/test-enhanced-sample-transformed.html";
+ fs.writeFileSync(outputPath, transformedContent);
+ console.log(chalk.green(`💾 Transformed template saved to: ${outputPath}`));
+ } else {
+ console.log(chalk.red("\n❌ Transformation failed:"));
+ result.errors.forEach((error) => {
+ console.log(` ${error}`);
+ });
+ }
+ } catch (error) {
+ console.error(chalk.red("❌ Test failed:"), error);
+ process.exit(1);
+ }
+}
+
+void testEnhancedTransformer();
diff --git a/scripts/migration/i18n/templates/test-migration/no-i18n.html b/scripts/migration/i18n/templates/test-migration/no-i18n.html
new file mode 100644
index 00000000000..26c61f88192
--- /dev/null
+++ b/scripts/migration/i18n/templates/test-migration/no-i18n.html
@@ -0,0 +1,5 @@
+
+
Static Title
+
This template has no i18n pipes
+
Static Button
+
+
appTitle
+
welcomeMessage
+
+ buttonText
+
+
+ home about
+
+ itemCount
+ camelCaseKey snake_case_key
+
diff --git a/scripts/migration/i18n/tsconfig.json b/scripts/migration/i18n/tsconfig.json
new file mode 100644
index 00000000000..1081656d04a
--- /dev/null
+++ b/scripts/migration/i18n/tsconfig.json
@@ -0,0 +1,19 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ "module": "commonjs",
+ "target": "es2020",
+ "lib": ["es2020"],
+ "declaration": false,
+ "strict": true,
+ "noImplicitReturns": true,
+ "noFallthroughCasesInSwitch": true,
+ "moduleResolution": "node",
+ "allowSyntheticDefaultImports": true,
+ "experimentalDecorators": true,
+ "importHelpers": true,
+ "types": ["node", "jest"]
+ },
+ "include": ["**/*.ts"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/scripts/migration/i18n/tsconfig.spec.json b/scripts/migration/i18n/tsconfig.spec.json
new file mode 100644
index 00000000000..1081656d04a
--- /dev/null
+++ b/scripts/migration/i18n/tsconfig.spec.json
@@ -0,0 +1,19 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ "module": "commonjs",
+ "target": "es2020",
+ "lib": ["es2020"],
+ "declaration": false,
+ "strict": true,
+ "noImplicitReturns": true,
+ "noFallthroughCasesInSwitch": true,
+ "moduleResolution": "node",
+ "allowSyntheticDefaultImports": true,
+ "experimentalDecorators": true,
+ "importHelpers": true,
+ "types": ["node", "jest"]
+ },
+ "include": ["**/*.ts"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/scripts/migration/i18n/typescript/README.md b/scripts/migration/i18n/typescript/README.md
new file mode 100644
index 00000000000..1cbf5e94691
--- /dev/null
+++ b/scripts/migration/i18n/typescript/README.md
@@ -0,0 +1,378 @@
+# TypeScript Migration CLI Tool
+
+This CLI tool automates the migration of TypeScript code from Bitwarden's custom I18nService to Angular's built-in `$localize` function.
+
+## Features
+
+- **Batch Processing**: Migrate multiple files efficiently with configurable batch sizes
+- **Validation**: Comprehensive validation of migration results
+- **Rollback Support**: Create backups and rollback changes if needed
+- **Detailed Reporting**: Generate comprehensive migration reports
+- **Error Recovery**: Continue processing even when individual files fail
+- **Progress Tracking**: Real-time progress updates during batch operations
+
+## Installation
+
+The tool is part of the Bitwarden clients repository and uses existing dependencies:
+
+```bash
+cd scripts/migration/i18n
+npm install # If package.json dependencies are needed
+```
+
+## Usage
+
+### Command Line Interface
+
+The CLI tool provides several commands:
+
+#### 1. Analyze Usage
+
+Analyze current I18nService usage patterns without making changes:
+
+```bash
+npm run cli analyze [options]
+
+# Examples:
+npm run cli analyze --verbose
+npm run cli analyze --output analysis-report.md
+npm run cli analyze --config ./custom-tsconfig.json
+```
+
+**Options:**
+
+- `-c, --config `: Path to tsconfig.json (default: ./tsconfig.json)
+- `-o, --output `: Output file for analysis report
+- `-v, --verbose`: Enable verbose logging
+
+#### 2. Migrate Files
+
+Migrate TypeScript files from I18nService to $localize:
+
+```bash
+npm run cli migrate [options]
+
+# Examples:
+npm run cli migrate --dry-run --verbose
+npm run cli migrate --file ./src/component.ts
+npm run cli migrate --backup --output ./migration-reports
+```
+
+**Options:**
+
+- `-c, --config `: Path to tsconfig.json (default: ./tsconfig.json)
+- `-f, --file `: Migrate specific file only
+- `-d, --dry-run`: Preview changes without applying them
+- `-o, --output `: Output directory for migration reports
+- `-v, --verbose`: Enable verbose logging
+- `--backup`: Create backup files before migration
+
+#### 3. Validate Migration
+
+Validate migration results and check for issues:
+
+```bash
+npm run cli validate [options]
+
+# Examples:
+npm run cli validate --verbose
+npm run cli validate --config ./tsconfig.json
+```
+
+**Options:**
+
+- `-c, --config `: Path to tsconfig.json (default: ./tsconfig.json)
+- `-v, --verbose`: Enable verbose logging
+
+#### 4. Rollback Changes
+
+Rollback migration using backup files:
+
+```bash
+npm run cli rollback [options]
+
+# Examples:
+npm run cli rollback --backup-dir ./migration-reports/backups
+npm run cli rollback --verbose
+```
+
+**Options:**
+
+- `-b, --backup-dir `: Path to backup directory (default: ./migration-reports/backups)
+- `-v, --verbose`: Enable verbose logging
+
+### Programmatic Usage
+
+You can also use the migration tools programmatically:
+
+```typescript
+import { TypeScriptMigrator } from "./typescript-migrator";
+import { BatchMigrator } from "./batch-migrator";
+import { MigrationValidator } from "./migration-validator";
+
+// Basic migration
+const config = {
+ sourceRoot: process.cwd(),
+ tsConfigPath: "./tsconfig.json",
+ dryRun: false,
+ verbose: true,
+};
+
+const migrator = new TypeScriptMigrator(config);
+const results = await migrator.migrateAll();
+
+// Batch migration with options
+const batchOptions = {
+ config,
+ batchSize: 10,
+ maxConcurrency: 3,
+ outputDir: "./reports",
+ createBackups: true,
+ continueOnError: true,
+};
+
+const batchMigrator = new BatchMigrator(batchOptions);
+const batchResult = await batchMigrator.migrate();
+
+// Validation
+const validator = new MigrationValidator(config);
+const validationResult = await validator.validate();
+```
+
+## Migration Process
+
+### What Gets Migrated
+
+The tool transforms the following patterns:
+
+#### Simple Translation Calls
+
+```typescript
+// Before
+this.i18nService.t("loginRequired");
+
+// After
+$localize`loginRequired`;
+```
+
+#### Parameterized Translation Calls
+
+```typescript
+// Before
+this.i18nService.t("itemCount", count.toString());
+
+// After
+$localize`itemCount${count.toString()}:param0:`;
+```
+
+#### Multiple Parameters
+
+```typescript
+// Before
+this.i18nService.t("welcomeMessage", name, role);
+
+// After
+$localize`welcomeMessage${name}:param0:${role}:param1:`;
+```
+
+#### Import Cleanup
+
+The tool automatically removes unused I18nService imports when they're no longer needed:
+
+```typescript
+// Before
+import { I18nService } from "@bitwarden/common/platform/services/i18n.service";
+
+class Component {
+ test() {
+ return this.i18nService.t("message");
+ }
+}
+
+// After
+class Component {
+ test() {
+ return $localize`message`;
+ }
+}
+```
+
+### What Doesn't Get Migrated
+
+- Constructor parameters and type annotations are preserved if I18nService is still used for other purposes
+- Dynamic translation keys (variables) require manual review
+- Complex parameter expressions may need manual adjustment
+
+## Validation
+
+The validation system checks for:
+
+### Errors (Migration Blockers)
+
+- Remaining I18nService.t() calls that weren't migrated
+- TypeScript compilation errors
+- Syntax errors in generated code
+
+### Warnings (Potential Issues)
+
+- Malformed $localize parameter syntax
+- Complex expressions in template literals
+- Unescaped special characters
+
+### Info (Recommendations)
+
+- Files that might benefit from explicit $localize imports
+- Performance optimization opportunities
+
+## Reports
+
+The tool generates several types of reports:
+
+### Analysis Report
+
+- Usage statistics across the codebase
+- Most common translation keys
+- Files with the most I18nService usage
+
+### Migration Report
+
+- Detailed list of all changes made
+- Success/failure statistics
+- Performance metrics
+- Before/after code comparisons
+
+### Validation Report
+
+- Comprehensive issue analysis
+- Categorized problems by severity
+- File-by-file breakdown of issues
+
+## Sample Test
+
+Run the sample test to see the tool in action:
+
+```bash
+npm run sample-test
+```
+
+This creates sample TypeScript files and demonstrates the complete migration workflow:
+
+1. Analysis of I18nService usage
+2. Batch migration with backups
+3. Validation of results
+4. Display of transformed code
+
+## Best Practices
+
+### Before Migration
+
+1. **Backup your code**: Always use version control and consider the `--backup` option
+2. **Run analysis first**: Use `analyze` command to understand the scope
+3. **Test on a subset**: Start with a single file or directory
+4. **Review complex cases**: Check files with dynamic keys or complex parameters
+
+### During Migration
+
+1. **Use dry-run mode**: Preview changes before applying them
+2. **Enable verbose logging**: Monitor progress and catch issues early
+3. **Process in batches**: Use reasonable batch sizes for large codebases
+4. **Continue on errors**: Use `continueOnError` to process as much as possible
+
+### After Migration
+
+1. **Run validation**: Always validate results after migration
+2. **Test your application**: Ensure functionality works as expected
+3. **Review reports**: Check migration reports for any issues
+4. **Update build configuration**: Configure Angular's i18n extraction
+
+## Troubleshooting
+
+### Common Issues
+
+#### "File not found" errors
+
+- Ensure tsconfig.json path is correct
+- Check that source files are included in TypeScript project
+
+#### "Remaining I18nService usage" warnings
+
+- Review files manually for dynamic keys or complex usage
+- Some patterns may require manual migration
+
+#### Performance issues with large codebases
+
+- Reduce batch size and concurrency
+- Process specific directories instead of entire codebase
+- Use file filtering options
+
+#### Compilation errors after migration
+
+- Check for missing imports or type issues
+- Review complex parameter transformations
+- Ensure $localize is properly configured
+
+### Getting Help
+
+1. Check the validation report for specific issues
+2. Review the migration report for transformation details
+3. Use verbose mode for detailed logging
+4. Test with sample files first
+
+## Configuration
+
+### TypeScript Configuration
+
+Ensure your tsconfig.json includes all files you want to migrate:
+
+```json
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ES2020",
+ "strict": true
+ },
+ "include": ["src/**/*.ts", "libs/**/*.ts"]
+}
+```
+
+### Migration Configuration
+
+The MigrationConfig interface supports:
+
+```typescript
+interface MigrationConfig {
+ sourceRoot: string; // Root directory for source files
+ tsConfigPath: string; // Path to TypeScript configuration
+ dryRun: boolean; // Preview mode without changes
+ verbose: boolean; // Detailed logging
+}
+```
+
+### Batch Configuration
+
+For large codebases, configure batch processing:
+
+```typescript
+interface BatchMigrationOptions {
+ config: MigrationConfig;
+ batchSize: number; // Files per batch (default: 10)
+ maxConcurrency: number; // Concurrent file processing (default: 3)
+ outputDir: string; // Report output directory
+ createBackups: boolean; // Create backup files
+ continueOnError: boolean; // Continue on individual file errors
+}
+```
+
+## Contributing
+
+When contributing to the migration tools:
+
+1. Add tests for new transformation patterns
+2. Update validation rules for new edge cases
+3. Maintain backward compatibility
+4. Document new features and options
+5. Test with real-world codebases
+
+## License
+
+This tool is part of the Bitwarden clients repository and follows the same GPL-3.0 license.
diff --git a/scripts/migration/i18n/typescript/ast-transformer.spec.ts b/scripts/migration/i18n/typescript/ast-transformer.spec.ts
new file mode 100644
index 00000000000..cc2578de8d9
--- /dev/null
+++ b/scripts/migration/i18n/typescript/ast-transformer.spec.ts
@@ -0,0 +1,362 @@
+import { Project, SourceFile } from "ts-morph";
+
+import { ASTTransformer } from "./ast-transformer";
+
+describe("ASTTransformer", () => {
+ let project: Project;
+ let transformer: ASTTransformer;
+ let sourceFile: SourceFile;
+
+ beforeEach(async () => {
+ project = new Project({
+ useInMemoryFileSystem: true,
+ });
+ transformer = new ASTTransformer();
+
+ // Initialize with mock translations for testing
+ await transformer.initialize();
+
+ // Mock the translation lookup to return predictable results for tests
+ const mockTranslationEntries: Record = {
+ loginWithDevice: { message: "loginWithDevice" },
+ itemsCount: {
+ message: "itemsCount $COUNT$",
+ placeholders: {
+ count: { content: "$1" },
+ },
+ },
+ testMessage: { message: "testMessage" },
+ simpleMessage: { message: "simpleMessage" },
+ itemCount: {
+ message: "itemCount $COUNT$",
+ placeholders: {
+ count: { content: "$1" },
+ },
+ },
+ message1: { message: "message1" },
+ message2: {
+ message: "message2 $PARAM$",
+ placeholders: {
+ param: { content: "$1" },
+ },
+ },
+ };
+
+ jest
+ .spyOn(transformer["translationLookup"], "getTranslation")
+ .mockImplementation((key: string) => {
+ return mockTranslationEntries[key]?.message || null;
+ });
+
+ jest
+ .spyOn(transformer["translationLookup"], "getTranslationEntry")
+ .mockImplementation((key: string) => {
+ return mockTranslationEntries[key] || null;
+ });
+
+ jest
+ .spyOn(transformer["translationLookup"], "hasTranslation")
+ .mockImplementation((key: string) => {
+ return key in mockTranslationEntries;
+ });
+ });
+
+ it("should find I18nService.t() calls", () => {
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ const message = this.i18nService.t('loginWithDevice');
+ const countMessage = this.i18nService.t('itemsCount', count.toString());
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ const usages = transformer.findI18nServiceCalls(sourceFile);
+
+ expect(usages).toHaveLength(2);
+ expect(usages[0].key).toBe("loginWithDevice");
+ expect(usages[0].method).toBe("t");
+ expect(usages[1].key).toBe("itemsCount");
+ expect(usages[1].parameters).toEqual(["count.toString()"]);
+ });
+
+ it("should transform I18nService.t() to $localize but keep import due to constructor usage", () => {
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ const message = this.i18nService.t('loginWithDevice');
+ }
+ }
+ `;
+
+ const expected = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ const message = $localize\`:@@loginWithDevice:loginWithDevice\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should handle parameters in I18nService.t() calls", () => {
+ const code = `
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('itemsCount', count.toString());
+ }
+ }
+ `;
+
+ const expected = `
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@itemsCount:itemsCount \${count.toString()}:count:\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should handle files without I18nService usage", () => {
+ const code = `
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ test() {
+ console.log('no i18n here');
+ }
+ }
+ `;
+
+ const expected = `
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ test() {
+ console.log('no i18n here');
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should remove I18nService import when no longer used", () => {
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('loginWithDevice');
+ }
+ }
+ `;
+
+ const expected = `
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@loginWithDevice:loginWithDevice\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should handle complex transformation scenarios", () => {
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ getMessage() {
+ return this.i18nService.t('simpleMessage');
+ }
+
+ getParameterizedMessage(count: number) {
+ return this.i18nService.t('itemCount', count.toString());
+ }
+
+ getMultipleMessages() {
+ const msg1 = this.i18nService.t('message1');
+ const msg2 = this.i18nService.t('message2', 'param');
+ return [msg1, msg2];
+ }
+ }
+ `;
+
+ const expected = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ getMessage() {
+ return $localize\`:@@simpleMessage:simpleMessage\`;
+ }
+
+ getParameterizedMessage(count: number) {
+ return $localize\`:@@itemCount:itemCount \${count.toString()}:count:\`;
+ }
+
+ getMultipleMessages() {
+ const msg1 = $localize\`:@@message1:message1\`;
+ const msg2 = $localize\`:@@message2:message2 \${'param'}:param:\`;
+ return [msg1, msg2];
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("complex-test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should remove import when only method calls are used (no constructor)", () => {
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('testMessage');
+ }
+ }
+ `;
+
+ const expected = `
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@testMessage:testMessage\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("no-constructor-test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should use translation lookup to generate proper $localize calls with actual text", () => {
+ const code = `
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('loginWithDevice');
+ }
+ }
+ `;
+
+ const expected = `
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@loginWithDevice:loginWithDevice\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("translation-lookup-test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should handle parameter substitution with translation lookup", () => {
+ // Mock translation with parameter placeholder in $VAR$ format
+ const mockTranslationEntry = {
+ message: "Items: $COUNT$",
+ placeholders: {
+ count: { content: "$1" },
+ },
+ };
+ jest
+ .spyOn(transformer["translationLookup"], "getTranslationEntry")
+ .mockReturnValue(mockTranslationEntry);
+ jest.spyOn(transformer["translationLookup"], "hasTranslation").mockReturnValue(true);
+
+ const code = `
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('itemsCount', count.toString());
+ }
+ }
+ `;
+
+ const expected = `
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@itemsCount:Items: \${count.toString()}:count:\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("param-translation-test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should fallback to key when translation is not found", () => {
+ const code = `
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('unknownKey');
+ }
+ }
+ `;
+
+ const expected = `
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@unknownKey:unknownKey\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("fallback-test.ts", code);
+ const result = transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ expect(result.errors).toContain("Warning: No translation found for key 'unknownKey' at line 4");
+ });
+});
diff --git a/scripts/migration/i18n/typescript/ast-transformer.ts b/scripts/migration/i18n/typescript/ast-transformer.ts
new file mode 100644
index 00000000000..c28b32fdaa3
--- /dev/null
+++ b/scripts/migration/i18n/typescript/ast-transformer.ts
@@ -0,0 +1,277 @@
+import { SourceFile, Node } from "ts-morph";
+
+import { TranslationLookup } from "../shared/translation-lookup";
+import { TransformationResult, TransformationChange, I18nUsage } from "../shared/types";
+
+/**
+ * AST transformation utilities for TypeScript code migration
+ */
+export class ASTTransformer {
+ private translationLookup: TranslationLookup;
+
+ constructor(rootPath?: string) {
+ this.translationLookup = new TranslationLookup(rootPath);
+ }
+
+ /**
+ * Initialize the translation lookup system
+ */
+ async initialize(combinedFilePath?: string): Promise {
+ await this.translationLookup.loadTranslations(combinedFilePath);
+ }
+
+ /**
+ * Find all I18nService.t() method calls in a source file
+ */
+ findI18nServiceCalls(sourceFile: SourceFile): I18nUsage[] {
+ const usages: I18nUsage[] = [];
+
+ sourceFile.forEachDescendant((node) => {
+ if (Node.isCallExpression(node)) {
+ const expression = node.getExpression();
+
+ if (Node.isPropertyAccessExpression(expression)) {
+ const object = expression.getExpression();
+ const property = expression.getName();
+
+ // Check if this is a call to i18nService.t() or this.i18n.t()
+ if (property === "t" && this.isI18nServiceAccess(object)) {
+ const args = node.getArguments();
+ if (args.length > 0) {
+ const keyArg = args[0];
+ const key = this.extractStringLiteral(keyArg);
+
+ if (key) {
+ const parameters = args.slice(1).map((arg) => arg.getText());
+ const { line, column } = sourceFile.getLineAndColumnAtPos(node.getStart());
+
+ usages.push({
+ filePath: sourceFile.getFilePath(),
+ line,
+ column,
+ method: "t",
+ key,
+ parameters: parameters.length > 0 ? parameters : undefined,
+ });
+ }
+ }
+ }
+ }
+ }
+ });
+
+ return usages;
+ }
+
+ /**
+ * Transform I18nService.t() calls to $localize calls
+ */
+ transformI18nServiceCalls(sourceFile: SourceFile): TransformationResult {
+ const changes: TransformationChange[] = [];
+ const errors: string[] = [];
+
+ try {
+ // Find and replace I18nService calls
+ sourceFile.forEachDescendant((node) => {
+ if (Node.isCallExpression(node)) {
+ const expression = node.getExpression();
+
+ if (Node.isPropertyAccessExpression(expression)) {
+ const object = expression.getExpression();
+ const property = expression.getName();
+
+ if (property === "t" && this.isI18nServiceAccess(object)) {
+ const args = node.getArguments();
+ if (args.length > 0) {
+ const keyArg = args[0];
+ const key = this.extractStringLiteral(keyArg);
+
+ if (key) {
+ const { line, column } = sourceFile.getLineAndColumnAtPos(node.getStart());
+ const original = node.getText();
+
+ // Generate $localize replacement
+ const replacement = this.generateLocalizeCall(key, args.slice(1));
+
+ // Check if translation was found
+ const hasTranslation = this.translationLookup.hasTranslation(key);
+ if (!hasTranslation) {
+ errors.push(`Warning: No translation found for key '${key}' at line ${line}`);
+ }
+
+ // Replace the node
+ node.replaceWithText(replacement);
+
+ changes.push({
+ type: "replace",
+ location: { line, column },
+ original,
+ replacement,
+ description: `Replaced i18nService.t('${key}') with $localize${hasTranslation ? "" : " (translation not found)"}`,
+ });
+ }
+ }
+ }
+ }
+ }
+ });
+
+ // Remove I18nService imports if no longer used
+ this.removeUnusedI18nImports(sourceFile, changes);
+
+ return {
+ success: true,
+ filePath: sourceFile.getFilePath(),
+ changes,
+ errors,
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ errors.push(`Error transforming file: ${errorMessage}`);
+ return {
+ success: false,
+ filePath: sourceFile.getFilePath(),
+ changes,
+ errors,
+ };
+ }
+ }
+
+ /**
+ * Check if a node represents access to I18nService
+ */
+ private isI18nServiceAccess(node: Node): boolean {
+ const text = node.getText();
+ return text.includes("i18nService") || text.includes("i18n") || text.includes("this.i18n");
+ }
+
+ /**
+ * Extract string literal value from a node
+ */
+ private extractStringLiteral(node: Node): string | null {
+ if (Node.isStringLiteral(node)) {
+ return node.getLiteralValue();
+ }
+ if (Node.isNoSubstitutionTemplateLiteral(node)) {
+ return node.getLiteralValue();
+ }
+ return null;
+ }
+
+ /**
+ * Generate $localize call with parameters using actual translation text
+ */
+ private generateLocalizeCall(key: string, paramArgs: Node[]): string {
+ // Get the full translation entry from the lookup
+ const translationEntry = this.translationLookup.getTranslationEntry(key);
+ const messageText = translationEntry?.message || key; // Fallback to key if translation not found
+
+ if (paramArgs.length === 0) {
+ // Simple case: no parameters
+ return `$localize\`:@@${key}:${this.escapeForTemplate(messageText)}\``;
+ }
+
+ // Handle parameter substitution using the placeholders object
+ let processedMessage = messageText;
+ const placeholders = translationEntry?.placeholders || {};
+
+ // Create a map of parameter positions to arguments based on placeholders
+ const paramMap = new Map();
+
+ // Map placeholders to parameter arguments
+ Object.entries(placeholders).forEach(([placeholderName, placeholderInfo]) => {
+ const content = placeholderInfo.content;
+ if (content && content.startsWith("$") && content.length > 1) {
+ // Extract parameter number from content like "$1", "$2", etc.
+ const paramNumber = parseInt(content.substring(1));
+ if (!isNaN(paramNumber) && paramNumber > 0 && paramNumber <= paramArgs.length) {
+ const argIndex = paramNumber - 1;
+ paramMap.set(placeholderName.toUpperCase(), {
+ arg: paramArgs[argIndex].getText(),
+ paramName: placeholderName,
+ });
+ }
+ }
+ });
+
+ // Replace $VAR$ placeholders in the message with $localize parameter syntax
+ paramMap.forEach(({ arg, paramName }, placeholderName) => {
+ const placeholder = `$${placeholderName}$`;
+ if (processedMessage.includes(placeholder)) {
+ processedMessage = processedMessage.replace(placeholder, `\${${arg}}:${paramName}:`);
+ }
+ });
+
+ // Handle any remaining parameters that weren't mapped through placeholders
+ // This is a fallback for cases where placeholders might not be properly defined
+ paramArgs.forEach((arg, index) => {
+ const paramName = `param${index}`;
+ const genericPlaceholder = `$${index + 1}$`;
+ if (processedMessage.includes(genericPlaceholder)) {
+ processedMessage = processedMessage.replace(
+ genericPlaceholder,
+ `\${${arg.getText()}}:${paramName}:`,
+ );
+ }
+ });
+
+ return `$localize\`:@@${key}:${this.escapeForTemplate(processedMessage)}\``;
+ }
+
+ /**
+ * Escape special characters for template literal usage
+ * Preserves $localize parameter syntax like ${param}:name:
+ */
+ private escapeForTemplate(text: string): string {
+ return (
+ text
+ .replace(/\\/g, "\\\\") // Escape backslashes
+ .replace(/`/g, "\\`") // Escape backticks
+ // Don't escape $ that are part of ${...}: parameter syntax
+ .replace(/\$(?!\{[^}]+\}:[^:]*:)/g, "\\$")
+ );
+ }
+
+ /**
+ * Remove unused I18nService imports
+ */
+ private removeUnusedI18nImports(sourceFile: SourceFile, changes: TransformationChange[]): void {
+ const imports = sourceFile.getImportDeclarations();
+
+ imports.forEach((importDecl) => {
+ const moduleSpecifier = importDecl.getModuleSpecifierValue();
+
+ if (moduleSpecifier.includes("i18n.service")) {
+ // Check if I18nService is still used in the file
+ const text = sourceFile.getFullText();
+
+ // Look for actual I18nService usage (constructor parameters, type annotations, etc.)
+ // but exclude the .t() method calls since we've transformed those
+ const hasI18nServiceType =
+ text.includes(": I18nService") ||
+ text.includes("") ||
+ text.includes("I18nService>") ||
+ text.includes("I18nService,") ||
+ text.includes("I18nService)");
+
+ // Check for remaining .t() calls that weren't transformed
+ const hasRemainingTCalls = text.match(/\bi18nService\.t\s*\(/);
+
+ // Only remove if there are no type references and no remaining method calls
+ if (!hasI18nServiceType && !hasRemainingTCalls) {
+ const { line, column } = sourceFile.getLineAndColumnAtPos(importDecl.getStart());
+ const original = importDecl.getText();
+
+ importDecl.remove();
+
+ changes.push({
+ type: "remove",
+ location: { line, column },
+ original,
+ description: "Removed unused I18nService import",
+ });
+ }
+ }
+ });
+ }
+}
diff --git a/scripts/migration/i18n/typescript/batch-migrator.spec.ts b/scripts/migration/i18n/typescript/batch-migrator.spec.ts
new file mode 100644
index 00000000000..8065644a919
--- /dev/null
+++ b/scripts/migration/i18n/typescript/batch-migrator.spec.ts
@@ -0,0 +1,360 @@
+// Mock chalk to avoid dependency issues in test environment
+jest.mock("chalk", () => ({
+ default: {
+ blue: (text: string) => text,
+ yellow: (text: string) => text,
+ green: (text: string) => text,
+ red: (text: string) => text,
+ cyan: (text: string) => text,
+ gray: (text: string) => text,
+ },
+ blue: (text: string) => text,
+ yellow: (text: string) => text,
+ green: (text: string) => text,
+ red: (text: string) => text,
+ cyan: (text: string) => text,
+ gray: (text: string) => text,
+}));
+
+import * as fs from "fs";
+import * as path from "path";
+
+import { Project } from "ts-morph";
+
+import { MigrationConfig } from "../shared/types";
+
+import { BatchMigrator, BatchMigrationOptions } from "./batch-migrator";
+import { MigrationValidator } from "./migration-validator";
+
+describe("BatchMigrator", () => {
+ let project: Project;
+ let tempDir: string;
+ let config: MigrationConfig;
+
+ beforeEach(() => {
+ // Create temporary directory for test files
+ tempDir = path.join(__dirname, "temp-test-" + Date.now());
+ fs.mkdirSync(tempDir, { recursive: true });
+
+ // Create test tsconfig.json
+ const tsConfigPath = path.join(tempDir, "tsconfig.json");
+ fs.writeFileSync(
+ tsConfigPath,
+ JSON.stringify({
+ compilerOptions: {
+ target: "ES2020",
+ module: "ES2020",
+ lib: ["ES2020", "DOM"],
+ strict: true,
+ esModuleInterop: true,
+ skipLibCheck: true,
+ forceConsistentCasingInFileNames: true,
+ },
+ include: ["**/*.ts"],
+ }),
+ );
+
+ config = {
+ sourceRoot: tempDir,
+ tsConfigPath,
+ dryRun: false,
+ verbose: false,
+ };
+
+ project = new Project({
+ tsConfigFilePath: tsConfigPath,
+ skipAddingFilesFromTsConfig: true,
+ });
+ });
+
+ afterEach(() => {
+ // Clean up temporary directory
+ if (fs.existsSync(tempDir)) {
+ fs.rmSync(tempDir, { recursive: true, force: true });
+ }
+ });
+
+ it("should handle batch migration of multiple files", async () => {
+ // Create test files
+ const testFiles = [
+ {
+ path: path.join(tempDir, "component1.ts"),
+ content: `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class Component1 {
+ constructor(private i18nService: I18nService) {}
+
+ getMessage() {
+ return this.i18nService.t('message1');
+ }
+ }
+ `,
+ },
+ {
+ path: path.join(tempDir, "component2.ts"),
+ content: `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class Component2 {
+ test() {
+ const msg = this.i18nService.t('message2', 'param');
+ return msg;
+ }
+ }
+ `,
+ },
+ {
+ path: path.join(tempDir, "service.ts"),
+ content: `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestService {
+ constructor(private i18n: I18nService) {}
+
+ getMessages() {
+ return [
+ this.i18n.t('service.message1'),
+ this.i18n.t('service.message2', count.toString())
+ ];
+ }
+ }
+ `,
+ },
+ ];
+
+ // Write test files
+ testFiles.forEach((file) => {
+ fs.writeFileSync(file.path, file.content);
+ project.addSourceFileAtPath(file.path);
+ });
+
+ const options: BatchMigrationOptions = {
+ config,
+ batchSize: 2,
+ maxConcurrency: 1,
+ outputDir: path.join(tempDir, "reports"),
+ createBackups: true,
+ continueOnError: true,
+ };
+
+ const batchMigrator = new BatchMigrator(options);
+ const result = await batchMigrator.migrate();
+
+ expect(result.totalFiles).toBe(3);
+ expect(result.successfulFiles).toBe(3);
+ expect(result.failedFiles).toBe(0);
+ expect(result.results).toHaveLength(3);
+
+ // Verify backups were created
+ const backupDir = path.join(tempDir, "reports", "backups");
+ expect(fs.existsSync(backupDir)).toBe(true);
+
+ // Verify files were transformed
+ const transformedFile1 = fs.readFileSync(testFiles[0].path, "utf8");
+ expect(transformedFile1).toContain("$localize`:@@message1:message1`");
+ expect(transformedFile1).not.toContain("i18nService.t(");
+
+ const transformedFile2 = fs.readFileSync(testFiles[1].path, "utf8");
+ expect(transformedFile2).toContain("$localize`:@@message2:message2");
+ expect(transformedFile2).not.toContain("I18nService");
+ });
+
+ it("should handle errors gracefully and continue processing", async () => {
+ // Create a file with syntax errors
+ const invalidFile = path.join(tempDir, "invalid.ts");
+ fs.writeFileSync(
+ invalidFile,
+ `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class Invalid {
+ // Syntax error - missing closing brace
+ test() {
+ return this.i18nService.t('test');
+ }
+ `,
+ );
+
+ const validFile = path.join(tempDir, "valid.ts");
+ fs.writeFileSync(
+ validFile,
+ `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class Valid {
+ test() {
+ return this.i18nService.t('valid');
+ }
+ }
+ `,
+ );
+
+ project.addSourceFileAtPath(invalidFile);
+ project.addSourceFileAtPath(validFile);
+
+ const options: BatchMigrationOptions = {
+ config,
+ batchSize: 1,
+ maxConcurrency: 1,
+ outputDir: path.join(tempDir, "reports"),
+ createBackups: false,
+ continueOnError: true,
+ };
+
+ const batchMigrator = new BatchMigrator(options);
+ const result = await batchMigrator.migrate();
+
+ expect(result.totalFiles).toBe(2);
+ expect(result.successfulFiles).toBe(2); // Both files should be processed successfully
+ expect(result.failedFiles).toBe(0);
+
+ // Valid file should be processed
+ const validContent = fs.readFileSync(validFile, "utf8");
+ expect(validContent).toContain("$localize`:@@valid:valid`");
+ });
+
+ it("should validate migration results", async () => {
+ // Create test file
+ const testFile = path.join(tempDir, "test.ts");
+ fs.writeFileSync(
+ testFile,
+ `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class Test {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ return this.i18nService.t('test');
+ }
+ }
+ `,
+ );
+
+ project.addSourceFileAtPath(testFile);
+
+ const options: BatchMigrationOptions = {
+ config,
+ batchSize: 1,
+ maxConcurrency: 1,
+ outputDir: path.join(tempDir, "reports"),
+ createBackups: false,
+ continueOnError: true,
+ };
+
+ const batchMigrator = new BatchMigrator(options);
+ await batchMigrator.migrate();
+
+ // Validate results
+ const validation = await batchMigrator.validateMigration();
+ expect(validation.isValid).toBe(true);
+ expect(validation.remainingUsages).toBe(0);
+ expect(validation.issues).toHaveLength(0);
+ });
+
+ it("should complete full migration workflow", async () => {
+ // Create realistic test scenario
+ const files = [
+ {
+ path: path.join(tempDir, "auth.component.ts"),
+ content: `
+ import { Component } from '@angular/core';
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ @Component({
+ selector: 'app-auth',
+ template: '{{ message }}
'
+ })
+ export class AuthComponent {
+ message: string;
+
+ constructor(private i18nService: I18nService) {}
+
+ ngOnInit() {
+ this.message = this.i18nService.t('loginRequired');
+ }
+
+ showError(count: number) {
+ return this.i18nService.t('errorCount', count.toString());
+ }
+ }
+ `,
+ },
+ {
+ path: path.join(tempDir, "vault.service.ts"),
+ content: `
+ import { Injectable } from '@angular/core';
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ @Injectable()
+ export class VaultService {
+ constructor(private i18n: I18nService) {}
+
+ getStatusMessage(status: string) {
+ switch (status) {
+ case 'locked':
+ return this.i18n.t('vaultLocked');
+ case 'unlocked':
+ return this.i18n.t('vaultUnlocked');
+ default:
+ return this.i18n.t('unknownStatus', status);
+ }
+ }
+ }
+ `,
+ },
+ ];
+
+ // Write test files
+ files.forEach((file) => {
+ fs.writeFileSync(file.path, file.content);
+ project.addSourceFileAtPath(file.path);
+ });
+
+ // Step 1: Batch Migration
+ const migrationOptions: BatchMigrationOptions = {
+ config,
+ batchSize: 10,
+ maxConcurrency: 2,
+ outputDir: path.join(tempDir, "reports"),
+ createBackups: true,
+ continueOnError: false,
+ };
+
+ const batchMigrator = new BatchMigrator(migrationOptions);
+ const migrationResult = await batchMigrator.migrate();
+
+ expect(migrationResult.successfulFiles).toBe(2);
+ expect(migrationResult.failedFiles).toBe(0);
+
+ // Step 2: Validation
+ const validator = new MigrationValidator(config);
+ const validationResult = await validator.validate();
+
+ // Validation may show TypeScript errors due to missing dependencies in test environment
+ // but the migration itself should be successful
+ expect(validationResult.summary.remainingI18nUsages).toBe(0);
+
+ // Step 3: Verify transformed content
+ const authContent = fs.readFileSync(files[0].path, "utf8");
+ expect(authContent).toContain("$localize`:@@loginRequired:loginRequired`");
+ expect(authContent).toContain("$localize`:@@errorCount:errorCount");
+ expect(authContent).not.toContain("i18nService.t(");
+
+ const vaultContent = fs.readFileSync(files[1].path, "utf8");
+ expect(vaultContent).toContain("$localize`:@@vaultLocked:vaultLocked`");
+ expect(vaultContent).toContain("$localize`:@@vaultUnlocked:vaultUnlocked`");
+ expect(vaultContent).toContain("$localize`:@@unknownStatus:unknownStatus");
+ expect(vaultContent).not.toContain("i18n.t(");
+
+ // Step 4: Verify reports were generated
+ const reportsDir = path.join(tempDir, "reports");
+ expect(fs.existsSync(reportsDir)).toBe(true);
+
+ const reportFiles = fs
+ .readdirSync(reportsDir)
+ .filter((f) => f.startsWith("batch-migration-report"));
+ expect(reportFiles.length).toBeGreaterThan(0);
+ });
+});
diff --git a/scripts/migration/i18n/typescript/batch-migrator.ts b/scripts/migration/i18n/typescript/batch-migrator.ts
new file mode 100644
index 00000000000..1badf507118
--- /dev/null
+++ b/scripts/migration/i18n/typescript/batch-migrator.ts
@@ -0,0 +1,306 @@
+/* eslint-disable no-console */
+import * as fs from "fs";
+import * as path from "path";
+
+import * as chalk from "chalk";
+
+import { MigrationConfig, TransformationResult } from "../shared/types";
+
+import { TypeScriptMigrator } from "./typescript-migrator";
+
+export interface BatchMigrationOptions {
+ config: MigrationConfig;
+ batchSize: number;
+ maxConcurrency: number;
+ outputDir: string;
+ createBackups: boolean;
+ continueOnError: boolean;
+}
+
+export interface BatchMigrationResult {
+ totalFiles: number;
+ processedFiles: number;
+ successfulFiles: number;
+ failedFiles: number;
+ skippedFiles: number;
+ results: TransformationResult[];
+ duration: number;
+}
+
+/**
+ * Handles batch migration of TypeScript files with progress tracking and error recovery
+ */
+export class BatchMigrator {
+ private migrator: TypeScriptMigrator;
+
+ constructor(private options: BatchMigrationOptions) {
+ this.migrator = new TypeScriptMigrator(options.config);
+ }
+
+ /**
+ * Execute batch migration with progress tracking
+ */
+ async migrate(): Promise {
+ const startTime = Date.now();
+
+ console.log(chalk.blue("🔍 Analyzing files to migrate..."));
+ const usages = this.migrator.analyzeUsage();
+ const filesToMigrate = Array.from(new Set(usages.map((u) => u.filePath)));
+
+ console.log(chalk.blue(`📊 Found ${filesToMigrate.length} files to migrate`));
+
+ if (this.options.createBackups && !this.options.config.dryRun) {
+ await this.createBackups(filesToMigrate);
+ }
+
+ const results: TransformationResult[] = [];
+ let processedFiles = 0;
+ let successfulFiles = 0;
+ let failedFiles = 0;
+ const skippedFiles = 0;
+
+ // Process files in batches
+ for (let i = 0; i < filesToMigrate.length; i += this.options.batchSize) {
+ const batch = filesToMigrate.slice(i, i + this.options.batchSize);
+
+ console.log(
+ chalk.blue(
+ `📦 Processing batch ${Math.floor(i / this.options.batchSize) + 1}/${Math.ceil(filesToMigrate.length / this.options.batchSize)} (${batch.length} files)`,
+ ),
+ );
+
+ const batchResults = await this.processBatch(batch);
+ results.push(...batchResults);
+
+ // Update counters
+ for (const result of batchResults) {
+ processedFiles++;
+ if (result.success) {
+ successfulFiles++;
+ } else {
+ failedFiles++;
+ if (!this.options.continueOnError) {
+ console.error(
+ chalk.red(`❌ Migration failed for ${result.filePath}, stopping batch migration`),
+ );
+ break;
+ }
+ }
+ }
+
+ // Progress update
+ const progress = Math.round((processedFiles / filesToMigrate.length) * 100);
+ console.log(
+ chalk.gray(`Progress: ${progress}% (${processedFiles}/${filesToMigrate.length})`),
+ );
+ }
+
+ const duration = Date.now() - startTime;
+
+ // Save changes if not in dry run mode
+ if (!this.options.config.dryRun) {
+ console.log(chalk.blue("💾 Saving changes..."));
+ await this.migrator["parser"].saveChanges();
+ }
+
+ // Generate comprehensive report
+ await this.generateBatchReport(results, duration);
+
+ return {
+ totalFiles: filesToMigrate.length,
+ processedFiles,
+ successfulFiles,
+ failedFiles,
+ skippedFiles,
+ results,
+ duration,
+ };
+ }
+
+ /**
+ * Process a batch of files with controlled concurrency
+ */
+ private async processBatch(filePaths: string[]): Promise {
+ const results: TransformationResult[] = [];
+
+ // Process files with limited concurrency
+ for (let i = 0; i < filePaths.length; i += this.options.maxConcurrency) {
+ const concurrentBatch = filePaths.slice(i, i + this.options.maxConcurrency);
+
+ const promises = concurrentBatch.map(async (filePath) => {
+ try {
+ if (this.options.config.verbose) {
+ console.log(chalk.gray(` Processing: ${path.relative(process.cwd(), filePath)}`));
+ }
+
+ return await this.migrator.migrateFile(filePath);
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ return {
+ success: false,
+ filePath,
+ changes: [],
+ errors: [`Batch processing error: ${errorMessage}`],
+ };
+ }
+ });
+
+ const batchResults = await Promise.all(promises);
+ results.push(...batchResults);
+ }
+
+ return results;
+ }
+
+ /**
+ * Create backup files before migration
+ */
+ private async createBackups(filePaths: string[]): Promise {
+ const backupDir = path.join(this.options.outputDir, "backups");
+
+ if (!fs.existsSync(backupDir)) {
+ fs.mkdirSync(backupDir, { recursive: true });
+ }
+
+ console.log(chalk.yellow("📦 Creating backups..."));
+
+ for (const filePath of filePaths) {
+ if (fs.existsSync(filePath)) {
+ const relativePath = path.relative(process.cwd(), filePath);
+ const backupPath = path.join(backupDir, relativePath.replace(/[/\\]/g, "_") + ".backup");
+
+ // Ensure backup directory exists
+ const backupFileDir = path.dirname(backupPath);
+ if (!fs.existsSync(backupFileDir)) {
+ fs.mkdirSync(backupFileDir, { recursive: true });
+ }
+
+ fs.copyFileSync(filePath, backupPath);
+ }
+ }
+
+ console.log(chalk.green(`📦 Created backups for ${filePaths.length} files in ${backupDir}`));
+ }
+
+ /**
+ * Generate comprehensive batch migration report
+ */
+ private async generateBatchReport(
+ results: TransformationResult[],
+ duration: number,
+ ): Promise {
+ const reportDir = this.options.outputDir;
+ if (!fs.existsSync(reportDir)) {
+ fs.mkdirSync(reportDir, { recursive: true });
+ }
+
+ const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+ const reportPath = path.join(reportDir, `batch-migration-report-${timestamp}.md`);
+
+ const successful = results.filter((r) => r.success).length;
+ const failed = results.filter((r) => !r.success).length;
+ const totalChanges = results.reduce((sum, r) => sum + r.changes.length, 0);
+
+ let report = `# Batch TypeScript Migration Report\n\n`;
+ report += `**Generated:** ${new Date().toISOString()}\n`;
+ report += `**Duration:** ${Math.round(duration / 1000)}s\n\n`;
+
+ report += `## Summary\n\n`;
+ report += `- **Total files:** ${results.length}\n`;
+ report += `- **Successful:** ${successful}\n`;
+ report += `- **Failed:** ${failed}\n`;
+ report += `- **Total changes:** ${totalChanges}\n`;
+ report += `- **Success rate:** ${Math.round((successful / results.length) * 100)}%\n\n`;
+
+ // Performance metrics
+ const avgTimePerFile = duration / results.length;
+ report += `## Performance Metrics\n\n`;
+ report += `- **Average time per file:** ${Math.round(avgTimePerFile)}ms\n`;
+ report += `- **Files per second:** ${Math.round(1000 / avgTimePerFile)}\n\n`;
+
+ // Change statistics
+ const changeTypes = results.reduce(
+ (acc, result) => {
+ result.changes.forEach((change) => {
+ acc[change.type] = (acc[change.type] || 0) + 1;
+ });
+ return acc;
+ },
+ {} as Record,
+ );
+
+ if (Object.keys(changeTypes).length > 0) {
+ report += `## Change Types\n\n`;
+ Object.entries(changeTypes).forEach(([type, count]) => {
+ report += `- **${type}:** ${count}\n`;
+ });
+ report += `\n`;
+ }
+
+ // Failed files section
+ if (failed > 0) {
+ report += `## Failed Files\n\n`;
+ results
+ .filter((r) => !r.success)
+ .forEach((result) => {
+ report += `### ${result.filePath}\n\n`;
+ result.errors.forEach((error) => {
+ report += `- ${error}\n`;
+ });
+ report += `\n`;
+ });
+ }
+
+ // Successful files with changes
+ const successfulWithChanges = results.filter((r) => r.success && r.changes.length > 0);
+ if (successfulWithChanges.length > 0) {
+ report += `## Successful Migrations\n\n`;
+ successfulWithChanges.forEach((result) => {
+ report += `### ${result.filePath}\n\n`;
+ result.changes.forEach((change) => {
+ report += `- **${change.type}** (Line ${change.location.line}): ${change.description}\n`;
+ if (change.original && change.replacement) {
+ report += ` - Before: \`${change.original}\`\n`;
+ report += ` - After: \`${change.replacement}\`\n`;
+ }
+ });
+ report += `\n`;
+ });
+ }
+
+ fs.writeFileSync(reportPath, report);
+ console.log(chalk.green(`📊 Batch migration report saved to: ${reportPath}`));
+ }
+
+ /**
+ * Validate batch migration results
+ */
+ async validateMigration(): Promise<{
+ isValid: boolean;
+ remainingUsages: number;
+ issues: string[];
+ }> {
+ console.log(chalk.blue("🔍 Validating batch migration results..."));
+
+ const issues: string[] = [];
+ const usages = this.migrator.analyzeUsage();
+
+ if (usages.length > 0) {
+ issues.push(`Found ${usages.length} remaining I18nService usages`);
+ usages.forEach((usage) => {
+ issues.push(` - ${usage.filePath}:${usage.line} - "${usage.key}"`);
+ });
+ }
+
+ // Additional validation checks could be added here
+ // - Check for compilation errors
+ // - Check for missing $localize imports
+ // - Check for malformed $localize calls
+
+ return {
+ isValid: issues.length === 0,
+ remainingUsages: usages.length,
+ issues,
+ };
+ }
+}
diff --git a/scripts/migration/i18n/typescript/cli.ts b/scripts/migration/i18n/typescript/cli.ts
new file mode 100644
index 00000000000..1d8d9f8c0a2
--- /dev/null
+++ b/scripts/migration/i18n/typescript/cli.ts
@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+import * as fs from "fs";
+import * as path from "path";
+
+import * as chalk from "chalk";
+import { Command } from "commander";
+
+import { MigrationConfig } from "../shared/types";
+
+import { TypeScriptMigrator } from "./typescript-migrator";
+
+const program = new Command();
+
+program
+ .name("i18n-typescript-migrator")
+ .description("CLI tool for migrating TypeScript code from I18nService to $localize")
+ .version("1.0.0");
+
+program
+ .command("analyze")
+ .description("Analyze current I18nService usage patterns")
+ .option("-c, --config ", "Path to tsconfig.json", "./tsconfig.json")
+ .option("-o, --output ", "Output file for analysis report")
+ .option("-v, --verbose", "Enable verbose logging")
+ .action(async (options) => {
+ try {
+ const config: MigrationConfig = {
+ sourceRoot: process.cwd(),
+ tsConfigPath: path.resolve(options.config),
+ dryRun: true,
+ verbose: options.verbose || false,
+ };
+
+ console.log(chalk.blue("🔍 Analyzing I18nService usage..."));
+
+ const migrator = new TypeScriptMigrator(config);
+ const report = migrator.generateAnalysisReport();
+
+ if (options.output) {
+ fs.writeFileSync(options.output, report);
+ console.log(chalk.green(`✅ Analysis report saved to: ${options.output}`));
+ } else {
+ console.log(report);
+ }
+ } catch (error) {
+ console.error(chalk.red("❌ Analysis failed:"), error);
+ process.exit(1);
+ }
+ });
+
+program
+ .command("migrate")
+ .description("Migrate TypeScript files from I18nService to $localize")
+ .option("-c, --config ", "Path to tsconfig.json", "./tsconfig.json")
+ .option("-f, --file ", "Migrate specific file only")
+ .option("-d, --dry-run", "Preview changes without applying them")
+ .option("-o, --output ", "Output directory for migration reports")
+ .option("-t, --translations ", "Path to combined translations file")
+ .option("-v, --verbose", "Enable verbose logging")
+ .option("--backup", "Create backup files before migration")
+ .action(async (options) => {
+ try {
+ const config: MigrationConfig = {
+ sourceRoot: process.cwd(),
+ tsConfigPath: path.resolve(options.config),
+ dryRun: options.dryRun || false,
+ verbose: options.verbose || false,
+ };
+
+ const migrator = new TypeScriptMigrator(config, options.translations);
+
+ if (options.backup && !options.dryRun) {
+ console.log(chalk.yellow("📦 Creating backups..."));
+ await createBackups(migrator, options.output || "./migration-reports");
+ }
+
+ console.log(chalk.blue("🚀 Starting TypeScript migration..."));
+
+ let results;
+ if (options.file) {
+ console.log(chalk.blue(`📄 Migrating file: ${options.file}`));
+ const result = await migrator.migrateFile(path.resolve(options.file));
+ results = [result];
+ } else {
+ results = await migrator.migrateAll();
+ }
+
+ const stats = migrator.generateMigrationStats(results);
+ console.log(stats);
+
+ // Save detailed report
+ if (options.output) {
+ const reportDir = options.output;
+ if (!fs.existsSync(reportDir)) {
+ fs.mkdirSync(reportDir, { recursive: true });
+ }
+
+ const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+ const reportPath = path.join(reportDir, `migration-report-${timestamp}.md`);
+
+ let detailedReport = stats + "\n\n## Detailed Changes\n\n";
+ results.forEach((result) => {
+ detailedReport += `### ${result.filePath}\n`;
+ if (result.success) {
+ result.changes.forEach((change) => {
+ detailedReport += `- ${change.description}\n`;
+ if (change.original) {
+ detailedReport += ` - **Before:** \`${change.original}\`\n`;
+ }
+ if (change.replacement) {
+ detailedReport += ` - **After:** \`${change.replacement}\`\n`;
+ }
+ });
+ } else {
+ detailedReport += "**Errors:**\n";
+ result.errors.forEach((error) => {
+ detailedReport += `- ${error}\n`;
+ });
+ }
+ detailedReport += "\n";
+ });
+
+ fs.writeFileSync(reportPath, detailedReport);
+ console.log(chalk.green(`📊 Detailed report saved to: ${reportPath}`));
+ }
+
+ const successful = results.filter((r) => r.success).length;
+ const failed = results.filter((r) => !r.success).length;
+
+ if (failed === 0) {
+ console.log(
+ chalk.green(`✅ Migration completed successfully! ${successful} files processed.`),
+ );
+ } else {
+ console.log(
+ chalk.yellow(
+ `⚠️ Migration completed with warnings. ${successful} successful, ${failed} failed.`,
+ ),
+ );
+ process.exit(1);
+ }
+ } catch (error) {
+ console.error(chalk.red("❌ Migration failed:"), error);
+ process.exit(1);
+ }
+ });
+
+program
+ .command("validate")
+ .description("Validate migration results and check for issues")
+ .option("-c, --config ", "Path to tsconfig.json", "./tsconfig.json")
+ .option("-v, --verbose", "Enable verbose logging")
+ .action(async (options) => {
+ try {
+ const config: MigrationConfig = {
+ sourceRoot: process.cwd(),
+ tsConfigPath: path.resolve(options.config),
+ dryRun: true,
+ verbose: options.verbose || false,
+ };
+
+ console.log(chalk.blue("🔍 Validating migration results..."));
+
+ const migrator = new TypeScriptMigrator(config);
+ const usages = migrator.analyzeUsage();
+
+ if (usages.length === 0) {
+ console.log(chalk.green("✅ No remaining I18nService usage found!"));
+ } else {
+ console.log(chalk.yellow(`⚠️ Found ${usages.length} remaining I18nService usages:`));
+ usages.forEach((usage) => {
+ console.log(` - ${usage.filePath}:${usage.line} - "${usage.key}"`);
+ });
+ process.exit(1);
+ }
+ } catch (error) {
+ console.error(chalk.red("❌ Validation failed:"), error);
+ process.exit(1);
+ }
+ });
+
+program
+ .command("rollback")
+ .description("Rollback migration using backup files")
+ .option("-b, --backup-dir ", "Path to backup directory", "./migration-reports/backups")
+ .option("-v, --verbose", "Enable verbose logging")
+ .action(async (options) => {
+ try {
+ console.log(chalk.blue("🔄 Rolling back migration..."));
+
+ const backupDir = options.backupDir;
+ if (!fs.existsSync(backupDir)) {
+ console.error(chalk.red(`❌ Backup directory not found: ${backupDir}`));
+ process.exit(1);
+ }
+
+ // Check for path mapping file
+ const mappingPath = path.join(backupDir, "path-mapping.json");
+ if (!fs.existsSync(mappingPath)) {
+ console.error(chalk.red("❌ Path mapping file not found. Cannot restore files safely."));
+ console.log(
+ chalk.gray("This backup was created with an older version that doesn't preserve paths."),
+ );
+ process.exit(1);
+ }
+
+ const pathMapping = JSON.parse(fs.readFileSync(mappingPath, "utf-8"));
+ const backupFiles = fs.readdirSync(backupDir).filter((f) => f.endsWith(".backup"));
+
+ if (backupFiles.length === 0) {
+ console.error(chalk.red("❌ No backup files found"));
+ process.exit(1);
+ }
+
+ let restoredCount = 0;
+ for (const backupFile of backupFiles) {
+ const backupPath = path.join(backupDir, backupFile);
+ const originalPath = pathMapping[backupFile];
+
+ if (!originalPath) {
+ console.warn(chalk.yellow(`⚠️ No mapping found for backup file: ${backupFile}`));
+ continue;
+ }
+
+ // Ensure the directory exists
+ const originalDir = path.dirname(originalPath);
+ if (!fs.existsSync(originalDir)) {
+ fs.mkdirSync(originalDir, { recursive: true });
+ }
+
+ fs.copyFileSync(backupPath, originalPath);
+ restoredCount++;
+
+ if (options.verbose) {
+ console.log(chalk.gray(`Restored: ${originalPath}`));
+ }
+ }
+
+ console.log(chalk.green(`✅ Rollback completed! ${restoredCount} files restored.`));
+ } catch (error) {
+ console.error(chalk.red("❌ Rollback failed:"), error);
+ process.exit(1);
+ }
+ });
+
+async function createBackups(migrator: TypeScriptMigrator, outputDir: string): Promise {
+ const backupDir = path.join(outputDir, "backups");
+ if (!fs.existsSync(backupDir)) {
+ fs.mkdirSync(backupDir, { recursive: true });
+ }
+
+ // Get all files that would be affected
+ const usages = migrator.analyzeUsage();
+ const filesToBackup = new Set(usages.map((u) => u.filePath));
+
+ // Create a mapping file to track original paths
+ const pathMapping: Record = {};
+
+ for (const filePath of filesToBackup) {
+ if (fs.existsSync(filePath)) {
+ // Create a unique backup filename that preserves path info
+ const relativePath = path.relative(process.cwd(), filePath);
+ const backupFileName = relativePath.replace(/[/\\]/g, "_") + ".backup";
+ const backupPath = path.join(backupDir, backupFileName);
+
+ fs.copyFileSync(filePath, backupPath);
+ pathMapping[backupFileName] = filePath;
+ }
+ }
+
+ // Save the path mapping for restoration
+ const mappingPath = path.join(backupDir, "path-mapping.json");
+ fs.writeFileSync(mappingPath, JSON.stringify(pathMapping, null, 2));
+
+ console.log(chalk.green(`📦 Created backups for ${filesToBackup.size} files`));
+}
+
+// Handle uncaught errors
+process.on("uncaughtException", (error) => {
+ console.error(chalk.red("❌ Uncaught Exception:"), error);
+ process.exit(1);
+});
+
+process.on("unhandledRejection", (reason, promise) => {
+ console.error(chalk.red("❌ Unhandled Rejection at:"), promise, "reason:", reason);
+ process.exit(1);
+});
+
+program.parse();
diff --git a/scripts/migration/i18n/typescript/demo-parameter-handling.ts b/scripts/migration/i18n/typescript/demo-parameter-handling.ts
new file mode 100644
index 00000000000..e9978b8ee41
--- /dev/null
+++ b/scripts/migration/i18n/typescript/demo-parameter-handling.ts
@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+import { Project } from "ts-morph";
+
+import { ASTTransformer } from "./ast-transformer";
+
+async function demonstrateParameterHandling() {
+ console.log("🔧 Demonstrating Parameter Handling with Translation Lookup\n");
+
+ const project = new Project({
+ useInMemoryFileSystem: true,
+ });
+
+ const transformer = new ASTTransformer();
+ await transformer.initialize();
+
+ // Mock a real translation entry like those found in the actual translation files
+ const mockTranslationEntry = {
+ message: "Data last updated: $DATE$",
+ placeholders: {
+ date: {
+ content: "$1",
+ example: "2021-01-01",
+ },
+ },
+ };
+
+ // Mock the translation lookup
+ jest
+ .spyOn(transformer["translationLookup"], "getTranslationEntry")
+ .mockReturnValue(mockTranslationEntry);
+ jest.spyOn(transformer["translationLookup"], "hasTranslation").mockReturnValue(true);
+
+ const code = `
+ class DataComponent {
+ updateStatus() {
+ const message = this.i18nService.t('dataLastUpdated', this.lastUpdateDate);
+ return message;
+ }
+ }
+ `;
+
+ console.log("📝 Original Code:");
+ console.log(code);
+
+ const sourceFile = project.createSourceFile("demo.ts", code);
+ const result = transformer.transformI18nServiceCalls(sourceFile);
+
+ console.log("\n✨ Transformed Code:");
+ console.log(sourceFile.getFullText());
+
+ console.log("\n📊 Transformation Result:");
+ console.log(`- Success: ${result.success}`);
+ console.log(`- Changes: ${result.changes.length}`);
+ console.log(`- Errors: ${result.errors.length}`);
+
+ if (result.changes.length > 0) {
+ console.log("\n🔄 Changes Made:");
+ result.changes.forEach((change, index) => {
+ console.log(` ${index + 1}. ${change.description}`);
+ console.log(` Original: ${change.original}`);
+ console.log(` Replacement: ${change.replacement}`);
+ });
+ }
+
+ console.log("\n✅ Key Features Demonstrated:");
+ console.log("- ✅ Uses actual translation text from lookup");
+ console.log("- ✅ Handles $VAR$ placeholder format correctly");
+ console.log("- ✅ Maps placeholders to parameter names");
+ console.log("- ✅ Generates proper $localize syntax with @@ID");
+ console.log("- ✅ Preserves parameter order and names");
+}
+
+// Only run if this file is executed directly
+if (require.main === module) {
+ demonstrateParameterHandling().catch(console.error);
+}
+
+export { demonstrateParameterHandling };
diff --git a/scripts/migration/i18n/typescript/migration-validator.spec.ts b/scripts/migration/i18n/typescript/migration-validator.spec.ts
new file mode 100644
index 00000000000..827f7263261
--- /dev/null
+++ b/scripts/migration/i18n/typescript/migration-validator.spec.ts
@@ -0,0 +1,209 @@
+// Mock chalk to avoid dependency issues in test environment
+jest.mock("chalk", () => ({
+ default: {
+ blue: (text: string) => text,
+ yellow: (text: string) => text,
+ green: (text: string) => text,
+ red: (text: string) => text,
+ cyan: (text: string) => text,
+ gray: (text: string) => text,
+ },
+ blue: (text: string) => text,
+ yellow: (text: string) => text,
+ green: (text: string) => text,
+ red: (text: string) => text,
+ cyan: (text: string) => text,
+ gray: (text: string) => text,
+}));
+
+import * as fs from "fs";
+import * as path from "path";
+
+import { Project } from "ts-morph";
+
+import { MigrationConfig } from "../shared/types";
+
+import { MigrationValidator } from "./migration-validator";
+
+describe("MigrationValidator", () => {
+ let project: Project;
+ let tempDir: string;
+ let config: MigrationConfig;
+
+ beforeEach(() => {
+ // Create temporary directory for test files
+ tempDir = path.join(__dirname, "temp-test-" + Date.now());
+ fs.mkdirSync(tempDir, { recursive: true });
+
+ // Create test tsconfig.json
+ const tsConfigPath = path.join(tempDir, "tsconfig.json");
+ fs.writeFileSync(
+ tsConfigPath,
+ JSON.stringify({
+ compilerOptions: {
+ target: "ES2020",
+ module: "ES2020",
+ lib: ["ES2020", "DOM"],
+ strict: true,
+ esModuleInterop: true,
+ skipLibCheck: true,
+ forceConsistentCasingInFileNames: true,
+ },
+ include: ["**/*.ts"],
+ }),
+ );
+
+ config = {
+ sourceRoot: tempDir,
+ tsConfigPath,
+ dryRun: false,
+ verbose: false,
+ };
+
+ project = new Project({
+ tsConfigFilePath: tsConfigPath,
+ skipAddingFilesFromTsConfig: true,
+ });
+ });
+
+ afterEach(() => {
+ // Clean up temporary directory
+ if (fs.existsSync(tempDir)) {
+ fs.rmSync(tempDir, { recursive: true, force: true });
+ }
+ });
+
+ it("should detect remaining I18nService usage", async () => {
+ // Create file with remaining I18nService usage
+ const testFile = path.join(tempDir, "remaining.ts");
+ fs.writeFileSync(
+ testFile,
+ `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class Test {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ // This should be detected as remaining usage
+ return this.i18nService.t('notMigrated');
+ }
+ }
+ `,
+ );
+
+ project.addSourceFileAtPath(testFile);
+
+ const validator = new MigrationValidator(config);
+ const result = await validator.validate();
+
+ expect(result.isValid).toBe(false);
+ expect(result.summary.remainingI18nUsages).toBe(1);
+ expect(result.issues.length).toBeGreaterThan(0);
+ const remainingUsageIssues = result.issues.filter((i) =>
+ i.message.includes("Remaining I18nService.t() call"),
+ );
+ expect(remainingUsageIssues.length).toBe(1);
+ expect(remainingUsageIssues[0].type).toBe("error");
+ });
+
+ it("should detect malformed $localize usage", async () => {
+ // Create file with malformed $localize
+ const testFile = path.join(tempDir, "malformed.ts");
+ fs.writeFileSync(
+ testFile,
+ `
+ class Test {
+ test() {
+ // Missing parameter name
+ return $localize\`Message with \${param}\`;
+ }
+ }
+ `,
+ );
+
+ project.addSourceFileAtPath(testFile);
+
+ const validator = new MigrationValidator(config);
+ const result = await validator.validate();
+
+ expect(result.summary.malformedLocalizeUsages).toBeGreaterThan(0);
+ const malformedIssues = result.issues.filter((i) => i.message.includes("malformed $localize"));
+ expect(malformedIssues.length).toBeGreaterThan(0);
+ });
+
+ it("should generate comprehensive validation report", async () => {
+ // Create mixed scenario file
+ const testFile = path.join(tempDir, "mixed.ts");
+ fs.writeFileSync(
+ testFile,
+ `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class Mixed {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ // Remaining usage (error)
+ const old = this.i18nService.t('old');
+
+ // Malformed $localize (warning)
+ const malformed = $localize\`Bad \${param}\`;
+
+ // Good $localize
+ const good = $localize\`Good \${param}:param:\`;
+
+ return [old, malformed, good];
+ }
+ }
+ `,
+ );
+
+ project.addSourceFileAtPath(testFile);
+
+ const validator = new MigrationValidator(config);
+ const result = await validator.validate();
+ const report = validator.generateReport(result);
+
+ expect(report).toContain("Migration Validation Report");
+ expect(report).toContain("INVALID");
+ expect(report).toContain("Remaining I18nService.t() call");
+ expect(report).toContain("malformed $localize");
+ expect(result.summary.errors).toBeGreaterThan(0);
+ expect(result.summary.warnings).toBeGreaterThan(0);
+ });
+
+ it("should validate files without issues", async () => {
+ // Create file with proper $localize usage
+ const testFile = path.join(tempDir, "valid.ts");
+ fs.writeFileSync(
+ testFile,
+ `
+ class Test {
+ test() {
+ return $localize\`Valid message\`;
+ }
+
+ testWithParam() {
+ return $localize\`Message with \${param}:param:\`;
+ }
+ }
+ `,
+ );
+
+ project.addSourceFileAtPath(testFile);
+
+ const validator = new MigrationValidator(config);
+ const result = await validator.validate();
+
+ expect(result.summary.remainingI18nUsages).toBe(0);
+ expect(result.summary.malformedLocalizeUsages).toBe(0);
+
+ // May have TypeScript errors due to missing dependencies, but no migration-specific issues
+ const migrationIssues = result.issues.filter(
+ (i) =>
+ i.message.includes("Remaining I18nService") || i.message.includes("malformed $localize"),
+ );
+ expect(migrationIssues).toHaveLength(0);
+ });
+});
diff --git a/scripts/migration/i18n/typescript/migration-validator.ts b/scripts/migration/i18n/typescript/migration-validator.ts
new file mode 100644
index 00000000000..2f67fd67657
--- /dev/null
+++ b/scripts/migration/i18n/typescript/migration-validator.ts
@@ -0,0 +1,385 @@
+/* eslint-disable no-console */
+import * as path from "path";
+
+import chalk from "chalk";
+import { Project, SourceFile, Node } from "ts-morph";
+
+import { MigrationConfig } from "../shared/types";
+
+export interface ValidationResult {
+ isValid: boolean;
+ issues: ValidationIssue[];
+ summary: ValidationSummary;
+}
+
+export interface ValidationIssue {
+ type: "error" | "warning" | "info";
+ filePath: string;
+ line: number;
+ column: number;
+ message: string;
+ code?: string;
+}
+
+export interface ValidationSummary {
+ totalFiles: number;
+ filesWithIssues: number;
+ errors: number;
+ warnings: number;
+ info: number;
+ remainingI18nUsages: number;
+ malformedLocalizeUsages: number;
+ missingImports: number;
+}
+
+/**
+ * Validates TypeScript migration results and checks for common issues
+ */
+export class MigrationValidator {
+ private project: Project;
+
+ constructor(private config: MigrationConfig) {
+ this.project = new Project({
+ tsConfigFilePath: config.tsConfigPath,
+ skipAddingFilesFromTsConfig: false,
+ });
+ }
+
+ /**
+ * Perform comprehensive validation of migration results
+ */
+ async validate(): Promise {
+ const issues: ValidationIssue[] = [];
+ const sourceFiles = this.project.getSourceFiles();
+
+ console.log(chalk.blue(`🔍 Validating ${sourceFiles.length} files...`));
+
+ for (const sourceFile of sourceFiles) {
+ if (this.config.verbose) {
+ console.log(
+ chalk.gray(` Validating: ${path.relative(process.cwd(), sourceFile.getFilePath())}`),
+ );
+ }
+
+ // Check for remaining I18nService usage
+ issues.push(...this.checkRemainingI18nUsage(sourceFile));
+
+ // Check for malformed $localize usage
+ issues.push(...this.checkMalformedLocalizeUsage(sourceFile));
+
+ // Check for missing imports
+ issues.push(...this.checkMissingImports(sourceFile));
+
+ // Check for compilation errors
+ issues.push(...this.checkCompilationErrors(sourceFile));
+
+ // Check for potential runtime issues
+ issues.push(...this.checkRuntimeIssues(sourceFile));
+ }
+
+ const summary = this.generateSummary(sourceFiles, issues);
+ const isValid = issues.filter((i) => i.type === "error").length === 0;
+
+ return {
+ isValid,
+ issues,
+ summary,
+ };
+ }
+
+ /**
+ * Check for remaining I18nService usage that wasn't migrated
+ */
+ private checkRemainingI18nUsage(sourceFile: SourceFile): ValidationIssue[] {
+ const issues: ValidationIssue[] = [];
+
+ sourceFile.forEachDescendant((node) => {
+ if (Node.isCallExpression(node)) {
+ const expression = node.getExpression();
+
+ if (Node.isPropertyAccessExpression(expression)) {
+ const object = expression.getExpression();
+ const property = expression.getName();
+
+ if (property === "t" && this.isI18nServiceAccess(object)) {
+ const { line, column } = sourceFile.getLineAndColumnAtPos(node.getStart());
+
+ issues.push({
+ type: "error",
+ filePath: sourceFile.getFilePath(),
+ line,
+ column,
+ message: "Remaining I18nService.t() call found - migration incomplete",
+ code: node.getText(),
+ });
+ }
+ }
+ }
+ });
+
+ return issues;
+ }
+
+ /**
+ * Check for malformed $localize usage
+ */
+ private checkMalformedLocalizeUsage(sourceFile: SourceFile): ValidationIssue[] {
+ const issues: ValidationIssue[] = [];
+
+ sourceFile.forEachDescendant((node) => {
+ if (Node.isTaggedTemplateExpression(node)) {
+ const tag = node.getTag();
+
+ if (Node.isIdentifier(tag) && tag.getText() === "$localize") {
+ const template = node.getTemplate();
+ const { line, column } = sourceFile.getLineAndColumnAtPos(node.getStart());
+
+ // Check for common malformed patterns
+ if (Node.isTemplateExpression(template)) {
+ const templateText = template.getText();
+
+ // Check for missing parameter names
+ if (templateText.includes("${") && !templateText.includes(":")) {
+ issues.push({
+ type: "warning",
+ filePath: sourceFile.getFilePath(),
+ line,
+ column,
+ message: "Potential malformed $localize parameter - missing parameter name",
+ code: node.getText(),
+ });
+ }
+
+ // Check for unescaped special characters
+ if (templateText.includes("`") && !templateText.includes("\\`")) {
+ issues.push({
+ type: "warning",
+ filePath: sourceFile.getFilePath(),
+ line,
+ column,
+ message: "Potential unescaped backtick in $localize template",
+ code: node.getText(),
+ });
+ }
+ }
+ }
+ }
+ });
+
+ return issues;
+ }
+
+ /**
+ * Check for missing imports that might be needed
+ */
+ private checkMissingImports(sourceFile: SourceFile): ValidationIssue[] {
+ const issues: ValidationIssue[] = [];
+ const text = sourceFile.getFullText();
+
+ // Check if $localize is used but @angular/localize is not imported
+ if (text.includes("$localize")) {
+ const hasLocalizeImport = sourceFile.getImportDeclarations().some((importDecl) => {
+ const moduleSpecifier = importDecl.getModuleSpecifierValue();
+ return moduleSpecifier.includes("@angular/localize");
+ });
+
+ // Note: $localize is typically a global, but we should check if it needs explicit import
+ if (!hasLocalizeImport && this.needsExplicitLocalizeImport(sourceFile)) {
+ issues.push({
+ type: "info",
+ filePath: sourceFile.getFilePath(),
+ line: 1,
+ column: 1,
+ message: "File uses $localize but may need explicit import in some configurations",
+ });
+ }
+ }
+
+ return issues;
+ }
+
+ /**
+ * Check for TypeScript compilation errors
+ */
+ private checkCompilationErrors(sourceFile: SourceFile): ValidationIssue[] {
+ const issues: ValidationIssue[] = [];
+
+ try {
+ const diagnostics = sourceFile.getPreEmitDiagnostics();
+
+ for (const diagnostic of diagnostics) {
+ const start = diagnostic.getStart();
+ const { line, column } = start
+ ? sourceFile.getLineAndColumnAtPos(start)
+ : { line: 1, column: 1 };
+
+ issues.push({
+ type: "error",
+ filePath: sourceFile.getFilePath(),
+ line,
+ column,
+ message: `TypeScript error: ${diagnostic.getMessageText()}`,
+ });
+ }
+ } catch (error) {
+ // If we can't get diagnostics, add a warning
+ issues.push({
+ type: "warning",
+ filePath: sourceFile.getFilePath(),
+ line: 1,
+ column: 1,
+ message: `Could not check compilation errors: ${error}`,
+ });
+ }
+
+ return issues;
+ }
+
+ /**
+ * Check for potential runtime issues
+ */
+ private checkRuntimeIssues(sourceFile: SourceFile): ValidationIssue[] {
+ const issues: ValidationIssue[] = [];
+
+ sourceFile.forEachDescendant((node) => {
+ if (Node.isTaggedTemplateExpression(node)) {
+ const tag = node.getTag();
+
+ if (Node.isIdentifier(tag) && tag.getText() === "$localize") {
+ const template = node.getTemplate();
+ const { line, column } = sourceFile.getLineAndColumnAtPos(node.getStart());
+
+ if (Node.isTemplateExpression(template)) {
+ const spans = template.getTemplateSpans();
+
+ // Check for complex expressions that might cause runtime issues
+ spans.forEach((span) => {
+ const expression = span.getExpression();
+ const expressionText = expression.getText();
+
+ // Check for function calls in template expressions
+ if (expressionText.includes("(") && expressionText.includes(")")) {
+ issues.push({
+ type: "warning",
+ filePath: sourceFile.getFilePath(),
+ line,
+ column,
+ message: "Complex expression in $localize template may cause runtime issues",
+ code: expressionText,
+ });
+ }
+ });
+ }
+ }
+ }
+ });
+
+ return issues;
+ }
+
+ /**
+ * Generate validation summary
+ */
+ private generateSummary(sourceFiles: SourceFile[], issues: ValidationIssue[]): ValidationSummary {
+ const filesWithIssues = new Set(issues.map((i) => i.filePath)).size;
+ const errors = issues.filter((i) => i.type === "error").length;
+ const warnings = issues.filter((i) => i.type === "warning").length;
+ const info = issues.filter((i) => i.type === "info").length;
+
+ const remainingI18nUsages = issues.filter((i) =>
+ i.message.includes("Remaining I18nService.t() call"),
+ ).length;
+
+ const malformedLocalizeUsages = issues.filter((i) =>
+ i.message.includes("malformed $localize"),
+ ).length;
+
+ const missingImports = issues.filter((i) =>
+ i.message.includes("may need explicit import"),
+ ).length;
+
+ return {
+ totalFiles: sourceFiles.length,
+ filesWithIssues,
+ errors,
+ warnings,
+ info,
+ remainingI18nUsages,
+ malformedLocalizeUsages,
+ missingImports,
+ };
+ }
+
+ /**
+ * Generate validation report
+ */
+ generateReport(result: ValidationResult): string {
+ let report = `# Migration Validation Report\n\n`;
+ report += `**Generated:** ${new Date().toISOString()}\n\n`;
+
+ report += `## Summary\n\n`;
+ report += `- **Total files:** ${result.summary.totalFiles}\n`;
+ report += `- **Files with issues:** ${result.summary.filesWithIssues}\n`;
+ report += `- **Errors:** ${result.summary.errors}\n`;
+ report += `- **Warnings:** ${result.summary.warnings}\n`;
+ report += `- **Info:** ${result.summary.info}\n`;
+ report += `- **Overall status:** ${result.isValid ? "✅ VALID" : "❌ INVALID"}\n\n`;
+
+ report += `## Issue Breakdown\n\n`;
+ report += `- **Remaining I18nService usages:** ${result.summary.remainingI18nUsages}\n`;
+ report += `- **Malformed $localize usages:** ${result.summary.malformedLocalizeUsages}\n`;
+ report += `- **Missing imports:** ${result.summary.missingImports}\n\n`;
+
+ if (result.issues.length > 0) {
+ report += `## Issues by File\n\n`;
+
+ const issuesByFile = result.issues.reduce(
+ (acc, issue) => {
+ if (!acc[issue.filePath]) {
+ acc[issue.filePath] = [];
+ }
+ acc[issue.filePath].push(issue);
+ return acc;
+ },
+ {} as Record,
+ );
+
+ Object.entries(issuesByFile).forEach(([filePath, fileIssues]) => {
+ report += `### ${filePath}\n\n`;
+
+ fileIssues.forEach((issue) => {
+ const icon = issue.type === "error" ? "❌" : issue.type === "warning" ? "⚠️" : "ℹ️";
+ report += `${icon} **Line ${issue.line}:** ${issue.message}\n`;
+ if (issue.code) {
+ report += ` \`${issue.code}\`\n`;
+ }
+ });
+
+ report += `\n`;
+ });
+ }
+
+ return report;
+ }
+
+ /**
+ * Check if a node represents access to I18nService
+ */
+ private isI18nServiceAccess(node: Node): boolean {
+ const text = node.getText();
+ return text.includes("i18nService") || text.includes("i18n") || text.includes("this.i18n");
+ }
+
+ /**
+ * Check if file needs explicit $localize import
+ */
+ private needsExplicitLocalizeImport(sourceFile: SourceFile): boolean {
+ // This is a heuristic - in most Angular setups, $localize is global
+ // But in some configurations, it might need explicit import
+ const text = sourceFile.getFullText();
+
+ // If there are many $localize usages, it might benefit from explicit import
+ const localizeCount = (text.match(/\$localize/g) || []).length;
+ return localizeCount > 5;
+ }
+}
diff --git a/scripts/migration/i18n/typescript/project-parser.ts b/scripts/migration/i18n/typescript/project-parser.ts
new file mode 100644
index 00000000000..59854bbd69d
--- /dev/null
+++ b/scripts/migration/i18n/typescript/project-parser.ts
@@ -0,0 +1,79 @@
+import { Project, SourceFile } from "ts-morph";
+
+import { MigrationConfig } from "../shared/types";
+
+/**
+ * Utility class for parsing TypeScript projects using ts-morph
+ */
+export class ProjectParser {
+ private project: Project;
+
+ constructor(private config: MigrationConfig) {
+ this.project = new Project({
+ tsConfigFilePath: config.tsConfigPath,
+ skipAddingFilesFromTsConfig: false,
+ });
+ }
+
+ /**
+ * Get all source files in the project
+ */
+ getSourceFiles(): SourceFile[] {
+ return this.project.getSourceFiles();
+ }
+
+ /**
+ * Get a specific source file by path
+ */
+ getSourceFile(filePath: string): SourceFile | undefined {
+ return this.project.getSourceFile(filePath);
+ }
+
+ /**
+ * Add a source file to the project
+ */
+ addSourceFile(filePath: string): SourceFile {
+ return this.project.addSourceFileAtPath(filePath);
+ }
+
+ /**
+ * Save all changes to disk
+ */
+ async saveChanges(): Promise {
+ if (!this.config.dryRun) {
+ await this.project.save();
+ }
+ }
+
+ /**
+ * Get the underlying ts-morph Project instance
+ */
+ getProject(): Project {
+ return this.project;
+ }
+
+ /**
+ * Find files that import I18nService
+ */
+ findI18nServiceImports(): SourceFile[] {
+ return this.project.getSourceFiles().filter((sourceFile) => {
+ return sourceFile.getImportDeclarations().some((importDecl) => {
+ const moduleSpecifier = importDecl.getModuleSpecifierValue();
+ return (
+ moduleSpecifier.includes("i18n.service") ||
+ moduleSpecifier.includes("@bitwarden/common/platform/services/i18n.service")
+ );
+ });
+ });
+ }
+
+ /**
+ * Find files that use the i18n pipe in template strings
+ */
+ findI18nPipeUsage(): SourceFile[] {
+ return this.project.getSourceFiles().filter((sourceFile) => {
+ const text = sourceFile.getFullText();
+ return text.includes("| i18n") || text.includes("|i18n");
+ });
+ }
+}
diff --git a/scripts/migration/i18n/typescript/sample-test.ts b/scripts/migration/i18n/typescript/sample-test.ts
new file mode 100644
index 00000000000..e1d5ac6179a
--- /dev/null
+++ b/scripts/migration/i18n/typescript/sample-test.ts
@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+/**
+ * Sample test script to demonstrate the TypeScript migration CLI tool
+ * This script creates sample files and runs the migration tool on them
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+import chalk from "chalk";
+
+import { MigrationConfig } from "../shared/types";
+
+import { BatchMigrator, BatchMigrationOptions } from "./batch-migrator";
+import { MigrationValidator } from "./migration-validator";
+import { TypeScriptMigrator } from "./typescript-migrator";
+
+async function runSampleTest() {
+ console.log(chalk.blue("🧪 Running TypeScript Migration CLI Sample Test"));
+ console.log(chalk.blue("=".repeat(60)));
+
+ // Create temporary test directory
+ const testDir = path.join(__dirname, "sample-test-" + Date.now());
+ fs.mkdirSync(testDir, { recursive: true });
+
+ try {
+ // Create sample TypeScript files
+ await createSampleFiles(testDir);
+
+ // Create tsconfig.json
+ const tsConfigPath = path.join(testDir, "tsconfig.json");
+ fs.writeFileSync(
+ tsConfigPath,
+ JSON.stringify(
+ {
+ compilerOptions: {
+ target: "ES2020",
+ module: "ES2020",
+ lib: ["ES2020", "DOM"],
+ strict: true,
+ esModuleInterop: true,
+ skipLibCheck: true,
+ forceConsistentCasingInFileNames: true,
+ },
+ include: ["**/*.ts"],
+ },
+ null,
+ 2,
+ ),
+ );
+
+ const config: MigrationConfig = {
+ sourceRoot: testDir,
+ tsConfigPath,
+ dryRun: false,
+ verbose: true,
+ };
+
+ // Step 1: Analysis
+ console.log(chalk.yellow("\n📊 Step 1: Analyzing I18nService usage"));
+ const migrator = new TypeScriptMigrator(config);
+ const analysisReport = migrator.generateAnalysisReport();
+ console.log(analysisReport);
+
+ // Step 2: Batch Migration
+ console.log(chalk.yellow("\n🚀 Step 2: Running batch migration"));
+ const batchOptions: BatchMigrationOptions = {
+ config,
+ batchSize: 3,
+ maxConcurrency: 2,
+ outputDir: path.join(testDir, "reports"),
+ createBackups: true,
+ continueOnError: true,
+ };
+
+ const batchMigrator = new BatchMigrator(batchOptions);
+ const migrationResult = await batchMigrator.migrate();
+
+ console.log(chalk.green(`✅ Migration completed:`));
+ console.log(` - Total files: ${migrationResult.totalFiles}`);
+ console.log(` - Successful: ${migrationResult.successfulFiles}`);
+ console.log(` - Failed: ${migrationResult.failedFiles}`);
+ console.log(` - Duration: ${Math.round(migrationResult.duration / 1000)}s`);
+
+ // Step 3: Validation
+ console.log(chalk.yellow("\n🔍 Step 3: Validating migration results"));
+ const validator = new MigrationValidator(config);
+ const validationResult = await validator.validate();
+
+ console.log(chalk.green(`📋 Validation results:`));
+ console.log(` - Valid: ${validationResult.isValid ? "✅ YES" : "❌ NO"}`);
+ console.log(` - Errors: ${validationResult.summary.errors}`);
+ console.log(` - Warnings: ${validationResult.summary.warnings}`);
+ console.log(` - Remaining I18n usages: ${validationResult.summary.remainingI18nUsages}`);
+
+ if (!validationResult.isValid) {
+ console.log(chalk.red("\n❌ Validation issues found:"));
+ validationResult.issues.forEach((issue) => {
+ const icon = issue.type === "error" ? "❌" : issue.type === "warning" ? "⚠️" : "ℹ️";
+ console.log(
+ ` ${icon} ${path.relative(testDir, issue.filePath)}:${issue.line} - ${issue.message}`,
+ );
+ });
+ }
+
+ // Step 4: Show transformed files
+ console.log(chalk.yellow("\n📄 Step 4: Showing transformed files"));
+ await showTransformedFiles(testDir);
+
+ console.log(chalk.green("\n🎉 Sample test completed successfully!"));
+ console.log(chalk.blue(`📁 Test files created in: ${testDir}`));
+ console.log(chalk.blue(`📊 Reports available in: ${path.join(testDir, "reports")}`));
+ } catch (error) {
+ console.error(chalk.red("❌ Sample test failed:"), error);
+ process.exit(1);
+ }
+}
+
+async function createSampleFiles(testDir: string) {
+ const sampleFiles = [
+ {
+ name: "auth.component.ts",
+ content: `
+import { Component } from '@angular/core';
+import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+@Component({
+ selector: 'app-auth',
+ template: '{{ message }}
'
+})
+export class AuthComponent {
+ message: string;
+
+ constructor(private i18nService: I18nService) {}
+
+ ngOnInit() {
+ this.message = this.i18nService.t('loginRequired');
+ }
+
+ showError(count: number) {
+ return this.i18nService.t('errorCount', count.toString());
+ }
+
+ getWelcomeMessage(name: string) {
+ return this.i18nService.t('welcomeMessage', name);
+ }
+}
+ `.trim(),
+ },
+ {
+ name: "vault.service.ts",
+ content: `
+import { Injectable } from '@angular/core';
+import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+@Injectable()
+export class VaultService {
+ constructor(private i18n: I18nService) {}
+
+ getStatusMessage(status: string) {
+ switch (status) {
+ case 'locked':
+ return this.i18n.t('vaultLocked');
+ case 'unlocked':
+ return this.i18n.t('vaultUnlocked');
+ default:
+ return this.i18n.t('unknownStatus', status);
+ }
+ }
+
+ getItemCountMessage(count: number) {
+ if (count === 0) {
+ return this.i18n.t('noItems');
+ } else if (count === 1) {
+ return this.i18n.t('oneItem');
+ } else {
+ return this.i18n.t('multipleItems', count.toString());
+ }
+ }
+}
+ `.trim(),
+ },
+ {
+ name: "settings.component.ts",
+ content: `
+import { Component } from '@angular/core';
+import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+@Component({
+ selector: 'app-settings',
+ templateUrl: './settings.component.html'
+})
+export class SettingsComponent {
+ constructor(private i18nService: I18nService) {}
+
+ getTitle() {
+ return this.i18nService.t('settings');
+ }
+
+ getSaveMessage() {
+ return this.i18nService.t('settingsSaved');
+ }
+
+ getConfirmationMessage(action: string) {
+ return this.i18nService.t('confirmAction', action);
+ }
+}
+ `.trim(),
+ },
+ {
+ name: "utils.ts",
+ content: `
+import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+export class Utils {
+ static formatMessage(i18nService: I18nService, key: string, ...params: string[]) {
+ if (params.length === 0) {
+ return i18nService.t(key);
+ } else if (params.length === 1) {
+ return i18nService.t(key, params[0]);
+ } else {
+ // This is a complex case that might need manual review
+ return i18nService.t(key, ...params);
+ }
+ }
+
+ static getErrorMessage(i18nService: I18nService, errorCode: number) {
+ return i18nService.t('error.' + errorCode.toString());
+ }
+}
+ `.trim(),
+ },
+ {
+ name: "no-i18n.component.ts",
+ content: `
+import { Component } from '@angular/core';
+
+@Component({
+ selector: 'app-no-i18n',
+ template: 'No i18n usage here
'
+})
+export class NoI18nComponent {
+ message = 'This file has no I18nService usage';
+
+ constructor() {}
+
+ getMessage() {
+ return this.message;
+ }
+}
+ `.trim(),
+ },
+ ];
+
+ console.log(chalk.blue("📝 Creating sample files..."));
+
+ for (const file of sampleFiles) {
+ const filePath = path.join(testDir, file.name);
+ fs.writeFileSync(filePath, file.content);
+ console.log(chalk.gray(` Created: ${file.name}`));
+ }
+}
+
+async function showTransformedFiles(testDir: string) {
+ const files = fs.readdirSync(testDir).filter((f) => f.endsWith(".ts") && f !== "sample-test.ts");
+
+ for (const file of files.slice(0, 2)) {
+ // Show first 2 files to avoid too much output
+ const filePath = path.join(testDir, file);
+ const content = fs.readFileSync(filePath, "utf8");
+
+ console.log(chalk.cyan(`\n📄 ${file}:`));
+ console.log(chalk.gray("─".repeat(40)));
+
+ // Show only the relevant parts
+ const lines = content.split("\n");
+ const relevantLines = lines.filter(
+ (line) =>
+ line.includes("$localize") || line.includes("i18nService") || line.includes("import"),
+ );
+
+ relevantLines.forEach((line) => {
+ if (line.includes("$localize")) {
+ console.log(chalk.green(line.trim()));
+ } else if (line.includes("i18nService.t(")) {
+ console.log(chalk.red(line.trim()));
+ } else {
+ console.log(chalk.gray(line.trim()));
+ }
+ });
+ }
+}
+
+// Run the sample test if this file is executed directly
+if (require.main === module) {
+ runSampleTest().catch((error) => {
+ console.error("❌ Sample test failed:", error);
+ process.exit(1);
+ });
+}
+
+export { runSampleTest };
diff --git a/scripts/migration/i18n/typescript/typescript-migrator.spec.ts b/scripts/migration/i18n/typescript/typescript-migrator.spec.ts
new file mode 100644
index 00000000000..3736a9b294b
--- /dev/null
+++ b/scripts/migration/i18n/typescript/typescript-migrator.spec.ts
@@ -0,0 +1,337 @@
+import { Project, SourceFile } from "ts-morph";
+
+import { ASTTransformer } from "./ast-transformer";
+
+describe("TypeScript Migration Tools", () => {
+ let project: Project;
+
+ beforeEach(() => {
+ project = new Project({
+ useInMemoryFileSystem: true,
+ });
+ });
+
+ describe("ASTTransformer", () => {
+ let transformer: ASTTransformer;
+ let sourceFile: SourceFile;
+
+ beforeEach(async () => {
+ transformer = new ASTTransformer();
+ await transformer.initialize();
+
+ // Mock the translation lookup to return predictable results for tests
+ const mockTranslationEntries: Record = {
+ loginWithDevice: { message: "loginWithDevice" },
+ itemsCount: {
+ message: "itemsCount $COUNT$",
+ placeholders: {
+ count: { content: "$1" },
+ },
+ },
+ testMessage: { message: "testMessage" },
+ simpleMessage: { message: "simpleMessage" },
+ itemCount: {
+ message: "itemCount $COUNT$",
+ placeholders: {
+ count: { content: "$1" },
+ },
+ },
+ message1: { message: "message1" },
+ message2: {
+ message: "message2 $PARAM$",
+ placeholders: {
+ param: { content: "$1" },
+ },
+ },
+ };
+
+ jest
+ .spyOn(transformer["translationLookup"], "getTranslation")
+ .mockImplementation((key: string) => {
+ return mockTranslationEntries[key]?.message || null;
+ });
+
+ jest
+ .spyOn(transformer["translationLookup"], "getTranslationEntry")
+ .mockImplementation((key: string) => {
+ return mockTranslationEntries[key] || null;
+ });
+
+ jest
+ .spyOn(transformer["translationLookup"], "hasTranslation")
+ .mockImplementation((key: string) => {
+ return key in mockTranslationEntries;
+ });
+ });
+
+ it("should find I18nService.t() calls", () => {
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ const message = this.i18nService.t('loginWithDevice');
+ const countMessage = this.i18nService.t('itemsCount', count.toString());
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ const usages = transformer.findI18nServiceCalls(sourceFile);
+
+ expect(usages).toHaveLength(2);
+ expect(usages[0].key).toBe("loginWithDevice");
+ expect(usages[0].method).toBe("t");
+ expect(usages[1].key).toBe("itemsCount");
+ expect(usages[1].parameters).toEqual(["count.toString()"]);
+ });
+
+ it("should transform I18nService.t() to $localize but keep import due to constructor usage", () => {
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ const message = this.i18nService.t('loginWithDevice');
+ }
+ }
+ `;
+
+ const expected = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ test() {
+ const message = $localize\`:@@loginWithDevice:loginWithDevice\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should handle parameters in I18nService.t() calls", () => {
+ const code = `
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('itemsCount', count.toString());
+ }
+ }
+ `;
+
+ const expected = `
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@itemsCount:itemsCount \${count.toString()}:count:\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should handle files without I18nService usage", () => {
+ const code = `
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ test() {
+ console.log('no i18n here');
+ }
+ }
+ `;
+
+ const expected = `
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ test() {
+ console.log('no i18n here');
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should remove I18nService import when no longer used", () => {
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('loginWithDevice');
+ }
+ }
+ `;
+
+ const expected = `
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@loginWithDevice:loginWithDevice\`;
+ }
+ }
+ `;
+
+ sourceFile = project.createSourceFile("test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+ });
+
+ describe("Integration Tests", () => {
+ function setupMocks(transformer: ASTTransformer) {
+ const mockTranslationEntries: Record = {
+ loginWithDevice: { message: "loginWithDevice" },
+ itemsCount: {
+ message: "itemsCount $COUNT$",
+ placeholders: {
+ count: { content: "$1" },
+ },
+ },
+ testMessage: { message: "testMessage" },
+ simpleMessage: { message: "simpleMessage" },
+ itemCount: {
+ message: "itemCount $COUNT$",
+ placeholders: {
+ count: { content: "$1" },
+ },
+ },
+ message1: { message: "message1" },
+ message2: {
+ message: "message2 $PARAM$",
+ placeholders: {
+ param: { content: "$1" },
+ },
+ },
+ };
+
+ jest
+ .spyOn(transformer["translationLookup"], "getTranslation")
+ .mockImplementation((key: string) => {
+ return mockTranslationEntries[key]?.message || null;
+ });
+
+ jest
+ .spyOn(transformer["translationLookup"], "getTranslationEntry")
+ .mockImplementation((key: string) => {
+ return mockTranslationEntries[key] || null;
+ });
+
+ jest
+ .spyOn(transformer["translationLookup"], "hasTranslation")
+ .mockImplementation((key: string) => {
+ return key in mockTranslationEntries;
+ });
+ }
+
+ it("should handle complex transformation scenarios", async () => {
+ const transformer = new ASTTransformer();
+ await transformer.initialize();
+ setupMocks(transformer);
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ getMessage() {
+ return this.i18nService.t('simpleMessage');
+ }
+
+ getParameterizedMessage(count: number) {
+ return this.i18nService.t('itemCount', count.toString());
+ }
+
+ getMultipleMessages() {
+ const msg1 = this.i18nService.t('message1');
+ const msg2 = this.i18nService.t('message2', 'param');
+ return [msg1, msg2];
+ }
+ }
+ `;
+
+ const expected = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+ import { Component } from '@angular/core';
+
+ @Component({})
+ class TestComponent {
+ constructor(private i18nService: I18nService) {}
+
+ getMessage() {
+ return $localize\`:@@simpleMessage:simpleMessage\`;
+ }
+
+ getParameterizedMessage(count: number) {
+ return $localize\`:@@itemCount:itemCount \${count.toString()}:count:\`;
+ }
+
+ getMultipleMessages() {
+ const msg1 = $localize\`:@@message1:message1\`;
+ const msg2 = $localize\`:@@message2:message2 \${'param'}:param:\`;
+ return [msg1, msg2];
+ }
+ }
+ `;
+
+ const sourceFile = project.createSourceFile("complex-test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+
+ it("should remove import when only method calls are used (no constructor)", async () => {
+ const transformer = new ASTTransformer();
+ await transformer.initialize();
+ setupMocks(transformer);
+ const code = `
+ import { I18nService } from '@bitwarden/common/platform/services/i18n.service';
+
+ class TestComponent {
+ test() {
+ const message = this.i18nService.t('testMessage');
+ }
+ }
+ `;
+
+ const expected = `
+ class TestComponent {
+ test() {
+ const message = $localize\`:@@testMessage:testMessage\`;
+ }
+ }
+ `;
+
+ const sourceFile = project.createSourceFile("no-constructor-test.ts", code);
+ transformer.transformI18nServiceCalls(sourceFile);
+
+ expect(sourceFile.getFullText().trim()).toBe(expected.trim());
+ });
+ });
+});
diff --git a/scripts/migration/i18n/typescript/typescript-migrator.ts b/scripts/migration/i18n/typescript/typescript-migrator.ts
new file mode 100644
index 00000000000..c1956a6c241
--- /dev/null
+++ b/scripts/migration/i18n/typescript/typescript-migrator.ts
@@ -0,0 +1,181 @@
+/* eslint-disable no-console */
+import { MigrationConfig, TransformationResult, I18nUsage } from "../shared/types";
+
+import { ASTTransformer } from "./ast-transformer";
+import { ProjectParser } from "./project-parser";
+
+/**
+ * Main class for TypeScript code migration from I18nService to $localize
+ */
+export class TypeScriptMigrator {
+ private parser: ProjectParser;
+ private transformer: ASTTransformer;
+
+ constructor(
+ private config: MigrationConfig,
+ private translationsPath?: string,
+ ) {
+ this.parser = new ProjectParser(config);
+ this.transformer = new ASTTransformer();
+ }
+
+ /**
+ * Analyze current I18nService usage across the project
+ */
+ analyzeUsage(): I18nUsage[] {
+ const sourceFiles = this.parser.findI18nServiceImports();
+ const allUsages: I18nUsage[] = [];
+
+ sourceFiles.forEach((sourceFile) => {
+ const usages = this.transformer.findI18nServiceCalls(sourceFile);
+ allUsages.push(...usages);
+ });
+
+ return allUsages;
+ }
+
+ /**
+ * Generate analysis report of current usage patterns
+ */
+ generateAnalysisReport(): string {
+ const usages = this.analyzeUsage();
+ const fileCount = new Set(usages.map((u) => u.filePath)).size;
+ const keyCount = new Set(usages.map((u) => u.key)).size;
+
+ let report = `# I18nService Usage Analysis Report\n\n`;
+ report += `## Summary\n`;
+ report += `- Total usage count: ${usages.length}\n`;
+ report += `- Files affected: ${fileCount}\n`;
+ report += `- Unique translation keys: ${keyCount}\n\n`;
+
+ report += `## Usage by File\n`;
+ const usagesByFile = usages.reduce(
+ (acc, usage) => {
+ if (!acc[usage.filePath]) {
+ acc[usage.filePath] = [];
+ }
+ acc[usage.filePath].push(usage);
+ return acc;
+ },
+ {} as Record,
+ );
+
+ Object.entries(usagesByFile).forEach(([filePath, fileUsages]) => {
+ report += `\n### ${filePath}\n`;
+ fileUsages.forEach((usage) => {
+ report += `- Line ${usage.line}: \`${usage.key}\``;
+ if (usage.parameters) {
+ report += ` (with parameters: ${usage.parameters.join(", ")})`;
+ }
+ report += `\n`;
+ });
+ });
+
+ report += `\n## Most Common Keys\n`;
+ const keyCounts = usages.reduce(
+ (acc, usage) => {
+ acc[usage.key] = (acc[usage.key] || 0) + 1;
+ return acc;
+ },
+ {} as Record,
+ );
+
+ Object.entries(keyCounts)
+ .sort(([, a], [, b]) => b - a)
+ .slice(0, 10)
+ .forEach(([key, count]) => {
+ report += `- \`${key}\`: ${count} usage(s)\n`;
+ });
+
+ return report;
+ }
+
+ /**
+ * Migrate all TypeScript files in the project
+ */
+ async migrateAll(): Promise {
+ await this.transformer.initialize(this.translationsPath);
+
+ const sourceFiles = this.parser.findI18nServiceImports();
+ const results: TransformationResult[] = [];
+
+ if (this.config.verbose) {
+ console.log(`Found ${sourceFiles.length} files with I18nService imports`);
+ }
+
+ for (const sourceFile of sourceFiles) {
+ if (this.config.verbose) {
+ console.log(`Processing: ${sourceFile.getFilePath()}`);
+ }
+
+ const result = this.transformer.transformI18nServiceCalls(sourceFile);
+ results.push(result);
+
+ if (!result.success) {
+ console.error(`Failed to process ${result.filePath}:`, result.errors);
+ }
+ }
+
+ // Save changes if not in dry run mode
+ if (!this.config.dryRun) {
+ await this.parser.saveChanges();
+ }
+
+ return results;
+ }
+
+ /**
+ * Migrate a specific file
+ */
+ async migrateFile(filePath: string): Promise {
+ await this.transformer.initialize(this.translationsPath);
+
+ const sourceFile = this.parser.getSourceFile(filePath);
+
+ if (!sourceFile) {
+ return {
+ success: false,
+ filePath,
+ changes: [],
+ errors: [`File not found: ${filePath}`],
+ };
+ }
+
+ const result = this.transformer.transformI18nServiceCalls(sourceFile);
+
+ if (!this.config.dryRun && result.success) {
+ await this.parser.saveChanges();
+ }
+
+ return result;
+ }
+
+ /**
+ * Generate migration statistics
+ */
+ generateMigrationStats(results: TransformationResult[]): string {
+ const successful = results.filter((r) => r.success).length;
+ const failed = results.filter((r) => !r.success).length;
+ const totalChanges = results.reduce((sum, r) => sum + r.changes.length, 0);
+
+ let stats = `# Migration Statistics\n\n`;
+ stats += `- Files processed: ${results.length}\n`;
+ stats += `- Successful: ${successful}\n`;
+ stats += `- Failed: ${failed}\n`;
+ stats += `- Total changes: ${totalChanges}\n\n`;
+
+ if (failed > 0) {
+ stats += `## Failed Files\n`;
+ results
+ .filter((r) => !r.success)
+ .forEach((result) => {
+ stats += `- ${result.filePath}\n`;
+ result.errors.forEach((error) => {
+ stats += ` - ${error}\n`;
+ });
+ });
+ }
+
+ return stats;
+ }
+}