RepoTransAgent: Repo-Aware Code Translation

• RepoTransAgent is a repository-aware framework that translates code by integrating context retrieval, dynamic prompting, and iterative repair.
• It decomposes translation into specialized tasks (context retrieval, dynamic prompt construction, and error-driven refinement) to handle global repository dependencies.
• Empirical results on Java↔C# projects show significant improvements in compile and pass rates compared to baseline models.

RepoTransAgent is a multi-agent LLM framework for repository-aware code translation, introduced to translate code between programming languages in the context of a full software repository rather than as isolated snippets (Guan et al., 25 Aug 2025). In this setting, correctness depends not only on local syntax but also on surrounding class fields, method signatures, imported classes and namespaces, repository-specific APIs, invocation relationships, implementation differences between source and target repositories, and tests that determine whether the translated function actually works (Guan et al., 25 Aug 2025). The framework decomposes translation into specialized subtasks—context retrieval, dynamic prompt construction, and iterative code refinement—handled by dedicated agents, and is evaluated on Java↔C# translation pairs from six open-source projects, where it reaches up to 55.34% compile rate and 45.84% pass rate (Guan et al., 25 Aug 2025).

1. Repository-aware code translation as a software engineering problem

RepoTransAgent is motivated by the claim that repository-aware translation is fundamentally different from ordinary code translation because real repositories impose global dependency structure and execution constraints that are absent in snippet-level settings (Guan et al., 25 Aug 2025). A function may depend on repository-local conventions, target-side replacements for source-side calls, imported classes, class fields, and differently organized utility code, so translating an isolated file or method is often insufficient (Guan et al., 25 Aug 2025). The paper explicitly states that prior work has focused mainly on isolated functions or small snippets and “systematically overlook[ed] the global dependencies and complex invocation relationships that characterize large-scale software repositories” (Guan et al., 25 Aug 2025).

This problem formulation aligns with broader benchmark evidence on repository-level translation. RepoTransBench defines repository-level code translation as translating an entire repository while preserving functionality, including functional code files, test code files, resource files, and configuration or build files (Wang et al., 2024). It reports that even the best-performing one-shot model achieves only 7.33% Success@1, and that iterative debugging raises the best Success@1 only to 21%, which the paper says may not meet the need for reliable automatic repository-level translation (Wang et al., 2024). RepoGenesis reaches a similar conclusion for README-to-repository microservice generation: despite API Coverage up to 73.91% and Deployment Success Rate up to 100%, the best Pass@1 remains 23.67% on Python and 21.45% on Java, with deficiencies concentrated in architectural coherence, dependency management, and cross-file consistency (Peng et al., 20 Jan 2026). This suggests that RepoTransAgent belongs to a broader class of systems for long-horizon repository engineering rather than conventional code translation alone.

2. Framework architecture and agent decomposition

RepoTransAgent uses three main agents: a RAG Agent, a Context Agent, and a Refine Agent (Guan et al., 25 Aug 2025). The RAG Agent retrieves semantically similar source-target translation pairs and target-repository functions with similar names; the Context Agent gathers repository-specific context through tool use; and the Refine Agent performs initial translation, runs tests, reflects on failures, and iteratively repairs outputs (Guan et al., 25 Aug 2025). The paper’s stated rationale is that repository-aware translation includes similarity retrieval, dependency and context discovery, prompt adaptation, code generation, and debugging or repair, which are better modularized than handled in a single prompt (Guan et al., 25 Aug 2025).

The end-to-end workflow begins with three inputs: the source function body, the target function signature, and repository metadata (Guan et al., 25 Aug 2025). The RAG Agent first decides whether retrieval is needed; the Context Agent then uses dynamic prompts and tool invocation to collect repository context; the Refine Agent generates translated code; and the resulting function is compiled and tested in the target repository (Guan et al., 25 Aug 2025). If validation succeeds, translation terminates; otherwise the framework gathers diagnostics, performs reflection, may retrieve additional context related to the error, and repeats until tests pass or the maximum iteration limit is reached (Guan et al., 25 Aug 2025). The paper explicitly mentions a maximum iteration limit but does not disclose its numeric value (Guan et al., 25 Aug 2025).

The multi-agent decomposition is a core design claim rather than an incidental implementation detail. A related result from ReCodeAgent, which addresses language-agnostic repository-level translation and validation, supports this kind of staged decomposition: removing analysis, planning, or validation agents substantially reduces test validation performance, and replacing the multi-agent architecture with single-agent prompt condensation or concatenation causes large drops in test pass rate and longer, less efficient trajectories (Ibrahimzada et al., 8 Apr 2026). This suggests that RepoTransAgent’s division of labor is part of a broader architectural trend in repository-level translation systems rather than a task-specific optimization.

3. Context retrieval and repository modeling

A major contribution of RepoTransAgent is its treatment of repository context as selectively retrieved evidence rather than a monolithic prompt (Guan et al., 25 Aug 2025). The paper explicitly lists the kinds of context it retrieves: source class information, including field definitions and method signatures in the class containing the source function; target class information of the class containing the target function; target imports from the file containing the target function; specific target class information, including field definitions and method signatures of a searched class in the target repository; and specific target method bodies, including the full method signature and body for a method in a target-side class (Guan et al., 25 Aug 2025). This context is intended to expose API availability, class structure, dependency mappings, target-side replacements for source-side calls, and repository-specific implementation differences (Guan et al., 25 Aug 2025).

The RAG Agent preprocesses repository metadata into two separate vector stores: a pair store containing method bodies of all source-target translation pairs, and a name store containing function names of all methods in the target repository (Guan et al., 25 Aug 2025). If retrieval is deemed necessary, RepoTransAgent uses two retrieval paths. The first retrieves similar source-target pairs using dense retrieval with cosine similarity and sparse retrieval with BM25, then fuses the ranked lists with Reciprocal Rank Fusion. The second retrieves target-side functions with similar names using BM25, with exact name matches forced to similarity score 1.0 (Guan et al., 25 Aug 2025). The merged results are then filtered by functional similarity, structural resemblance, and referenced context (Guan et al., 25 Aug 2025).

The paper is equally clear about what it does not specify. It does not report the embedding model, vector database product, exact top-$k$, chunk size, truncation strategy under token limits, or a formal RRF equation (Guan et al., 25 Aug 2025). Nor does it state that build metadata, README content, test code as prompt context, comments as first-class retrieval units, or class hierarchy graphs are retrieved (Guan et al., 25 Aug 2025). The retrieval design is therefore intentionally selective and operational rather than exhaustively repository-representative.

This selective retrieval orientation contrasts with structure-first systems such as RepoMaster, which preprocess a repository into a Hierarchical Code Tree $\mathcal{T}$, a Function Call Graph $G_f$, and a Module Dependency Graph $G_m$, then score modules and classes for context entry (Wang et al., 27 May 2025). RepoMaster formalizes a repository as

$\mathcal{R}= \langle M, C, F, \mathcal{I} \rangle$

and constructs a full structural synopsis

$$\bigl\langle M,C,F,\mathcal{I},G_f,G_m,\mathcal{T} \bigr\rangle$$

before exploration (Wang et al., 27 May 2025). RepoTransAgent explicitly criticizes static-analysis-based context retrieval such as call graphs and dependency graphs as hard for LLMs to interpret, potentially noisy or redundant, and brittle when code structures or external dependencies change (Guan et al., 25 Aug 2025). A plausible implication is that RepoTransAgent prioritizes directly consumable repository evidence over full structural precomputation.

4. Dynamic prompting and tool-mediated interaction

RepoTransAgent uses dynamic and adaptive prompting rather than a fixed prompt template (Guan et al., 25 Aug 2025). Its prompt structure has static components—Goals, Tools, Guidelines, Example, and Output Format—and dynamic components—Input, Gathered Context, and Last Command (Guan et al., 25 Aug 2025). The dynamic fields evolve during interaction, allowing the agent to condition later decisions on repository state and prior tool results rather than recomputing from scratch (Guan et al., 25 Aug 2025).

For the Context Agent, prompts instruct the model to prioritize three tools first: get_source_class_info, get_target_class_info, and find_target_imports (Guan et al., 25 Aug 2025). Only after gathering this basic information does the agent use find_target_class_info and find_target_method_body to drill into dependencies, interfaces, namespace or package mappings, and implementation details (Guan et al., 25 Aug 2025). The agent must output strict JSON with id, name, and args, with no extra text (Guan et al., 25 Aug 2025). The Last Command field is explicitly described as helping the agent avoid repeated or redundant tool calls and reflect on whether its strategy is working (Guan et al., 25 Aug 2025).

The Refine Agent also uses stage-sensitive prompts. For initial generation, the prompt includes the source function body, target function signature, repository context collected by the Context Agent, and similar functions retrieved by the RAG Agent (Guan et al., 25 Aug 2025). In correction rounds, the prompt is augmented with the previous erroneous code, test execution results, and the reflection or correction strategy (Guan et al., 25 Aug 2025). This means prompting adapts both to repository structure and to translation stage: first-pass generation and repair are different prompt states rather than a single repeated template (Guan et al., 25 Aug 2025).

The paper describes prompt sections conceptually but does not print full templates verbatim, and it does not provide an ablation isolating dynamic prompting alone from the rest of the architecture (Guan et al., 25 Aug 2025). This leaves the exact contribution of prompt adaptation inseparable from the larger multi-agent workflow. However, related work on repository-level bug localization shows a similar benefit from stage-specific reformulation: in "Reformulate, Retrieve, Localize," an agent improves file-level localization by first extracting Explanation, Identifiers, and Code Snippets from bug reports, then using these structured queries with BM25 before downstream agent reasoning (Caumartin et al., 7 Dec 2025). That paper argues that the main bottleneck is often getting the right candidate files into view early, not merely reasoning harder after poor retrieval (Caumartin et al., 7 Dec 2025). RepoTransAgent’s prompt design fits this broader pattern of repository tasks benefiting from upstream context shaping.

5. Reflection, repair, and execution feedback

The Refine Agent is responsible for both initial translation and iterative correction (Guan et al., 25 Aug 2025). After translation, the generated function is validated in the target repository, and failures are categorized into four types: Compilation errors, Test failures, Runtime errors, and Non-terminating execution (Guan et al., 25 Aug 2025). For each category, the system collects error logs, error type, output messages, and exact error locations (Guan et al., 25 Aug 2025). Reflection then asks the agent to analyze the relation among the source function, target function signature, generated erroneous code, and execution results so that it can identify what failed, why it failed, and what correction strategy should be applied (Guan et al., 25 Aug 2025).

This reflection stage is central to the paper’s argument that raw test feedback alone is too weak (Guan et al., 25 Aug 2025). The repair phase uses prior code, test results, reflection, and updated repository context to produce an improved translation, and the agent may reinvoke tools to gather context closely related to the identified errors (Guan et al., 25 Aug 2025). The loop continues until all tests pass or the iteration limit is reached (Guan et al., 25 Aug 2025).

The empirical motivation for this repair architecture is consistent with benchmark findings from RepoTransBench, which reports that iterative debugging with error-related feedback improves Success@1 by an average of 7.09% across evaluated LLMs and raises GPT-4o from 4% to 21% Success@1 on repository-level Python→Java translation (Wang et al., 2024). RepoTransBench’s error taxonomy—configuration file issues, limited repository understanding, incomplete generation, language feature mismatches, and encoding issues—closely matches the kinds of problems that RepoTransAgent’s Refine Agent is designed to address (Wang et al., 2024). The case study in RepoTransAgent makes this concrete: the agent discovers that the target repository imports CellPropertyType rather than CellUtil, and that the target CellAddress class lacks calculateCount but contains collectCount, then uses semantic reasoning to translate cell.CalculateCount to cell.collectCount (Guan et al., 25 Aug 2025). This is not a syntax-level repair but a repository-specific API mapping.

A plausible implication is that RepoTransAgent’s core strength lies less in first-pass translation than in coupling translation to repository-grounded debugging. This interpretation is reinforced by the ablation results discussed below.

6. Experimental evaluation and comparative performance

RepoTransAgent is evaluated on six popular open-source GitHub projects with both Java and C# implementations: lucene, poi, jgit, itext, quartz, and rocketmq-clients (Guan et al., 25 Aug 2025). Following the methodology of Methods2Test, the authors extract Java–C# translation pairs that include corresponding test cases (Guan et al., 25 Aug 2025). In the main experiments, the total translated functions are 627 for C#→Java and 655 for Java→C# (Guan et al., 25 Aug 2025). The baselines are No Agent, UniTrans, and PLTranslation, with prompts adapted for repository-aware translation (Guan et al., 25 Aug 2025).

The framework is implemented in Python with LangChain and evaluated with Llama 3.1 8B, Llama 3.1 70B, Qwen2.5 7B, Qwen2.5 72B, GPT-4o-mini, and DeepSeek V3 (Guan et al., 25 Aug 2025). For the main baseline comparison, DeepSeek V3 is used with consistent parameters across methods (Guan et al., 25 Aug 2025). The paper gives one especially salient decoding detail: temperature is 0 for the RAG Agent and Context Agent, and 0.8 for the Refine Agent, on the rationale that retrieval and context decisions should be stable while repair benefits from some diversity (Guan et al., 25 Aug 2025).

The headline results are strongest for C#→Java. RepoTransAgent achieves 55.34% compile rate and 45.84% pass rate, compared with 26.07% / 18.59% for No Agent, 30.36% / 25.33% for UniTrans, and 30.47% / 28.16% for PLTranslation (Guan et al., 25 Aug 2025). For Java→C#, RepoTransAgent reaches 43.07% compile rate and 32.36% pass rate, versus 14.03% / 9.44%, 14.30% / 10.94%, and 19.53% / 12.04% for the same baselines (Guan et al., 25 Aug 2025). In absolute terms with DeepSeek V3, the system compiles 363 and passes 299 of 627 C#→Java functions, and compiles 306 and passes 245 of 655 Java→C# functions (Guan et al., 25 Aug 2025).

Per-project results show gains across all six projects. For example, in C#→Java pass rate, RepoTransAgent reaches 36.29% on lucene, 58.52% on poi, 35.82% on jgit, 61.19% on itext, 57.14% on quartz, and 26.19% on rocketmq-clients, each exceeding all three baselines (Guan et al., 25 Aug 2025). In Java→C#, it reaches 57.73% on poi, 54.29% on itext, 36.00% on quartz, and 14.00% on rocketmq-clients, again outperforming the baselines (Guan et al., 25 Aug 2025).

The ablation study is particularly informative. Removing the RAG Agent reduces compile and pass rates to 51.39% and 42.94%; removing the Context Agent reduces them to 36.87% and 32.20%; and removing the Refine Agent reduces them to 34.81% and 26.50% (Guan et al., 25 Aug 2025). This indicates that repository context retrieval and iterative repair are much more consequential than retrieval of analogous examples alone (Guan et al., 25 Aug 2025). The paper interprets the RAG Agent as helpful especially when overloaded functions or close analogues exist, but less central than the other components because sufficiently similar functions are often hard to retrieve (Guan et al., 25 Aug 2025).

Two comparative perspectives sharpen these results. First, RepoTransBench reports that even with iterative debugging, the best repository-level translation systems remain far below reliable automation, suggesting that RepoTransAgent’s results represent substantial but still partial progress (Wang et al., 2024). Second, ReCodeAgent later generalizes the repository-translation problem across six languages and four language pairs, reaching 99.4% compilation success and 86.5% pass rate on validated developer tests across 118 projects, but with a heavier analysis–planning–translation–validation workflow, target-project skeletons, and explicit translation-unit extraction (Ibrahimzada et al., 8 Apr 2026). This suggests that RepoTransAgent occupies an intermediate point: stronger than basic test-guided translators, but less structurally elaborate than later language-agnostic repository translation systems.

7. Limitations, scope, and relation to adjacent repository-agent research

RepoTransAgent is explicitly evaluated only on Java and C# (Guan et al., 25 Aug 2025). The repositories also contain parallel implementations and aligned tests, which is an important structural assumption: the source and target repositories are related enough that method pairs and tests can be aligned (Guan et al., 25 Aug 2025). The paper does not report train/dev/test splits, exact pair-alignment procedures, top-$k$ retrieval values, context-window limits, full decoding settings beyond temperatures, prompt token lengths, compiler versions, or execution timeout thresholds (Guan et al., 25 Aug 2025). A possible concern is data leakage, which the authors probe by exact matching after removing line breaks, comments, and whitespace; only 19.40% of successful C#→Java and 13.06% of successful Java→C# translations are exact matches, which they interpret as suggesting low leakage risk (Guan et al., 25 Aug 2025).

The error analysis identifies Compilation Errors as the dominant failure mode: 264 / 349 failures in C#→Java and Java→C# respectively are compilation-related, with “symbol not found” as the most frequent specific issue (Guan et al., 25 Aug 2025). This supports the paper’s central claim that repository-specific contextual differences are the main bottleneck rather than pure syntactic translation (Guan et al., 25 Aug 2025). The framework also works much better on larger models than on smaller ones; the authors attribute this to weaker tool invocation and context gathering in smaller models, and to difficulty handling longer prompts (Guan et al., 25 Aug 2025).

RepoTransAgent also invites comparison with work on repository reasoning rather than translation per se. RepoMirage argues that end-to-end benchmark success can overstate genuine repository context reasoning and shows that code agents often suffer from “exploration drift,” accessing more files without converting that access into effective structural understanding (Li et al., 25 May 2026). RepoAnchor, proposed in that paper, suggests a structure-first workflow that separates repository exploration from downstream problem solving (Li et al., 25 May 2026). A plausible implication is that RepoTransAgent could benefit from a stronger explicit structural intermediate representation, especially because its current design emphasizes targeted retrieval and tool use rather than persistent structure synthesis.

Likewise, RepoMaster provides an explicit repository synopsis—hierarchical tree, call graph, dependency graph—and shows strong gains for repository reuse and adaptation under context limits (Wang et al., 27 May 2025). RepoAgent, in turn, shows that repository-wide AST parsing, reference extraction via Jedi, and bottom-to-top processing can support repository-scale documentation generation and maintenance (Luo et al., 2024). These systems are not translation frameworks, but they indicate that repository-aware agents often benefit from durable graph- or tree-based internal representations that RepoTransAgent does not foreground.

At the systems level, Repo2Run and BootstrapAgent highlight another adjacent concern: many repository-level tasks depend on reliably bootstrapping an executable environment. Repo2Run frames environment configuration as a transactional, rollback-supported search process over Dockerized Python repositories and achieves 86.0% Environment Configuration Success Rate on 420 repositories (Hu et al., 19 Feb 2025). BootstrapAgent turns repository setup into a persistent .bootstrap contract and reaches 92.9% clean-replay bootstrap success rate across three benchmarks (Fu et al., 15 May 2026). RepoTransAgent assumes target repositories with available tests and toolchains rather than solving environment construction itself. This suggests that for broader deployment, translation frameworks may need to integrate with environment-setup systems rather than treat execution as a solved prerequisite.

In sum, RepoTransAgent is best characterized as a repository-aware multi-agent translation framework whose defining contribution is the integration of selective repository context retrieval, adaptive prompt construction, and reflection-driven iterative repair for Java↔C# translation (Guan et al., 25 Aug 2025). It outperforms contemporaneous repository-aware translation baselines by large margins on compile and pass rates, but it remains bounded by language scope, aligned-repository assumptions, and the continuing difficulty of compilation-heavy, cross-file translation errors (Guan et al., 25 Aug 2025). Its broader significance lies in demonstrating that repository-level translation is most tractable when treated as an orchestrated software-engineering workflow rather than as isolated code generation (Guan et al., 25 Aug 2025).